api.raml

#%RAML 0.8

title: GeoRenting
baseUri: https://georenting.herokuapp.com/{version}
version: v1
protocols: [HTTPS]

schemas:
  - Fence: !include schema/fence.json

securitySchemes:
  - x-jean-auth:
      type: x-Jean-Auth
      description: Some requests require authentication. Jean-Auth uses a JSON Web Token in a Header to prove the Identity of the user.
      describedBy:
        headers:
          Authorization:
            description: |
              Used to send a valid Jean-Auth Token.
            type: string
        responses:
          401:
            description: |
              Bad or expired token. Reauthenticate the user.
          403:
            description: |
              Things are going bad for you. Reauthenticating won't help here.

documentation:
  - title: Home
    content: |
      Welcome to the GeoRenting API. This is WIP. Please use me gently.
  - title: Auth
    content: |
      The GeoRenting API uses JSON Web Tokens for authentication. You will get
      one through the Sign In API Call. You need a Google Account Token to login.
      Authenticated API calls require the token you get after login to be sent in a
      Authorization header.
  - title: GCM
    content: |
      The API will leverage Google Butt Messaging to notify the user of specific events.

      <img src="art/comm.jpg" style="width: 700px" />

/application:
  /upgrades:
    get:
      description: Gives you information about the currently possible Upgrade Levels of GeoFences.
      responses:
        200:
          description: Returns the Information about Upgrade Levels. Radius in Meters, Max TTL in Seconds.
          body:
            application/json:
              example: |
                {
                  "min_radius": 100,
                  "max_radius": 400,
                  "radius": [
                    100, 150, 200, 250, 300, 350, 400
                  ],
                  "rent": [
                    1, 1.5, 2, 2.5, 3, 3.5, 4
                  ],
                  max_ttl: 604800,
                  min_ttl: 10
                }
/users:
  get:
   queryParameters:
     name:
       description: Filter the users by name.
  /refreshToken:
    post:
      description: Refreshes a Session for a given user. Requires an existing session Token.
      body:
        application/json:
          example: |
            {
              "token": "asdasdasd.asdasd98asd987.asd89a7"
            }
      responses:
        200:
          description: Returns the JWT Token.
          body:
            application/json:
              example: |
                {
                  "token": "asdaisdansd.asdiu088ur98uasd.oaisd982"
                  "user": UserObject
                }
        403:
          description: You sent an invalid JWT token.
  /auth:
    post:
      description: Authenticate the User. Requires a Google OAuth Token.
      body:
        application/json:
          example: |
            {
              "google_token": "AAAJJJDDDDEEEE"
            }
      responses:
        200:
          description: Returns the JWT token.
          body:
            application/json:
              example: |
                {
                  "token": "asdaisdansd.asdiu088ur98uasd.oaisd982"
                  "user": UserObject
                }
        403:
          description: You sent an invalid Google OAuth token.
    delete:
      securedBy: [x-jean-auth]
      description: Delete the session.
      body:
        application/json:
          example: |
            {
              "token": "asdasdasd.asdpiajsdohuds9f8asdf.asdiasjdo"
            }
      responses:
        200:
          body:
            application/json:
              example: |
                {}
  /me:
    get:
      description: Returns information about the currently signed in User.
      securedBy: [x-jean-auth]
      responses:
        200:
          description: Returns the JWT token.
          body:
            application/json:
              example: |
                UserObject
        403:
          description: You sent an invalid Google OAuth token.
    /cash:
      get:
        description: Returns information about the CashFlow of the user in the last 7 days and all time.
        securedBy: [x-jean-auth]
        responses:
          200:
            body:
              application/json:
                example: |
                  {
                    "earnings_rent_7d": 100.0,
                    "expenses_rent_7d": 10.0,
                    "expenses_geofence_7d": 100.0,
                    "earnings_rent_all": 10000.0,
                    "expenses_rent_all": 2342090.0,
                    "expenses_geofence_all": 3909090.0
                  }
          403:
            description: The user is not authorized to access this.
    /history:
      get:
        description: Returns the Activity stream of the User.
        securedBy: [x-jean-auth]
        responses:
          200:
            body:
              application/json:
                example: |
                  [{
                    'verb': 'ownFenceVisited',
                    'date': 2255555555
                    'data': {
                      'visitor': 'Ulf',
                      'fence': 'Pedas Castle',
                      'rent': 200
                    }
                  }, {
                    'verb': 'foreignFenceVisited',
                    'date': 2255555557
                    'data': {
                      'owner': 'Friedhelm',
                      'fence': 'Friedhelms Area',
                      'rent': 10
                    }
                  }]
          403:
            description: The user is not authorized to access this.
    /gcm:
      post:
        description: Add a GCM ID.
        securedBy: [x-jean-auth]
        body:
          application/json:
            example: |
              {
                "gcm_id": "42ua0sd8n"
              }
      delete:
        description: Remove a GCM ID.
        securedBy: [x-jean-auth]
        body:
          application/json:
            example: |
              {
                "gcm_id": "42ua0sd8n"
              }
        responses:
          200:
            body:
              application/json:
                example: |
                  {}
          403:
            description: The user is not authorized to do this.
          401:
            description: The specified GCM ID could not be deleted.
