From 597f13903f28727f34ed28aeb9097429b28f6cfa Mon Sep 17 00:00:00 2001 From: Andrew Bonney Date: Thu, 13 Oct 2016 09:42:52 +0100 Subject: [PATCH] schemas: add further schemas where missing --- APIs/NodeAPI.raml | 62 +++++++++++++ APIs/QueryAPI.raml | 87 +++++++++++++++++++ APIs/RegistrationAPI.raml | 45 +++++++++- APIs/schemas/empty.json | 10 +++ APIs/schemas/error.json | 27 ++++++ APIs/schemas/nodeapi-base.json | 20 +++++ APIs/schemas/queryapi-base.json | 21 +++++ .../queryapi-subscription-response.json | 45 ++++++++++ .../queryapi-subscriptions-response.json | 11 +++ APIs/schemas/registrationapi-base.json | 16 ++++ .../registrationapi-health-response.json | 16 ++++ .../registrationapi-resource-response.json | 14 +++ 12 files changed, 373 insertions(+), 1 deletion(-) create mode 100644 APIs/schemas/empty.json create mode 100644 APIs/schemas/error.json create mode 100644 APIs/schemas/nodeapi-base.json create mode 100644 APIs/schemas/queryapi-base.json create mode 100644 APIs/schemas/queryapi-subscription-response.json create mode 100644 APIs/schemas/queryapi-subscriptions-response.json create mode 100644 APIs/schemas/registrationapi-base.json create mode 100644 APIs/schemas/registrationapi-health-response.json create mode 100644 APIs/schemas/registrationapi-resource-response.json diff --git a/APIs/NodeAPI.raml b/APIs/NodeAPI.raml index 0626d1b0..6b4925bc 100644 --- a/APIs/NodeAPI.raml +++ b/APIs/NodeAPI.raml @@ -21,6 +21,8 @@ schemas: SenderTarget: !include schemas/sender-target.json Receiver: !include schemas/receiver.json Receivers: !include schemas/receivers.json + EmptySchema: !include schemas/empty.json + ErrorSchema: !include schemas/error.json documentation: - title: Overview content: | @@ -58,14 +60,19 @@ documentation: displayName: Base get: description: List of paths available from this API + body: + schema: EmptySchema responses: 200: body: example: !include ../examples/nodeapi-v1.0-base-get-200.json + schema: !include schemas/nodeapi-base.json /self: displayName: Self get: description: Get information about this Node + body: + schema: EmptySchema responses: 200: body: @@ -75,14 +82,22 @@ documentation: displayName: Sources get: description: List Sources + body: + schema: EmptySchema responses: 200: body: example: !include ../examples/nodeapi-v1.0-sources-get-200.json schema: Sources /{sourceId}: + uriParameters: + sourceId: + 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}$" get: description: Get a single Source + body: + schema: EmptySchema responses: 200: body: @@ -90,18 +105,28 @@ documentation: schema: Source 404: description: Returned when the requested Source ID does not exist + body: + schema: ErrorSchema /flows: displayName: Flows get: description: List Flows + body: + schema: EmptySchema responses: 200: body: example: !include ../examples/nodeapi-v1.0-flows-get-200.json schema: Flows /{flowId}: + uriParameters: + flowId: + 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}$" get: description: Get a single Flow + body: + schema: EmptySchema responses: 200: body: @@ -109,18 +134,28 @@ documentation: schema: Flow 404: description: Returned when the requested Flow ID does not exist + body: + schema: ErrorSchema /devices: displayName: Devices get: description: List Devices + body: + schema: EmptySchema responses: 200: body: example: !include ../examples/nodeapi-v1.0-devices-get-200.json schema: Devices /{deviceId}: + uriParameters: + deviceId: + 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}$" get: description: Get a single Device + body: + schema: EmptySchema responses: 200: body: @@ -128,18 +163,28 @@ documentation: schema: Device 404: description: Returned when the requested Device ID does not exist + body: + schema: ErrorSchema /senders: displayName: Senders get: description: List Senders + body: + schema: EmptySchema responses: 200: body: example: !include ../examples/nodeapi-v1.0-senders-get-200.json schema: Senders /{senderId}: + uriParameters: + senderId: + 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}$" get: description: Get a single Sender + body: + schema: EmptySchema responses: 200: body: @@ -147,18 +192,28 @@ documentation: schema: Sender 404: description: Returned when the requested Sender ID does not exist + body: + schema: ErrorSchema /receivers: displayName: Receivers get: description: List Receivers + body: + schema: EmptySchema responses: 200: body: example: !include ../examples/nodeapi-v1.0-receivers-get-200.json schema: Receivers /{receiverId}: + uriParameters: + receiverId: + 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}$" get: description: Get a single Receiver + body: + schema: EmptySchema responses: 200: body: @@ -166,11 +221,14 @@ documentation: schema: Receiver 404: description: Returned when the requested Receiver ID does not exist + body: + schema: ErrorSchema /target: put: description: Request a change to a Receiver's subscription body: example: !include ../examples/nodeapi-v1.0-receivertarget-put-request.json + schema: SenderTarget responses: 202: body: @@ -178,5 +236,9 @@ documentation: schema: SenderTarget 400: description: Returned when the PUT request is incorrectly formatted or missing mandatory attributes + body: + schema: ErrorSchema 404: description: Returned when the requested Receiver ID does not exist + body: + schema: ErrorSchema diff --git a/APIs/QueryAPI.raml b/APIs/QueryAPI.raml index 829f9835..71d69037 100644 --- a/APIs/QueryAPI.raml +++ b/APIs/QueryAPI.raml @@ -20,6 +20,8 @@ schemas: Senders: !include schemas/senders.json Receiver: !include schemas/receiver.json Receivers: !include schemas/receivers.json + EmptySchema: !include schemas/empty.json + ErrorSchema: !include schemas/error.json documentation: - title: Overview content: | @@ -37,22 +39,33 @@ documentation: displayName: Base get: description: List of paths available from this API + body: + schema: EmptySchema responses: 200: body: example: !include ../examples/queryapi-v1.0-base-get-200.json + schema: !include schemas/queryapi-base.json /nodes: displayName: Nodes get: description: List Nodes + body: + schema: EmptySchema responses: 200: body: example: !include ../examples/queryapi-v1.0-nodes-get-200.json schema: Nodes /{nodeId}: + 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}$" get: description: Get a single Node + body: + schema: EmptySchema responses: 200: body: @@ -60,10 +73,14 @@ documentation: schema: Node 404: description: Returned when the requested Node ID does not exist + body: + schema: ErrorSchema /sources: displayName: Sources get: description: List Sources + body: + schema: EmptySchema queryParameters: device_id: label: @@ -75,8 +92,14 @@ documentation: example: !include ../examples/queryapi-v1.0-sources-get-200.json schema: Sources /{sourceId}: + uriParameters: + sourceId: + 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}$" get: description: Get a single Source + body: + schema: EmptySchema responses: 200: body: @@ -84,10 +107,14 @@ documentation: schema: Source 404: description: Returned when the requested Source ID does not exist + body: + schema: ErrorSchema /flows: displayName: Flows get: description: List Flows + body: + schema: EmptySchema queryParameters: source_id: label: @@ -99,8 +126,14 @@ documentation: example: !include ../examples/queryapi-v1.0-flows-get-200.json schema: Flows /{flowId}: + uriParameters: + flowId: + 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}$" get: description: Get a single Flow + body: + schema: EmptySchema responses: 200: body: @@ -108,10 +141,14 @@ documentation: schema: Flow 404: description: Returned when the requested Flow ID does not exist + body: + schema: ErrorSchema /devices: displayName: Devices get: description: List Devices + body: + schema: EmptySchema queryParameters: node_id: label: @@ -122,8 +159,14 @@ documentation: example: !include ../examples/queryapi-v1.0-devices-get-200.json schema: Devices /{deviceId}: + uriParameters: + deviceId: + 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}$" get: description: Get a single Device + body: + schema: EmptySchema responses: 200: body: @@ -131,10 +174,14 @@ documentation: schema: Device 404: description: Returned when the requested Device ID does not exist + body: + schema: ErrorSchema /senders: displayName: Senders get: description: List Senders + body: + schema: EmptySchema queryParameters: flow_id: label: @@ -146,8 +193,14 @@ documentation: example: !include ../examples/queryapi-v1.0-senders-get-200.json schema: Senders /{senderId}: + uriParameters: + senderId: + 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}$" get: description: Get a single Sender + body: + schema: EmptySchema responses: 200: body: @@ -155,10 +208,14 @@ documentation: schema: Sender 404: description: Returned when the requested Sender ID does not exist + body: + schema: ErrorSchema /receivers: displayName: Receivers get: description: List Receivers + body: + schema: EmptySchema queryParameters: label: description: @@ -170,8 +227,14 @@ documentation: example: !include ../examples/queryapi-v1.0-receivers-get-200.json schema: Receivers /{receiverId}: + uriParameters: + receiverId: + 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}$" get: description: Get a single Receiver + body: + schema: EmptySchema responses: 200: body: @@ -179,6 +242,8 @@ documentation: schema: Receiver 404: description: Returned when the requested Receiver ID does not exist + body: + schema: ErrorSchema /subscriptions: displayName: Subscriptions post: @@ -190,32 +255,54 @@ documentation: 201: body: example: !include ../examples/queryapi-v1.0-subscriptions-post-200.json + schema: !include schemas/queryapi-subscription-response.json 200: body: example: !include ../examples/queryapi-v1.0-subscriptions-post-200.json + schema: !include schemas/queryapi-subscription-response.json 400: description: Returned when the POST request is incorrectly formatted or missing mandatory attributes + body: + schema: ErrorSchema get: description: List active connections to websockets providing real-time updates on resource changes + body: + schema: EmptySchema responses: 200: body: example: !include ../examples/queryapi-v1.0-subscriptions-get-200.json + schema: !include schemas/queryapi-subscriptions-response.json /{subscriptionId}: + uriParameters: + subscriptionId: + 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}$" get: description: Get a single subscription + body: + schema: EmptySchema responses: 200: body: example: !include ../examples/queryapi-v1.0-subscriptionid-get-200.json + schema: !include schemas/queryapi-subscription-response.json 404: description: Returned when the requested Subscription ID does not exist + body: + schema: ErrorSchema delete: description: Delete a single subscription + body: + schema: EmptySchema responses: 204: description: The expected response, indicating 'No Content' following the DELETE 403: description: Returned when a DELETE request is made against a non-persistent subscription which is managed by the Query API and cannot be deleted + body: + schema: ErrorSchema 404: description: Returned when the requested Subscription ID does not exist + body: + schema: ErrorSchema diff --git a/APIs/RegistrationAPI.raml b/APIs/RegistrationAPI.raml index d6ca3f3d..8067c3ab 100644 --- a/APIs/RegistrationAPI.raml +++ b/APIs/RegistrationAPI.raml @@ -7,6 +7,9 @@ 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: | @@ -23,10 +26,13 @@ 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: @@ -38,6 +44,7 @@ documentation: 200: body: example: !include ../examples/registrationapi-v1.0-resource-post-200.json + schema: !include schemas/registrationapi-resource-response.json headers: Location: example: /x-nmos/v1.0/registration/resource/nodes/3b8be755-08ff-452b-b217-c9151eb21193/ @@ -45,47 +52,83 @@ documentation: 201: body: example: !include ../examples/registrationapi-v1.0-resource-post-200.json + schema: !include schemas/registrationapi-resource-response.json headers: Location: example: /x-nmos/v1.0/registration/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: - description: One of 'nodes', 'devices', 'sources', 'flows', 'senders' or 'receivers' 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 diff --git a/APIs/schemas/empty.json b/APIs/schemas/empty.json new file mode 100644 index 00000000..72afc51b --- /dev/null +++ b/APIs/schemas/empty.json @@ -0,0 +1,10 @@ +{ + "$schema": "http://json-schema.org/draft-04/schema#", + "type": "object", + "description": "Describes an empty request or response", + "title": "Empty schema", + "required": [ + ], + "properties": { + } +} diff --git a/APIs/schemas/error.json b/APIs/schemas/error.json new file mode 100644 index 00000000..402147b5 --- /dev/null +++ b/APIs/schemas/error.json @@ -0,0 +1,27 @@ +{ + "$schema": "http://json-schema.org/draft-04/schema#", + "type": "object", + "description": "Describes the standard error response which is returned with HTTP codes 400 and above", + "title": "Error response", + "required": [ + "code", + "error", + "debug" + ], + "properties": { + "code": { + "description": "HTTP error code", + "type": "integer", + "minimum": 400, + "maximum": 599 + }, + "error": { + "description": "Human readable message which is suitable for user interface display, and helpful to the user", + "type": "string" + }, + "debug": { + "description": "Debug information which may assist a programmer working with the API", + "type": ["null", "string"] + } + } +} diff --git a/APIs/schemas/nodeapi-base.json b/APIs/schemas/nodeapi-base.json new file mode 100644 index 00000000..61dcdec8 --- /dev/null +++ b/APIs/schemas/nodeapi-base.json @@ -0,0 +1,20 @@ +{ + "$schema": "http://json-schema.org/draft-04/schema#", + "type": "array", + "description": "Describes the Node API base resource", + "title": "Node API base resource", + "items": { + "type": "string", + "enum": [ + "self/", + "sources/", + "flows/", + "devices/", + "senders/", + "receivers/" + ], + "minItems": 6, + "maxItems": 6, + "uniqueItems": true + } +} diff --git a/APIs/schemas/queryapi-base.json b/APIs/schemas/queryapi-base.json new file mode 100644 index 00000000..0cf5f72a --- /dev/null +++ b/APIs/schemas/queryapi-base.json @@ -0,0 +1,21 @@ +{ + "$schema": "http://json-schema.org/draft-04/schema#", + "type": "array", + "description": "Describes the Query API base resource", + "title": "Query API base resource", + "items": { + "type": "string", + "enum": [ + "nodes/", + "sources/", + "flows/", + "devices/", + "senders/", + "receivers/", + "subscriptions/" + ], + "minItems": 7, + "maxItems": 7, + "uniqueItems": true + } +} diff --git a/APIs/schemas/queryapi-subscription-response.json b/APIs/schemas/queryapi-subscription-response.json new file mode 100644 index 00000000..1888f34e --- /dev/null +++ b/APIs/schemas/queryapi-subscription-response.json @@ -0,0 +1,45 @@ +{ + "$schema": "http://json-schema.org/draft-04/schema#", + "type": "object", + "description": "A single subscription resource registered with a Query API", + "title": "Subscription resource", + "required": [ + "id", + "ws_href", + "max_update_rate_ms", + "persist", + "resource_path", + "params" + ], + "properties": { + "id": { + "description": "Globally unique identifier for the subscription", + "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}$" + }, + "ws_href": { + "description": "Address to connect to for the websocket subscription", + "type": "string", + "format": "uri" + }, + "max_update_rate_ms": { + "description": "Rate limiting for messages. Sets the minimum interval between consecutive websocket messages", + "type": "integer", + "default": 100 + }, + "persist": { + "description": "Whether to destroy the socket when the final client disconnects", + "type": "boolean", + "default": false + }, + "resource_path": { + "description": "HTTP resource path in the query API which this subscription relates to", + "type": "string", + "enum": ["/nodes", "/devices", "/sources", "/flows", "/senders", "/receivers"] + }, + "params": { + "description": "Object containing attributes to filter the resource on as per the Query Parameters specification. Can be empty.", + "type": "object" + } + } +} diff --git a/APIs/schemas/queryapi-subscriptions-response.json b/APIs/schemas/queryapi-subscriptions-response.json new file mode 100644 index 00000000..fe2b561b --- /dev/null +++ b/APIs/schemas/queryapi-subscriptions-response.json @@ -0,0 +1,11 @@ +{ + "$schema": "http://json-schema.org/draft-04/schema#", + "type": "array", + "description": "A list of subscription resources", + "title": "Collection of subscriptions", + "items": { + "$ref": "queryapi-subscription-response.json" + }, + "minItems": 0, + "uniqueItems": true +} diff --git a/APIs/schemas/registrationapi-base.json b/APIs/schemas/registrationapi-base.json new file mode 100644 index 00000000..07bf137d --- /dev/null +++ b/APIs/schemas/registrationapi-base.json @@ -0,0 +1,16 @@ +{ + "$schema": "http://json-schema.org/draft-04/schema#", + "type": "array", + "description": "Describes the Registration API base resource", + "title": "Registration API base resource", + "items": { + "type": "string", + "enum": [ + "resource/", + "health/" + ], + "minItems": 2, + "maxItems": 2, + "uniqueItems": true + } +} diff --git a/APIs/schemas/registrationapi-health-response.json b/APIs/schemas/registrationapi-health-response.json new file mode 100644 index 00000000..3ebac723 --- /dev/null +++ b/APIs/schemas/registrationapi-health-response.json @@ -0,0 +1,16 @@ +{ + "$schema": "http://json-schema.org/draft-04/schema#", + "type": "object", + "description": "Response to a request to update a resource's health", + "title": "Heartbeat response", + "required": [ + "health" + ], + "properties": { + "health": { + "description": "Timestamp indicating the time in seconds at which the server recorded the heartbeat", + "type": "string", + "pattern": "^[0-9]+$" + } + } +} diff --git a/APIs/schemas/registrationapi-resource-response.json b/APIs/schemas/registrationapi-resource-response.json new file mode 100644 index 00000000..f37657b2 --- /dev/null +++ b/APIs/schemas/registrationapi-resource-response.json @@ -0,0 +1,14 @@ +{ + "$schema": "http://json-schema.org/draft-04/schema#", + "type": "object", + "description": "Returning a registered resource from the Registration API", + "title": "Registered resource", + "oneOf": [ + {"$ref": "node.json"}, + {"$ref": "device.json"}, + {"$ref": "source.json"}, + {"$ref": "flow.json"}, + {"$ref": "sender.json"}, + {"$ref": "receiver.json"} + ] +}