HTTP Schema Resource¶
An HTTP Schema Resource is a JSON resource providing a detailed description of the HTTP methods supported by an HTTP resource and is intended to be provided as the entity body on a successful response of the HTTP OPTIONS method.
An HTTP Schema Resource is an OpenAPI [openapi] Operations object. The
definition of HTTP Schema Resource extends the definition of OpenAPI
Media Type such that Media Type objects MUST provide a schema property
and a context property. The value of a Media Type schema property
MUST be the URI of a schema defining valid content for the Media Type. The
value of a Media Type context property MUST be the URI of an RDF
context resource for the Media Type.
Example¶
{
"get": {
"responses": {
"200": {
"description": "OK"
, "content": {
"application/json": {
"context": "<json-ld context url>"
, "schema": "<json-schema url>"
}
}
}
}
}
, "put": {
"requestBody": {
"description": "The updated content for the resource."
, "required": true
, "content": {
"application/json": {
"context": "<json-ld context url>"
, "schema": "<json-schema url>"
}
}
}
, "responses": {
"200": {
"description": "OK"
, "content": {
"application/json": {
"context": "<json-ld context url>"
, "schema": "<json-schema url>"
}
}
}
, "400": {
"description": "BAD REQUEST: The request was malformed or
missing required content."
, "content": {
"application/json": {
"context": "<json-ld context url for error objects>"
, "schema": "<json-schema url for error objects>"
}
}
}
, "401": {
"description": "UNAUTHORIZED: The request requires
authentication."
}
, "403": {
"description": "FORBIDDEN: The requires requires
permissions the current authenticated
request does not have."
}
}
}
, "delete": {
"responses": {
"200": {
"description": "OK"
}
, "400": {
"description": "BAD REQUEST: The request was malformed or
missing required content."
, "content": {
"application/json": {
"context": "<json-ld context url for error objects>"
, "schema": "<json-schema url for error objects>"
}
}
}
, "401": {
"description": "UNAUTHORIZED: The request requires
authentication."
}
, "403": {
"description": "FORBIDDEN: The requires requires permissions
the current authenticated request does not
have."
}
}
}
}
JSON Schema¶
{
"$id": "TBD"
, "$schema": "http://json-schema.org/draft-04/schema"
, "title": "HTTP Schema Resource"
, "description": "A resource detailing the HTTP methods supported by a resource along with links to a schema describing that resource and a linked data description of the resource."
, "type": "object"
, "properties": {
"get": { "$ref": "#/definitions/HttpMethod" }
, "put": { "$ref": "#/definitions/HttpMethod" }
, "post": { "$ref": "#/definitions/HttpMethod" }
, "delete": { "$ref": "#/definitions/HttpMethod" }
, "options": { "$ref": "#/definitions/HttpMethod" }
}
, "definitions": {
"HttpMethod": {
"type": "object"
, "$$target": "#/definitions/HttpMethod"
, "description": "An HTTP Method"
, "properties": {
"requestBody": { "$ref": "#/definitions/HttpRequestEntity" }
,"responses": {
"type": "object"
, "description": "A dictionary of valid HttpResponseEntity for the request, by HTTP response code."
, "additionalProperties": { "$ref": "#/definitions/HttpResponseEntity" }
}
}
}
, "HttpRequestEntity": {
"type": "object"
, "description": "The entity that must be provided with the request."
, "properties": {
"description": { "type": "string" }
, "required": { "type": "boolean" }
, "content": { "$ref": "#/definitinos/EntityContent" }
}
}
, "HttpResponseEntity": {
"type": "object"
, "description": "An HTTP response."
, "properties": {
"description": { "type": "string" }
, "content": { "$ref": "#/definitions/EntityContent" }
}
}
, "EntityContent": {
"type": "object"
, "description": "An object whose property keys are MIME types and property values are objects describing the MIME type."
, "additionalProperties": { "$ref": "#/definitions/EntityContentType" }
}
, "EntityContentType": {
"type": "object"
, "description": "Details about resources defining and/or describing a specific entity content type."
, "properties": {
"context": {
"type": "string"
, "description": "If the entity may be mapped into RDF, this property **MUST** be the URL of a resource defning how to map the entity to RDF statemensts. For example, the URL of a JSON-LD context."
}
, "schema": {
"type": "string"
, "description": "If the entity is described by a schema defining valid and/or expected content of the entity, this property **MUST** be the URL of a resource defining the schema for the entity. For example, a JSON Schema."
}
}
}
}
}
JSON-LD Context¶
{
"xsd": "http://www.w3.org/2001/XMLSchema#"
, "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
, "rdfs": "http://www.w3.org/2000/01/rdf-schema#"
, "http": "http://www.w3.org/2011/http#"
, "http-methods": "http://www.w3.org/2011/http-methods#"
, "get": { "@id": "http-methods:GET" }
, "post": { "@id": "http-methods:POST" }
, "put": { "@id": "http-methods:PUT" }
, "delete": { "@id": "http-methods:DELETE" }
, "options": { "@id": "http-methods:OPTIONS" }
, "title": { "@id": "rdfs:label" }
, "description": { "@id": "rdfs:comment" }
TBD...
}
HTTP Examples¶
OPTIONS¶
Request¶
OPTIONS /api/person/foo HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Basic V2h5IGFyZSB5b3UgbG9va2luZyBhdCB0aGlzPyBJdCdzIGEgc2VjcmV0IQ==
Response¶
HTTP/1.1 200 OK
Date: Thu, 04 Apr 2019 15:15:15 GMT
Content-Length: XXXXX
Content-Type: application/json
Last-Modified: Mon, 20 Jul 2015 14:15:15 GMT
ETag: "XXXX"
Link: <http://scrud.io/schemas/semantic_http.json>; rel=”describedby”
Link: <https://scrud.io/contexts/semantic_http.json>;
rel="http://www.w3.org/ns/json-ld#context";
type="application/ld+json"
{
"get": {
"responses": {
"200": {
"description": "OK"
, "content": {
"application/json": {
"context": "<json-ld context url>"
, "schema": "<json-schema url>"
}
}
}
}
}
, "put": {
"requestBody": {
"description": "The updated content for the resource."
, "required": true
, "content": {
"application/json": {
"context": "<json-ld context url>"
, "schema": "<json-schema url>"
}
}
}
, "responses": {
"200": {
"description": "OK"
, "content": {
"application/json": {
"context": "<json-ld context url>"
, "schema": "<json-schema url>"
}
}
}
, "400": {
"description": "BAD REQUEST: The request was malformed or
missing required content."
, "content": {
"application/json": {
"context": "<json-ld context url for error objects>"
, "schema": "<json-schema url for error objects>"
}
}
}
, "401": {
"description": "UNAUTHORIZED: The request requires
authentication."
}
, "403": {
"description": "FORBIDDEN: The requires requires
permissions the current authenticated
request does not have."
}
}
}
, "delete": {
"responses": {
"200": {
"description": "OK"
}
, "400": {
"description": "BAD REQUEST: The request was malformed or
missing required content."
, "content": {
"application/json": {
"context": "<json-ld context url for error objects>"
, "schema": "<json-schema url for error objects>"
}
}
}
, "401": {
"description": "UNAUTHORIZED: The request requires
authentication."
}
, "403": {
"description": "FORBIDDEN: The requires requires permissions
the current authenticated request does not
have."
}
}
}
}