RegistrationAPI
This API definition uses RAML 0.8, which is not supported by the shared HTML renderer. The source is shown below.
#%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.1
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: DNS-SD Advertisement
content: |
Registration APIs MUST produce an mDNS advertisement of the type \_nmos-registration.\_tcp. This MAY be accompanied by a unicast DNS announcement of the same type.
The IP address and port of the Registration API MUST be identified via the DNS-SD advertisement, with the full HTTP path then being resolved via the standard NMOS API path documentation.
Multiple DNS-SD advertisements for the same API are permitted where the API is exposed via multiple ports and/or protocols.
- title: DNS-SD TXT Records
content: |
**api\_proto**
The DNS-SD advertisement MUST be accompanied by a TXT record of name 'api\_proto' with a value of either 'http' or 'https' dependent on the protocol in use by the Registration API web server.
**api\_ver**
The DNS-SD advertisement MUST be accompanied by a TXT record of name 'api\_ver'. The value of this TXT record is a comma separated list of API versions supported by the server. For example: 'v1.0,v1.1,v2.0'. There should be no whitespace between commas, and versions should be listed in ascending order.
**pri**
The DNS-SD advertisement MUST include a TXT record with key 'pri' and an integer value. Servers MAY additionally represent a matching priority via the DNS-SD SRV record 'priority' and 'weight' as defined in RFC 2782. The TXT record should be used in favour to the SRV priority and weight where these values differ in order to overcome issues in the Bonjour and Avahi implementations.
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.
- title: Versioning
content: |
A Registration API may support multiple API versions at one time, provided data exposed from each of these versioned endpoints matches the schema for that API version. A Node registering with a Registration API should do so using only one version at a time, which should be the highest version which both the Node and the Registration API support. See the [APIs](../docs/2.0. APIs.md) and [Upgrade Path](../docs/6.0. Upgrade Path.md) documentation for more details.
/:
displayName: Base
get:
description: List of paths available from this API
body:
schema: EmptySchema
responses:
200:
body:
example: !include ../examples/registrationapi-v1.1-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.1-resource-post-request.json
schema: !include schemas/registrationapi-resource-post-request.json
responses:
200:
body:
example: !include ../examples/registrationapi-v1.1-resource-post-200.json
schema: !include schemas/registrationapi-resource-response.json
headers:
Location:
example: /x-nmos/registration/v1.1/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.1-resource-post-200.json
schema: !include schemas/registrationapi-resource-response.json
headers:
Location:
example: /x-nmos/registration/v1.1/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.1-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.1-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.1-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