RegistrationAPI

#%RAML 0.8

# AMWA NMOS Discovery and Registration Specification: Registration API
# (c) AMWA 2016

title: Registration
baseUri: http://example.api.com/x-nmos/registration/{version}
version: v1.0
mediaType: application/json
schemas:
  - EmptySchema: !include schemas/empty.json
    ErrorSchema: !include schemas/error.json
documentation:
  - title: Overview
    content: |
      The Registration API is exposed by NMOS discovery Nodes. It is used to publish data to the distributed registry, which can then be queried via the Query API. In smaller deployments where no distributed registry is available, the Registration API is not used and discovery responsibilities fall to individual Nodes which choose to implement Peer to Peer specification. The Registration API is a Write Only API.
  - title: mDNS Advertisement
    content: |
      Registration APIs MUST produce an mDNS advertisement of the type \_nmos-registration.\_tcp

      The mDNS advertisement MUST include a TXT record with key 'pri' and an integer value. Values 0 to 99 correspond to an active NMOS Registration API (zero being the highest priority). Values 100+ are reserved for development work to avoid colliding with a live system. NB: In future versions of the specification it is likely that the 'priority' and 'weight' as specified by RFC 2782 will be used.

      The IP address and port of the registration API MUST be identified via the mDNS advertisement, with the HTTP path then being resolved via the standard NMOS API path documentation.

/:
  displayName: Base
  get:
    description: List of paths available from this API
    body:
      schema: EmptySchema
    responses:
      200:
        body:
          example: !include ../examples/registrationapi-v1.0-base-get-200.json
          schema: !include schemas/registrationapi-base.json
/resource:
  displayName: Resource
  post:
    description: Create or update a registered resource
    body:
      example: !include ../examples/registrationapi-v1.0-resource-post-request.json
      schema: !include schemas/registrationapi-v1.0-resource-post-request.json
    responses:
      200:
        body:
          example: !include ../examples/registrationapi-v1.0-resource-post-200.json
          schema: !include schemas/registrationapi-resource-response.json
        headers:
          Location:
            example: /x-nmos/registration/v1.0/resource/nodes/3b8be755-08ff-452b-b217-c9151eb21193/
        description: The expected response for an update operation on an existing registered resource
      201:
        body:
          example: !include ../examples/registrationapi-v1.0-resource-post-200.json
          schema: !include schemas/registrationapi-resource-response.json
        headers:
          Location:
            example: /x-nmos/registration/v1.0/resource/nodes/3b8be755-08ff-452b-b217-c9151eb21193/
        description: The expected response for a create operation performed for a previously unregistered resource
      400:
        description: Returned when the POST request is incorrectly formatted or missing mandatory attributes
        body:
          schema: ErrorSchema
  /{resourceType}/{resourceId}:
    uriParameters:
      resourceId:
        type: string
        pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
      resourceType:
        type: string
        enum: [
          "nodes",
          "devices",
          "sources",
          "flows",
          "senders",
          "receivers"
        ]
    delete:
      description: Delete a registered resource
      body:
        schema: EmptySchema
      responses:
        204:
          description: The expected response, indicating 'No Content' following the DELETE
        404:
          description: Returned when the requested resource does not exist
          body:
            schema: ErrorSchema
    get:
      description: Show a registered resource (for debug use only)
      body:
        schema: EmptySchema
      responses:
        200:
          body:
            example: !include ../examples/registrationapi-v1.0-resource-get-200.json
            schema: !include schemas/registrationapi-resource-response.json
        404:
          description: Returned when the requested resource does not exist
          body:
            schema: ErrorSchema
/health/nodes/{nodeId}:
  displayName: Node health
  uriParameters:
    nodeId:
      type: string
      pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
  post:
    description: Update Node health
    body:
      schema: EmptySchema
    responses:
      200:
        body:
          example: !include ../examples/registrationapi-v1.0-health-post-200.json
          schema: !include schemas/registrationapi-health-response.json
      404:
        description: Returned when the requested Node does not exist or has been garbage collected
        body:
          schema: ErrorSchema
  get:
    description: Show a Node's health (for debug use only)
    body:
      schema: EmptySchema
    responses:
      200:
        body:
          example: !include ../examples/registrationapi-v1.0-health-get-200.json
          schema: !include schemas/registrationapi-health-response.json
      404:
        description: Returned when the requested Node does not exist or has been garbage collected
        body:
          schema: ErrorSchema