/scores:
  /heatmap:
    get:
      description: Returns data for generating a HeatMap of score values.
      responses:
        200:
          body:
            application/json:
              example: |
                [{
                  lat: 54.01,
                  lon: 8.2,
                  score: 2
                }, {
                  lat: 42.1,
                  lon: 1.3,
                  score: 10
                }]
/fences:
  get:
    description: Get Fences by user or around a center location. Returns more Information if the fence is owned by the current user.
    queryParameters:
      user:
        type: string
        description: Get all Fences owned by the specified User ID.
        required: false
      latitude:
        type: number
        description: Get Fences near the specified center location. Requires longitude and radius.
      longitude:
        type: number
        description: Get Fences near the specified center location. Requires latitude and radius.
      radius:
        type: integer
        description: Get Fences near the specified center location. Requires latitude and longitude.
      excludeOwn:
        type: boolean
        description: Exclude GeoFences owned by the current user from the search. Requires Authorization, otherwise will be ignored.
    responses:
      200:
        body:
          application/json:
            schema: Fence
            example: |
              [
                {
                  "id": 42
                  "center_lon": 54.42,
                  "center_lat": 8.5,
                  "name": "Ulfs Castle",
                  "radius": 200,
                  "total_visitors": 23,
                  "total_earnings": 55.31,
                  "cost": 500.32,
                  "dies_at": 14588879,
                  "rent_multiplier": 1.5
                },
                {
                  "id": 45
                  "center_lon": 51.42,
                  "center_lat": 4.5,
                  "name": "Pedas House",
                  "radius": 100,
                  "total_visitors": 23,
                  "total_earnings": 55.31,
                  "cost": 500.32,
                  "dies_at": 14588879,
                  "rent_multiplier": 1.5
                }
              ]
  post:
    description: Create the GeoFence. TTL has to be smaller than MaxTLL, RentMultiplier and Radius have to be valid Values from GET /application/upgrades.
    securedBy: [x-jean-auth]
    body:
      application/json:
        schema: Fence
        example: |
          {
            "center_lon": 54.42,
            "center_lat": 8.5,
            "ttl": 1024,
            "rent_multiplier": 1.5,
            "radius": 150
            "name": "Ulfs Castle"
          }
    responses:
      200:
        body:
          application/json:
            schema: Fence
            example: |
              {
                "id": "42",
                "center_lon": 54.42,
                "center_lat": 8.5,
                "name": "Ulfs Castle",
                "dies_at": 14588879,
                "rent_multiplier": 1.5,
                "radius": 150
              }
      402:
        description: The user does not have enough GeoCoins.
      400:
        description: The GeoFence is overlapping with another GeoFence in its radius.
      417:
        description: Upgrade Values not valid.
  /estimateCost:
    post:
      description: Returns a price estimate for creating a GeoFence at the given location. TTL has to be smaller than MaxTLL, RentMultiplier and Radius have to be valid Values from GET /application/upgrades.
      securedBy: [x-jean-auth]
      body:
        application/json:
          schema: Fence
          example: |
            {
              "center_lon": 54.42,
              "center_lat": 8.5,
              "ttl": 1024,
              "rent_multiplier": 1.5,
              "radius": 150
            }
      responses:
        200:
          body:
            application/json:
              schema: CostEstimate
              example: |
                {
                  "cost": 100,
                  "can_afford": true
                }
        400:
          description: The GeoFence is overlapping with another GeoFence in its radius.
        417:
          description: Upgrade Values not valid.
  /{fenceId}:
    get:
      description: Get information about the GeoFence.
      responses:
        200:
          body:
            application/json:
              schema: Fence
              example: |
                {
                  "id": "42",
                  "center_lon": 54.42,
                  "center_lat": 8.5,
                  "name": "Ulfs Castle",
                  "radius": 200
                }
        404:
          description: Not found.
    put:
      description: Update the GeoFence. Requires the user to be the owner of it.
      securedBy: [x-jean-auth]
      responses:
        200:
          body:
            application/json:
              schema: Fence
              example: |
                {
                  "id": "42",
                  "center_lon": 54.42,
                  "center_lat": 8.5,
                  "name": "Ulfs Castle",
                  "radius": 100
                }
        404:
          description: Not Found.
        403:
          description: The current user is not authorized to update that fence.
      body:
        application/json:
          schema: Fence
          example: |
            {
              "id": "42",
              "center_lon": 54.42,
              "center_lat": 8.5,
              "name": "Ulfs Castle"
            }
    delete:
      description: Delete the GeoFence. Requires the user to be the owner of it.
      securedBy: [x-jean-auth]
      responses:
        200:
          body:
            application/json:
              example: |
                {}
        404:
          description: Not Found.
        403:
          description: The current user is not authorized to delete the fence.
    /visit:
      post:
        securedBy: [x-jean-auth]
        description: |
          This method will visit a GeoFence. The visitor and the owner will be notified
          via GCM.