Name API as all other similar pages

Name API as all other similar pages

#%RAML 0.8
---
title: Modify delivery API
baseUri: https://www.mybring.com/modify-delivery

documentation:
- title: Introduction
  content: |
      The modify delivery api is used to modify a shipment currently on it's way.
      Below are the various modifications (which will be API calls) supported:
        - Stop shipment.
        - Change cash on deivery.

- title: Authentication
  content: |
    The Modify delivery API requires authentication for all its endpoints. See the [getting started guide on authentication](/api/#authentication) if you're not sure what this means.

    | Header | Example | Comment |
    |:-------|:--------|:--------|
    | `X-MyBring-API-Uid` | `john.doe@example.com` | Mybring login ID |
    | `X-MyBring-API-Key` | `1234abc-abcd-1234-5678-abcd1234abcd ` | Mybring login's API key |
    | `X-Bring-Client-URL` | `https://example.com/ ` | A URL that sort of identifies where you're using the APIs. |

    Those headers must be present for authenticating requests.

/allowed-modification:
  displayName: Allowed modifications
  get:
    description: List of allowed modifications, along with failure causes.
    queryParameters:
        q:
            description: Shipment number to be checked for.
            type: string
            required: true
            example: 707262014721
    responses:
      200:
        body:
          application/json:
            example: !include examples/allowed-modification.json

/stop-shipment:
  displayName: Stop shipment

  post:
    description: Stop a shipment and return to sender.
    body:
      application/json:
        example: !include examples/stoprequest.json

    responses:
      200:
        body:
          application/xml:
            example: !include examples/stopresponse.json

/change-cod:
  displayName: Change cash on delivery

  post:
    description: Change cash on delivery amount to be paid.
    body:
      application/json:
        example: !include examples/changecodrequest.json

    responses:
      200:
        body:
          application/json:
            example: !include examples/changecodresponse.json

#%RAML 0.8
---
title: Modify delivery
baseUri: https://www.mybring.com/modify-delivery

documentation:
- title: Introduction
  content: |
      The modify delivery api is used to modify a shipment currently on it's way.
      Below are the various modifications (which will be API calls) supported:
        - Stop shipment.
        - Change cash on deivery.

- title: Authentication
  content: |
    The Modify delivery API requires authentication for all its endpoints. See the [getting started guide on authentication](/api/#authentication) if you're not sure what this means.

    | Header | Example | Comment |
    |:-------|:--------|:--------|
    | `X-MyBring-API-Uid` | `john.doe@example.com` | Mybring login ID |
    | `X-MyBring-API-Key` | `1234abc-abcd-1234-5678-abcd1234abcd ` | Mybring login's API key |
    | `X-Bring-Client-URL` | `https://example.com/ ` | A URL that sort of identifies where you're using the APIs. |

    Those headers must be present for authenticating requests.

/allowed-modification:
  displayName: Allowed modifications
  get:
    description: List of allowed modifications, along with failure causes.
    queryParameters:
        q:
            description: Shipment number to be checked for.
            type: string
            required: true
            example: 707262014721
    responses:
      200:
        body:
          application/json:
            example: !include examples/allowed-modification.json

/stop-shipment:
  displayName: Stop shipment

  post:
    description: Stop a shipment and return to sender.
    body:
      application/json:
        example: !include examples/stoprequest.json

    responses:
      200:
        body:
          application/xml:
            example: !include examples/stopresponse.json

/change-cod:
  displayName: Change cash on delivery

  post:
    description: Change cash on delivery amount to be paid.
    body:
      application/json:
        example: !include examples/changecodrequest.json

    responses:
      200:
        body:
          application/json:
            example: !include examples/changecodresponse.json


Removed optional query parameter that is not used yet and leads to confusion

#%RAML 1.0
title: Digitale Delta - API
version: 2.0
securitySchemes:
  basic:
    type: Basic Authentication
  openidconnect:
    type: OAuth 2.0
baseUri: http://api.rws.nl/dl/
mediaType: [ application/json ]
description: Digital Delta API version 2.0
documentation:
 - title: Introduction
   content: !include documentation/dd/Introduction.md
 - title: Document history
   content: !include documentation/dd/Document_History.md
 - title: The API specification
   content: !include documentation/dd/The_API_Specification.md
 - title: Future enhancements and research
   content: !include documentation/dd/Future_Enhancements_and_Research.md

# HTTP is included as protocol but is optional as for security reasons a Provider might decide to support HTTPS only.
protocols:
  - HTTP
  - HTTPS

uses:
  DD-T: libraries/dd-base-types.raml
  GENERIC-RESP: libraries/generic-response-types.raml
  DD-RESP: libraries/dd-response-types.raml
  TRAITS: libraries/dd-traits.raml

#
# All data types are defined in external files (see above) so they can be shared between DD and DD-OPER API.
#
types:

#
# The resources
/dd/2.0:

# ##################################################

  /nodes:
    description: The Nodes endpoint returns the nodes that the provider offers.
    get:
      is: [ TRAITS.pageable, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError ]
      queryParameters:
        process?:
          type: DD-T.ProcessName
        name?:
          type: string
          description: (Partial) name of the node. Partial meaning startsWith(...).
          example: AquaDeskPrimaryNode
      responses:
        200:
          description: |
            Succesfully retrieved resource.
          body:
            application/json:
              type: DD-RESP.NodeListResponse
              example: !include examples/dd-nodelist-response.json
    /{nodeId}:
      description: Request a specific Node by its unique dentifier.
      uriParameters:
        nodeId:
          type: DD-T.Identifier
      is: [ TRAITS.has403-AccessDeniedError, TRAITS.has404-NotFoundError, TRAITS.has500-ServerError ]
      get:
        queryParameters:
          process?:
            type: DD-T.ProcessName
        responses:
          200:
            description: |
              Succesfully retrieved resource.
            body:
              application/json:
                type: DD-RESP.NodeResponse
                example: !include examples/dd-node-response.json

# ##################################################

  /sources:
    description: Retrieve (data)source resources.
    is: [ TRAITS.pageable, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError ]
    get:
      queryParameters:
        process?:
          type: DD-T.ProcessName
      responses:
        200:
          description: Succesfully retrieved resource.
          body:
            application/json:
              type: DD-RESP.SourceListResponse
              example: !include examples/dd-sourcelist-response.json

# #####################################################

  /locations:
    get:
      description: |
        The locations endpoint returns the locations where measurements and/or model results are available.
      is: [ TRAITS.pageable, TRAITS.has400-InvalidRequestError, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError, TRAITS.locationFilterable ]
      queryParameters:
        process?:
          type: DD-T.ProcessName
        boundingBox?:
          type: DD-T.BoundingBox
          example: [4.8, 52.0, 5.8, 54.0]
        locationName?:
          type: string
          description: (Partial) location name. Partial meaning startsWith(...).
          example: NEDHMT
        nodeId?:
          type: DD-T.Identifier
          description: This query parameter is deprecated.
        locationCode?:
          type: string
          description: Location code.
          example: NLWATB-RWTS_AFGDM_0001
        locationId?: DD-T.Identifier
      responses:
        200:
          description: Succesfully retrieved resource.
          body:
            application/json:
              type: DD-RESP.LocationListResponse
              example: !include examples/dd-locationslist-response.json

    /geojson:
      get:
        description: |
          Retrieve location resources. Response is in GeoJSON format.
        is: [ TRAITS.pageable, TRAITS.has400-InvalidRequestError, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError, TRAITS.locationFilterable ]
        queryParameters:
          process?:
            type: DD-T.ProcessName
          boundingBox?:
            type: DD-T.BoundingBox
            example: [4.8, 52.0, 5.8, 54.0]
          locationName?:
            type: string
            description: (Partial) location name. Partial meaning startsWith(...).
            example: NEDHMT
          nodeId?:
            type: DD-T.Identifier
            description: This query parameter is deprecated.
          locationCode?:
            type: string
            description: Location code.
            example: NLWATB-RWTS_AFGDM_0001
          locationId?: DD-T.Identifier
        responses:
          200:
            description: Succesfully retrieved resource.
            body:
              application/json:
                type: DD-RESP.LocationListResponseGeoJSON
                example: !include examples/dd-locationslist-response-geojson.json

    /{locationId}:
      description: Request a specific location by its id. Response is always in GeoJSON format.
      uriParameters:
        locationId:
          type: DD-T.Identifier
      is: [ TRAITS.has403-AccessDeniedError, TRAITS.has404-NotFoundError, TRAITS.has500-ServerError ]
      get:
        description: |
          Request a specific Location by its unique dentifier.
        queryParameters:
          process?:
            type: DD-T.ProcessName
            default: measurement
        responses:
          200:
            description: |
              Succesfully retrieved resource
            body:
              application/json:
                type: object
                example: !include examples/dd-location-response-geojson.json

######################################################

  /aspectSets:
    description:
      Retrieves available aspect sets.
      Note - The request requires some parameters to provide a context for the response as aspects relate to observation types for instance.
      When aspects and aspect sets are not supported and empty List shall be returned.
    get:
      is: [ TRAITS.pageable, TRAITS.has400-InvalidRequestError, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError  ]
      queryParameters:
        process?:
          type: DD-T.ProcessName
      responses:
        200:
          description: |
            Succesfully retrieved resource.
          body:
            application/json:
              type: DD-RESP.AspectSetListResponse
              example: !include examples/dd-aspectsetlist-response.json

######################################################

  /observationTypes:
    description: The ObservationTypes endpoint can return the observationtypes that the provider offers. Filtering: list of parameters.

About ObservationType

The ObservationType objects describe all attributes to correctly interpret what has been measured, and in what way. It is essential to have the quantity field.

    get:
      description: |
        Retrieve observationTypes resources.
      is: [ TRAITS.pageable, TRAITS.has400-InvalidRequestError, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError, TRAITS.observationTypeFilterable ]
      queryParameters:
        process?:
          type: DD-T.ProcessName
        observationTypeId?:
          type: DD-T.Identifier
        quantity?:
          description: Retrieve only observation types that contain the specified quantity.
          type: string
        parameterCode?:
          description: Retrieve only observation types that contain the specified parameter code.
          type: string
      responses:
        200:
          description: |
            Succesfully retrieved timeseries.
          body:
            application/json:
              type: DD-RESP.ObservationTypeListResponse
              example: !include examples/dd-observationtypelist-response.json

    /{observationTypeId}:
      description: Request a specific ObservationType by its unique identifier.
      is: [ TRAITS.has403-AccessDeniedError, TRAITS.has404-NotFoundError, TRAITS.has500-ServerError ]
      uriParameters:
        observationTypeId:
          type: DD-T.Identifier
      get:
        queryParameters:
          process?:
            type: DD-T.ProcessName
        responses:
          200:
            description: |
              Succesfully retrieved resource.
            body:
              application/json:
                type: DD-RESP.ObservationTypeResponse
                example: !include examples/dd-observationtype-response.json

######################################################

  /timeseries:
    get:
      description: |
        Retrieve timeseries resources.
        A request where both startTime and endTime are omitted returns a response with just the metadata (implicit includeMetaData = true).
      is: [ TRAITS.pageable, TRAITS.has400-InvalidRequestError, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError, TRAITS.timeseriesFilterable, TRAITS.locationFilterable, TRAITS.observationTypeFilterable ]
      queryParameters:
        process?:
          type: DD-T.ProcessName
        startTime?:
          type: DD-T.StartTime
        endTime?:
          type: DD-T.EndTime
        locationCode?:
          type: string
          example: "HVH"
        locationName?:
          type: DD-T.LocationName
          example: "Hoek.vanHolland.nieuwewat"
        sourceName:
          type: DD-T.SourceName
          example: rws_prediction
        observationTypeId?:
          type: DD-T.Identifier
        realizationCount?:
          description: Added Count as this is the name in ObservationType response.
          type: integer
        parameterCode?:
          type: string
        quantity?:
          description:
          type: string
        aspectSet?:
          type: DD-T.AspectSetName
        quantityName?:
          type: DD-T.QuantityName
        intervalLength?:
          type: DD-T.IntervalLength
        nodeId?:
          type: DD-T.Identifier
      responses:
        200:
          description: |
            Succesfully retrieved timeseries.
          body:
            application/json:
              type: DD-RESP.TimeseriesListResponse
              example: !include examples/dd-timeserieslist-response-verwachtingen-en-metingen-fulldd.json

    /{timeseriesId}:
      description: Request a specific (single) Timeseries by its unique identifier.
      uriParameters:
        timeseriesId:
          type: DD-T.Identifier
      is: [ TRAITS.has403-AccessDeniedError, TRAITS.has404-NotFoundError, TRAITS.has500-ServerError ]
      get:
        queryParameters:
          process?:
            type: DD-T.ProcessName
            default: measurement
        responses:
          200:
            description: |
              Succesfully retrieved resource
            body:
              application/json:
                type: DD-RESP.TimeseriesResponse
                example: !include examples/dd-timeseries-response-single.json

#%RAML 1.0
title: Digitale Delta - API
version: 2.0
securitySchemes:
  basic:
    type: Basic Authentication
  openidconnect:
    type: OAuth 2.0
baseUri: http://api.rws.nl/dl/
mediaType: [ application/json ]
description: Digital Delta API version 2.0
documentation:
 - title: Introduction
   content: !include documentation/dd/Introduction.md
 - title: Document history
   content: !include documentation/dd/Document_History.md
 - title: The API specification
   content: !include documentation/dd/The_API_Specification.md
 - title: Future enhancements and research
   content: !include documentation/dd/Future_Enhancements_and_Research.md

# HTTP is included as protocol but is optional as for security reasons a Provider might decide to support HTTPS only.
protocols:
  - HTTP
  - HTTPS

uses:
  DD-T: libraries/dd-base-types.raml
  GENERIC-RESP: libraries/generic-response-types.raml
  DD-RESP: libraries/dd-response-types.raml
  TRAITS: libraries/dd-traits.raml

#
# All data types are defined in external files (see above) so they can be shared between DD and DD-OPER API.
#
types:

#
# The resources
/dd/2.0:

# ##################################################

  /nodes:
    description: The Nodes endpoint returns the nodes that the provider offers.
    get:
      is: [ TRAITS.pageable, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError ]
      queryParameters:
        process?:
          type: DD-T.ProcessName
        name?:
          type: string
          description: (Partial) name of the node. Partial meaning startsWith(...).
          example: AquaDeskPrimaryNode
      responses:
        200:
          description: |
            Succesfully retrieved resource.
          body:
            application/json:
              type: DD-RESP.NodeListResponse
              example: !include examples/dd-nodelist-response.json
    /{nodeId}:
      description: Request a specific Node by its unique dentifier.
      uriParameters:
        nodeId:
          type: DD-T.Identifier
      is: [ TRAITS.has403-AccessDeniedError, TRAITS.has404-NotFoundError, TRAITS.has500-ServerError ]
      get:
        queryParameters:
          process?:
            type: DD-T.ProcessName
        responses:
          200:
            description: |
              Succesfully retrieved resource.
            body:
              application/json:
                type: DD-RESP.NodeResponse
                example: !include examples/dd-node-response.json

# ##################################################

  /sources:
    description: Retrieve (data)source resources.
    is: [ TRAITS.pageable, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError ]
    get:
      queryParameters:
        process?:
          type: DD-T.ProcessName
      responses:
        200:
          description: Succesfully retrieved resource.
          body:
            application/json:
              type: DD-RESP.SourceListResponse
              example: !include examples/dd-sourcelist-response.json

# #####################################################

  /locations:
    get:
      description: |
        The locations endpoint returns the locations where measurements and/or model results are available.
      is: [ TRAITS.pageable, TRAITS.has400-InvalidRequestError, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError, TRAITS.locationFilterable ]
      queryParameters:
        process?:
          type: DD-T.ProcessName
        boundingBox?:
          type: DD-T.BoundingBox
          example: [4.8, 52.0, 5.8, 54.0]
        locationName?:
          type: string
          description: (Partial) location name. Partial meaning startsWith(...).
          example: NEDHMT
        nodeId?:
          type: DD-T.Identifier
          description: This query parameter is deprecated.
        locationCode?:
          type: string
          description: Location code.
          example: NLWATB-RWTS_AFGDM_0001
        locationId?: DD-T.Identifier
      responses:
        200:
          description: Succesfully retrieved resource.
          body:
            application/json:
              type: DD-RESP.LocationListResponse
              example: !include examples/dd-locationslist-response.json

    /geojson:
      get:
        description: |
          Retrieve location resources. Response is in GeoJSON format.
        is: [ TRAITS.pageable, TRAITS.has400-InvalidRequestError, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError, TRAITS.locationFilterable ]
        queryParameters:
          process?:
            type: DD-T.ProcessName
          boundingBox?:
            type: DD-T.BoundingBox
            example: [4.8, 52.0, 5.8, 54.0]
          locationName?:
            type: string
            description: (Partial) location name. Partial meaning startsWith(...).
            example: NEDHMT
          nodeId?:
            type: DD-T.Identifier
            description: This query parameter is deprecated.
          locationCode?:
            type: string
            description: Location code.
            example: NLWATB-RWTS_AFGDM_0001
          locationId?: DD-T.Identifier
        responses:
          200:
            description: Succesfully retrieved resource.
            body:
              application/json:
                type: DD-RESP.LocationListResponseGeoJSON
                example: !include examples/dd-locationslist-response-geojson.json

    /{locationId}:
      description: Request a specific location by its id. Response is always in GeoJSON format.
      uriParameters:
        locationId:
          type: DD-T.Identifier
      is: [ TRAITS.has403-AccessDeniedError, TRAITS.has404-NotFoundError, TRAITS.has500-ServerError ]
      get:
        description: |
          Request a specific Location by its unique dentifier.
        queryParameters:
          process?:
            type: DD-T.ProcessName
            default: measurement
        responses:
          200:
            description: |
              Succesfully retrieved resource
            body:
              application/json:
                type: object
                example: !include examples/dd-location-response-geojson.json

######################################################

  /aspectSets:
    description:
      Retrieves available aspect sets.
      Note - The request requires some parameters to provide a context for the response as aspects relate to observation types for instance.
      When aspects and aspect sets are not supported and empty List shall be returned.
    get:
      is: [ TRAITS.pageable, TRAITS.has400-InvalidRequestError, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError  ]
      queryParameters:
        process?:
          type: DD-T.ProcessName
      responses:
        200:
          description: |
            Succesfully retrieved resource.
          body:
            application/json:
              type: DD-RESP.AspectSetListResponse
              example: !include examples/dd-aspectsetlist-response.json

######################################################

  /observationTypes:
    description: The ObservationTypes endpoint can return the observationtypes that the provider offers. Filtering: list of parameters.

About ObservationType

The ObservationType objects describe all attributes to correctly interpret what has been measured, and in what way. It is essential to have the quantity field.

    get:
      description: |
        Retrieve observationTypes resources.
      is: [ TRAITS.pageable, TRAITS.has400-InvalidRequestError, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError, TRAITS.observationTypeFilterable ]
      queryParameters:
        process?:
          type: DD-T.ProcessName
        observationTypeId?:
          type: DD-T.Identifier
        quantity?:
          description: Retrieve only observation types that contain the specified quantity.
          type: string
        parameterCode?:
          description: Retrieve only observation types that contain the specified parameter code.
          type: string
      responses:
        200:
          description: |
            Succesfully retrieved timeseries.
          body:
            application/json:
              type: DD-RESP.ObservationTypeListResponse
              example: !include examples/dd-observationtypelist-response.json

    /{observationTypeId}:
      description: Request a specific ObservationType by its unique identifier.
      is: [ TRAITS.has403-AccessDeniedError, TRAITS.has404-NotFoundError, TRAITS.has500-ServerError ]
      uriParameters:
        observationTypeId:
          type: DD-T.Identifier
      get:
        queryParameters:
          process?:
            type: DD-T.ProcessName
        responses:
          200:
            description: |
              Succesfully retrieved resource.
            body:
              application/json:
                type: DD-RESP.ObservationTypeResponse
                example: !include examples/dd-observationtype-response.json

######################################################

  /timeseries:
    get:
      description: |
        Retrieve timeseries resources.
        A request where both startTime and endTime are omitted returns a response with just the metadata (implicit includeMetaData = true).
      is: [ TRAITS.pageable, TRAITS.has400-InvalidRequestError, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError, TRAITS.timeseriesFilterable, TRAITS.locationFilterable, TRAITS.observationTypeFilterable ]
      queryParameters:
        process?:
          type: DD-T.ProcessName
        startTime?:
          type: DD-T.StartTime
        endTime?:
          type: DD-T.EndTime
        locationCode?:
          type: string
          example: "HVH"
        locationName?:
          type: DD-T.LocationName
          example: "Hoek.vanHolland.nieuwewat"
        sourceName:
          type: DD-T.SourceName
          example: rws_prediction
        observationTypeId?:
          type: DD-T.Identifier
        realizationCount?:
          description: Added Count as this is the name in ObservationType response.
          type: integer
        parameterCode?:
          type: string
        quantity?:
          description:
          type: string
        aspectSet?:
          type: DD-T.AspectSetName
        quantityName?:
          type: DD-T.QuantityName
        includeMetaData?:
          description: This url query parameter replaces the '/data' control extension of the /timeseries endpoint.
            Metadata is included in the response by default, but can be excluded to reduce response size.
          type: boolean
          default: true
        intervalLength?:
          type: DD-T.IntervalLength
        nodeId?:
          type: DD-T.Identifier
      responses:
        200:
          description: |
            Succesfully retrieved timeseries.
          body:
            application/json:
              type: DD-RESP.TimeseriesListResponse
              example: !include examples/dd-timeserieslist-response-verwachtingen-en-metingen-fulldd.json

    /{timeseriesId}:
      description: Request a specific (single) Timeseries by its unique identifier.
      uriParameters:
        timeseriesId:
          type: DD-T.Identifier
      is: [ TRAITS.has403-AccessDeniedError, TRAITS.has404-NotFoundError, TRAITS.has500-ServerError ]
      get:
        queryParameters:
          process?:
            type: DD-T.ProcessName
            default: measurement
        responses:
          200:
            description: |
              Succesfully retrieved resource
            body:
              application/json:
                type: DD-RESP.TimeseriesResponse
                example: !include examples/dd-timeseries-response-single.json


Fixed small issue in organization resource

is: [ auth ]
type:
  collection:
    humanName: organization
    schemaBaseName: organization
    exampleGetResponse: !include ../examples/organizations/response-array-get.json
    examplePostRequest: !include ../examples/organizations/request-post.json
    examplePostError: !include ../examples/organizations/response-post-error.json
get:
  securedBy: [ test ]
post:
  securedBy: [ test ]
  description: Create a new organization and assign the signed in user.

/{organizationId}:
  is: [ auth ]
  type:
    member:
      humanName: organization
      schemaBaseName: organization
      identifierName: organizationId
      exampleGetResponse: !include ../examples/organizations/response-get.json
      examplePatchRequest: !include ../examples/organizations/request-patch.json
      examplePatchError: !include ../examples/organizations/response-patch-error.json
  get:
    securedBy: [ test ]

  patch:
    securedBy: [ jwt: { type: 'owner' }, test ]

  /users:
    is: [ auth ]
    get:
      securedBy: [ jwt: { type: 'owner' } ]
      description: Retrieve all the users for an organization.
      responses:
        200:
          description: List of users or empty list `[]`.
          body:
            schema: user-getAll
            example: !include ../examples/users/response-array-get.json

  /actions:
    is: [ auth ]
    description: Execute different action on the organization.

    post:
      securedBy: [ jwt: { type: 'owner' } ]
      description: Post an action
      body:
        schema: organization-action-post
        example: !include ../examples/organizations/actions/request-post.json

is: [ auth ]
type:
  collection:
    humanName: organization
    schemaBaseName: organization
    exampleGetResponse: !include ../examples/organizations/response-array-get.json
    examplePostRequest: !include ../examples/organizations/request-post.json
    examplePostError: !include ../examples/organizations/response-post-error.json
get:
  securedBy: [ test ]
post:
  securedBy: [ test ]
  description: Create a new organization and assign the signed in user.

/{organizationId}:
  is: [ auth ]
  type:
    member:
      humanName: organization
      schemaBaseName: organization
      identifierName: organizationId
      exampleGetResponse: !include ../examples/organizations/response-get.json
      examplePatchRequest: !include ../examples/organizations/request-patch.json
      examplePatchError: !include ../examples/organizations/response-patch-error.json
  get:
    securedBy: [ test ]

  patch:
    securedBy: [ jwt: { type: 'owner' }, test ]
    description: Patch the organization. **Can only be done by a user associated to the organization.**
    responses:
      404:
        description: When the organization is not found or is not associated with the singned in user.

  /users:
    is: [ auth ]
    get:
      securedBy: [ jwt: { type: 'owner' } ]
      description: Retrieve all the users for an organization.
      responses:
        200:
          description: List of users or empty list `[]`.
          body:
            schema: user-getAll
            example: !include ../examples/users/response-array-get.json

  /actions:
    is: [ auth ]
    description: Execute different action on the organization.

    post:
      securedBy: [ jwt: { type: 'owner' } ]
      description: Post an action
      body:
        schema: organization-action-post
        example: !include ../examples/organizations/actions/request-post.json


documenting the /_version endpoint

documenting the /_version endpoint

#%RAML 0.8

title: Ephemeral Container Service (ECS) (%ECS_VERSION%)
version: v99.999
documentation:
  - title: Overview
    content: |
      * ...
  - title: Key Concepts
    content: |
      * task packaged inside a docker container
      * emphemeral = short lived, no state

/tasks:
  displayName: Tasks
  description: |
    The ```/tasks``` endpoint enables creation and execution of tasks
  post:
    description: |
      Create and execute a task.

      ##### Authentication
        * None

      ##### Performance Expectations
        * 99% of the time < nnn ms

      ##### Example
      ```bash
      >cat echo.json
      {
        "docker_image": "ubuntu",
        "tag": "latest",
        "cmd": [
          "echo",
          "hello world!!!"
        ]
      }
      >curl \
        -s \
        -X POST \
        -H "Content-Type: application/json" \
        --data-binary @echo.json \
        http://127.0.0.1:8445/v1.0/tasks | \
        jq
      {
        "stdout": "aGVsbG8gd29ybGQhISEK",
        "stderr": "",
        "exitCode": 0
      }
      > python
      Python 2.7.6 (default, Jun 22 2015, 17:58:13)
      [GCC 4.8.2] on linux2
      Type "help", "copyright", "credits" or "license" for more information.
      >>> import base64
      >>> base64.b64decode('aGVsbG8gd29ybGQhISEK')
      'hello world!!!\n'
      >>>
      ```
    responses:
      200:
        description:
          Success!
        body:
          application/json:
            schema: !include ../ecs/jsonschemas/create_tasks_request.json
      400:
        description:
          Bad request.

/_version:
  description: |
    The ```/_version``` endpoint reports
    returns the ECS' version.
  get:
    description: |
      The endpoint always returns 200 OK and includes the services'
      version number in the body.

      ##### Authentication
        * None

      ##### Example
      ```bash
      >curl \
        -s \
        -o /dev/null \
        -w %{http_code}\\n \
        http://127.0.0.1:8445/v1.0/_version
      200
      >
      ```
    responses:
      200:
        description:
          200 OK is always returned by this endpoint.
        body:
          application/json:

/_noop:
  description: |
    The ```/_noop``` endpoint is intended to be used
    for assessing a deployment's performance.
  get:
    description: |
      The endpoint always returns 200 OK after doing nothing ie. it's a no-op.
      The intended purpose of this endpoint is to measure how long it takes
      for a caller and the service to establish a secure connection
      and complete a request/response roundtrip.

      ##### Authentication
        * None

      ##### Example
      ```bash
      >curl \
        -s \
        -o /dev/null \
        -w %{http_code}\\n \
        http://127.0.0.1:8445/v1.0/_noop
      200
      >
      ```
    responses:
      200:
        description:
          200 OK is always returned by this endpoint.
        body:
          application/json:

/_health:
  description: |
    An HTTP GET to the ```/_health``` endpoint returns a JSON document
    which describes the health of the service.
  get:
    description: |
      The JSON document returned by an HTTP GET to the ```/_health```
      endpoint and the HTTP status code describe the health of the service.
      An HTTP status code of 200 OK is healthy and anything else is unhealthy.
      The top level "status" property in the JSON document will be "green" if the service
      is healthy and "red" if there's a problem.
      The "details" property of the JSON document contains a red/green style health entry
      for each service's components.
      The overall health is "red" if any of the dependant services are unhealthy.

      Two types of health check are possible. A quick health check
      does not confirm the health of all service components and will
      respond quickly. A comprehensive health check does check
      all service components. The ```quick``` query string parameter
      takes a boolean value to determine if a quick or comprehensive
      health check is performed.

      ##### Authentication
        * None (for now)

      ##### Usage Expectations
        * the external monitoring service will perform a quick health check every minute
        * the external monitoring service will perform a comprehensive health check 5 minutes
        * a load balancer sitting in front of the app tier will repeatedly and
          frequently issue a quick health check

      ##### Performance Expectations
        * quick - 99% of the time < 50 ms
        * comprehensive - 99% of the time < 3,050 ms
          (note 3,050 is determined by taking the default value for the
          ```max_time_in_ms_to_wait_for_component_health_checks```
          configuration option and adding 50 ms ie. changing the
          configuration option can be used to change the performance
          characteristics of the endpoint)

      ##### Example
      For example, below a sample of a healthy response to a request
      for a quick health check.

      ```bash
      >curl \
        -s \
        http://127.0.0.1:8445/v1.0/_health?quick=false | \
        jq
      {
        "status": "green",
        "details": {
          "docker remote api": {
            "status": "green",
            "details": {
              "connectivity": "green",
              "api version": "green"
            }
          }
        },
        "links": {
          "self": {
            "href": "http://127.0.0.1:8445/v1.0/_health"
          }
        }
      }
      >
      ```

    queryParameters:
      quick:
        displayName: quick
        type: boolean
        description:
          Determines if a quick or deep health check is performed.
          quick is true by default.
        example: true
        required: false
    responses:
      200:
        description:
          When everything is green a 200 OK is returned.
      500:
        description:
          something super nasty happened inside the service
      503:
        description:
          When something is red a 503 service unavailable is returned.

#%RAML 0.8

title: Ephemeral Container Service (ECS) (%ECS_VERSION%)
version: v99.999
documentation:
  - title: Overview
    content: |
      * ...
  - title: Key Concepts
    content: |
      * task packaged inside a docker container
      * emphemeral = short lived, no state

/tasks:
  displayName: Tasks
  description: |
    The ```/tasks``` endpoint enables creation and execution of tasks
  post:
    description: |
      Create and execute a task.

      ##### Authentication
        * None

      ##### Performance Expectations
        * 99% of the time < nnn ms

      ##### Example
      ```bash
      >cat echo.json
      {
        "docker_image": "ubuntu",
        "tag": "latest",
        "cmd": [
          "echo",
          "hello world!!!"
        ]
      }
      >curl \
        -s \
        -X POST \
        -H "Content-Type: application/json" \
        --data-binary @echo.json \
        http://127.0.0.1:8445/v1.0/tasks | \
        jq
      {
        "stdout": "aGVsbG8gd29ybGQhISEK",
        "stderr": "",
        "exitCode": 0
      }
      > python
      Python 2.7.6 (default, Jun 22 2015, 17:58:13)
      [GCC 4.8.2] on linux2
      Type "help", "copyright", "credits" or "license" for more information.
      >>> import base64
      >>> base64.b64decode('aGVsbG8gd29ybGQhISEK')
      'hello world!!!\n'
      >>>
      ```
    responses:
      200:
        description:
          Success!
        body:
          application/json:
            schema: !include ../ecs/jsonschemas/create_tasks_request.json
      400:
        description:
          Bad request.

/_noop:
  description: |
    The ```/_noop``` endpoint is intended to be used
    for assessing a deployment's performance.
  get:
    description: |
      The endpoint always returns 200 OK after doing nothing ie. it's a no-op.
      The intended purpose of this endpoint is to measure how long it takes
      for a caller and the service to establish a secure connection
      and complete a request/response roundtrip.

      ##### Authentication
        * None

      ##### Example
      ```bash
      >curl \
        -s \
        -o /dev/null \
        -w %{http_code}\\n \
        http://127.0.0.1:8445/v1.0/_noop
      200
      >
      ```
    responses:
      200:
        description:
          200 OK is always returned by this endpoint.
        body:
          application/json:

/_health:
  description: |
    An HTTP GET to the ```/_health``` endpoint returns a JSON document
    which describes the health of the service.
  get:
    description: |
      The JSON document returned by an HTTP GET to the ```/_health```
      endpoint and the HTTP status code describe the health of the service.
      An HTTP status code of 200 OK is healthy and anything else is unhealthy.
      The top level "status" property in the JSON document will be "green" if the service
      is healthy and "red" if there's a problem.
      The "details" property of the JSON document contains a red/green style health entry
      for each service's components.
      The overall health is "red" if any of the dependant services are unhealthy.

      Two types of health check are possible. A quick health check
      does not confirm the health of all service components and will
      respond quickly. A comprehensive health check does check
      all service components. The ```quick``` query string parameter
      takes a boolean value to determine if a quick or comprehensive
      health check is performed.

      ##### Authentication
        * None (for now)

      ##### Usage Expectations
        * the external monitoring service will perform a quick health check every minute
        * the external monitoring service will perform a comprehensive health check 5 minutes
        * a load balancer sitting in front of the app tier will repeatedly and
          frequently issue a quick health check

      ##### Performance Expectations
        * quick - 99% of the time < 50 ms
        * comprehensive - 99% of the time < 3,050 ms
          (note 3,050 is determined by taking the default value for the
          ```max_time_in_ms_to_wait_for_component_health_checks```
          configuration option and adding 50 ms ie. changing the
          configuration option can be used to change the performance
          characteristics of the endpoint)

      ##### Example
      For example, below a sample of a healthy response to a request
      for a quick health check.

      ```bash
      >curl \
        -s \
        http://127.0.0.1:8445/v1.0/_health?quick=false | \
        jq
      {
        "status": "green",
        "details": {
          "docker remote api": {
            "status": "green",
            "details": {
              "connectivity": "green",
              "api version": "green"
            }
          }
        },
        "links": {
          "self": {
            "href": "http://127.0.0.1:8445/v1.0/_health"
          }
        }
      }
      >
      ```

    queryParameters:
      quick:
        displayName: quick
        type: boolean
        description:
          Determines if a quick or deep health check is performed.
          quick is true by default.
        example: true
        required: false
    responses:
      200:
        description:
          When everything is green a 200 OK is returned.
      500:
        description:
          something super nasty happened inside the service
      503:
        description:
          When something is red a 503 service unavailable is returned.


remove router-specific syntax in test RAML

#%RAML 0.8
title: gref
version: 1

baseUri: http://github.com/buddhamagnet/ramlapi
documentation:
  -  title: Overview

/testapi:
  description: Test API for the ramlapi package.
  get:
    displayName: get.
    queryParameters:
      country:
        name: country
        type: string
        description: User country code
        example: GB
        required: true
        pattern: "[a-z]{2}"
      city:
        name: City
        type: string
        description: User city name
        example: Adelaide
        required: true
  post:
    displayName: post
  put:
    displayName: put
  patch:
    displayName: patch
  head:
    displayName: head
  delete:
    displayName: delete

#%RAML 0.8
title: gref
version: 1

baseUri: http://github.com/buddhamagnet/ramlapi
documentation:
  -  title: Overview

/testapi:
  description: Test API for the ramlapi package.
  get:
    displayName: get.
    queryParameters:
      country:
        name: country
        type: string
        description: User country code
        example: GB
        required: true
        pattern: "{[a-z]{2}}"
      city:
        name: City
        type: string
        description: User city name
        example: Adelaide
        required: true
  post:
    displayName: post
  put:
    displayName: put
  patch:
    displayName: patch
  head:
    displayName: head
  delete:
    displayName: delete