API.yml

#%RAML 0.8
title: Open mHealth Data Point API
version: v1.0.M1

baseUri: https://{endpointUrl}/{version}
baseUriParameters:
  domain:
    endpointUrl: the location of the API endpoint
    type: string

mediaType: application/json

schemas:
  - data-point: !include http://www.openmhealth.org/schema/omh/data-point-1.0.json

traits:
  - paginated:
      queryParameters:
        skip:
          description: the number of data points to skip
        limit:
          description: the number of data points to return
          default: 100

securitySchemes:
  - oauth_2_0:
    type: OAuth 2.0
    describedBy:
      headers:
        Authorization:
          description: the access token
          type: string
      responses:
        401:
          description: the access token is not valid or has not been granted the required scope

    settings:
      authorizationUri: http://domain/oauth/authorize
      accessTokenUri: http://domain/oauth/token
      authorizationGrants: [code, token, owner]
      scopes: [read_data_points, write_data_points, delete_data_points]

/dataPoints:
  get:
    description: get a list of data points matching some criteria
    is: [ paginated ]
    securedBy: [oauth_2_0]
    queryParameters:
      schema_namespace:
        description: the namespace of the schema the data points conform to
        type: string
        pattern: "^[a-zA-Z0-9.-]+"
        example: "omh"
        required: true
      schema_name:
        description: the name of the schema the data points conform to
        type: string
        pattern: "[a-zA-Z0-9.-]+"
        example: "blood-pressure"
        required: true
      schema_version:
        description:  the version of the schema the data points conform to
        type: string
        pattern: "\d+\.\d+(\.[a-zA-Z0-9]+)?"
        example: "1.1.RC1"
        required: true
      created_on_or_after:
        description: the earliest creation timestamp of the data points to return, inclusive, in ISO8601 format
        type: string
        example: "2013-02-05T07:25:00Z"
      created_before:
        description: the latest creation timestamp of the data points to return, exclusive, in ISO8601 format
        type: string
        example: "2013-04-05T07:25:00.123+03:00"
    responses:
      200:
        description: a list of matching data points belonging to the user associated with the access token
        body:
          application/json:
            schema: |
              {
                  "$schema": "http://json-schema.org/draft-04/schema#",
                  "type": "array",
                  "items": {
                      "data_point": {
                          "$ref": "http://www.openmhealth.org/schema/omh/data-point-1.0.json"
                      }
                  }
              }

  post:
    description: create a data point
    securedBy: [oauth_2_0]
    body:
      application/json:
        schema: !include data-point
    responses:
      201:
        description: the data point has been created
      409:
        description: a data point with the same identifier already exists

  /{id}:
    uriParameters:
      id:
        description: the identifier of the data point
        type: string

    get:
      description: get a data point
      securedBy: [oauth_2_0]
      responses:
        200:
          body:
            application/json:
              schema: !include data-point
        404:
          description: the data point does not exist

    delete:
      description: delete a data point
      securedBy: [oauth_2_0]
      responses:
        200:
          description: the data point has been deleted
        404:
          description: the data point does not exist