c3.raml

#%RAML 0.8
---
title: C3 Beacon
baseUri: http://api.c3wireless.com/{version}
version: v2
securitySchemes:
    - oauth_2_0:
        description: |
            C3 supports OAuth 2.0 for authenticating all API requests.
        type: OAuth 2.0
        describedBy:
            headers:
                Authorization:
                    description: |
                       Used to send a valid OAuth 2 access token. Do not use
                       with the "access_token" query string parameter.
                    type: string
            queryParameters:
                access_token:
                    description: |
                       Used to send a valid OAuth 2 access token. Do not use together with
                       the "Authorization" header
                    type: string
            responses:
                401:
                    description: |
                        Bad or expired token. This can happen if the user or C3
                        revoked or expired an access token. To fix, you should re-
                        authenticate the user.
                403:
                    description: |
                        Bad OAuth request (wrong consumer key, bad nonce, expired
                        timestamp...). Unfortunately, re-authenticating the user won't help here.
        settings:
          authorizationUri: https://{baseUri}/oauth2/authorize
          accessTokenUri: https://{baseUri/oauth2/token
          authorizationGrants: [ code, token ]
resourceTypes:
  - collection:
      description: Collection of available <<resourcePathName>>
      get:
        description: Get a list of <<resourcePathName>>
        body:
          application/json:
          text/html:
            example: null
        responses:
          200:
            body:
              application/json:
                schema: <<resourcePathName>>
                example: <<exampleCollection>>
      post:
        description: Add a new <<resourcePathName|!singularize>>
        body:
          application/json:
            schema: <<resourcePathName|!singularize>>
            example: <<exampleItem>>
        responses:
          201:
            body:
              application/json:
                schema: genResponse
                example: !include 201.sample
          400:
            description: Error in submitted data
            body:
              application/json:
                schema: genResponse
                example: !include 400.sample
  - collection-readonly:
      description: Collection of <<resourcePathName>>
      get:
        description: Get a list of <<resourcePathName>>
        body:
          application/json:
          text/html:
            example: null
        responses:
          200:
            body:
              application/json:
                schema: <<resourcePathName>>
                example: <<exampleCollection>>
  - collection-item:
      get:
        description: |
          Retrieve a known <<resourcePathName|!singularize>>
        body:
          application/json:
          text/html:
            example: null
        responses:
          200:
            body:
              application/json:
                schema: <<resourcePathName|!singularize>>
                example: <<exampleItem>>
          404:
            description: |
              Requested <<resourcePathName|!singularize>> not found
            body:
              application/json:
                schema: genResponse
                example: !include 404.sample
      put:
        description: |
          Update a known <<resourcePathName|!singularize>>
        responses:
          200:
            description: <<resourcePathName|!singularize>> updated successfully
            body:
              application/json:
                schema: <<resourcePathName|!singularize>>
                example: |
                  <<exampleItem>>
          404:
            description: <<resourcePathName|!singularize>> not found
            body:
              application/json:
                schema: genResponse
                example: !include 404.sample
      delete:
        description: Delete a <<resourcePathName|!singularize>>
        responses:
          200:
            description: <<resourcePathName|!singularize>> successfully deleted
            body:
              application/json:
                schema: genResponse
                example: !include 200.sample
          404:
            description: <<resourcePathName|!singularize>> record not found
            body:
              application/json:
                schema: genResponse
                example: !include 404.sample

/users:
  type:
    collection:
      exampleCollection: !include user-collection.sample
      exampleItem: !include user.sample
  get:
    is: [
          searchable: {
            description: "with valid fields: username",
            example: "[\"username\", \"jackson\", \"=\"]"
          },
          pageable
        ]
  /{user_id}:
    type:
      collection-item:
        exampleItem: !include user.sample

/listeners:
  type:
    collection:
      exampleCollection: !include listener-collection.sample
      exampleItem: !include listener.sample
  get:
    is: [
          searchable: {
            description: "with valid fields: mac, zone_id, missing",
            example: "[\"zone_id\", \"24\", \"=\"]"
          },
          pageable
        ]
  /{listener_id}:
    type:
      collection-item:
        exampleItem: !include listener.sample

/beacons:
  type:
    collection:
      exampleCollection: !include beacon-collection.sample
      exampleItem: !include beacon.sample
  get:
    is: [
          searchable: {
            description: "with valid fields: mac, major, minor, uuid, missing, last_battery, zone_id",
            example: "[\"zone_id\", \"24\", \"=\"]"
          },
          pageable
        ]
  /{beacon_id}:
    type:
      collection-item:
        exampleItem: !include beacon.sample
    /history:
      type:
        collection-readonly:
          exampleCollection: !include history-collection.sample
      get:
        is: [
              pageable,
              searchable: {
                description: "with valid fields: timestamp, zone_id, state",
                example: "[\"zone_id\", \"24\", \"=\"]"
              }
            ]

/zones:
  type:
    collection:
      exampleCollection: !include zone-collection.sample
      exampleItem: !include zone.sample
  get:
    is: [ pageable ]
  /{zone_id}:
    type:
      collection-item:
        exampleItem: !include zone.sample

traits:
  - searchable:
      queryParameters:
        query:
          description: |
            JSON array [{"field1","value1","operator1"},{"field2","value2","operator2"},...,{"fieldN","valueN","operatorN"}] <<description>>
          example: |
            <<example>>
  - orderable:
      queryParameters:
        orderBy:
          description: |
            Order by field: <<fieldsList>>
          type: string
          required: false
        order:
          description: Order
          enum: [desc, asc]
          default: desc
          required: false
  - pageable:
      queryParameters:
        offset:
          description: Skip over a number of elements by specifying an offset value for the query
          type: integer
          required: false
          example: 20
          default: 0
        limit:
          description: Limit the number of elements on the response
          type: integer
          required: false
          example: 80
          default: 10


        
schemas:
  - genResponse: !include generic.schema
  - user: !include user.schema
  - users: !include user-collection.schema
  - listener: !include listener.schema
  - listeners: !include listener-collection.schema
  - beacon: !include beacon.schema
  - beacons: !include beacon-collection.schema
  - zone: !include zone.schema
  - zones: !include zone-collection.schema
  - history: !include history-collection.schema