RESTful Interfaces of the Virima API Specification - Common Behaviors

Version: 0.1

Last Updated: 24 Dec 2024 07:03:05 GMT

This document specifies constraints that apply to all of the requests and responses that occur in the RESTful Interfaces supported by the Virima API, hereinafter referred to as the "API".

Contents

1 Imperative Specification Terms
2 Transport Protocol
3 Media Types
4 Request Headers
5 Request Parameters
6 Response Headers
7 Standard HTTP Status Codes
8 Error Response Message Bodies

8.1 Introduction
8.2 Data Models

8.2.1 Messages Data Model
8.2.2 Message Data Model

9 Version Request Type

9.1 Introduction
9.2 Version Data Model

Imperative Specification Terms

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document, and all other documents that comprise the specification of the RESTful Interfaces, are to be interpreted as described in "Key words for use in RFCs to Indicate Requirement Levels" (RFC 2119).

Transport Protocol

All API Interfaces are based on the Hypertext Transfer Protocol, version 1.1 (RFC 2616). Each request is authenticated using HTTP Basic Authentication (RFC 2617). Therefore, requests sent from clients on the public Internet (and not on a secure channel such as a VPN) MUST use the https protocol.

Media Types

Resource representations and request bodies are normally encoded in JSON, as specified in RFC 4267.

The API MUST provide representations of all resources available in JSON. The API MUST accept requests from clients encoded in JSON.

Request Headers

In requests made to services implementing the Virima API, several HTTP headers are used:

Header	Supported Values	Description of Use	Required
Accept	Comma-delimited list of media types or media type patterns.	Indicates to the server which media type(s) this client is prepared to accept.	Recommended, on requests that produce a response message body.
Authorization	"Basic" plus username and password (per RFC 2617).	Identifies the authorized user making the request.	Yes, on all requests.
Content-Length	Length (in bytes) of the request message body.	Describes the size of the message body.	Yes, on requests containing a message body.
Content-Type	Media type describing the request message body. For example, text/plain, application/json	Describes the representation and syntax of the request message body.	Yes, on requests containing a message body.
Host	Identifies the origin host receiving the message.	Required to allow support of multiple origin hosts at a single IP address.	Yes, on all requests. Note that since a single space may spread its URIs across multiple hosts, this may need to be re-set for each request.

Note that, since all interactions with RESTful Interfaces of the Virima APIs are stateless, no Cookie header (or any other mechanism to provide a session identifier) is used.

Request Parameters

Since the URI space is controlled by the server, client programs MUST NOT make any assumptions regarding the meaning of request parameters.

Response Headers

In responses returned by the API, several HTTP headers are used:

Header	Supported Values	Description of Use	Required
Content-Length	Length (in bytes) of the response message body.	Describes the size of the message body.	Yes, on responses containing a message body.
Content-Type	Media type describing the response message body.	Describes the representation and syntax of the response message body.	Yes, on responses containing a message body.
Location	Canonical URI of a newly created resource.	Returns a new URI that can be used to request a representation of the newly created resource.	Yes, on responses to requests that create new server side resources accessible via a URI.

Standard HTTP Status Codes

The API will return standard HTTP response codes, under the following conditions.

HTTP Status	Description
200 OK	The request was successfully completed. If this request created a new resource that is addressable with a URI, and a response body is returned containing a representation of the new resource, a 200 status will be returned with a Location header containing the canonical URI for the newly created resource.
201 Created	A request that created a new resource was completed, and no response body containing a representation of the new resource is being returned. A Location header containing the canonical URI for the newly created resource should also be returned.
202 Accepted	The request has been accepted for processing, but the processing has not been completed. Per the HTTP/1.1 specification, the returned entity (if any) SHOULD include an indication of the request's current status, and either a pointer to a status monitor or some estimate of when the user can expect the request to be fulfilled.
204 No Content	The server fulfilled the request, but does not need to return a response message body.
400 Bad Request	The request could not be processed because it contains missing or invalid information (such as a validation error in an input field or a missing required value).
401 Unauthorized	The authentication credentials included with this request are missing or invalid.
403 Forbidden	The server recognized the user's credentials, but the user does not possess authorization to perform this request.
404 Not Found	The request specified a URI of a resource that does not exist.
405 Method Not Allowed	The HTTP verb specified in the request (DELETE, GET, HEAD, POST, PUT) is not supported for this request URI.
406 Not Acceptable	The resource identified by this request is not capable of generating a representation corresponding to one of the media types in the Accept header of the request.
409 Conflict	A create or update request could not be completed, because it would cause a conflict in the current state of the resources supported by the server (for example, an attempt to create a new resource with a unique identifier which is already assigned to an existing resource).
500 Internal Server Error	The server encountered an unexpected condition, which prevented it from fulfilling the request.
501 Not Implemented	The server does not support the functionality required to fulfill the request.
503 Service Unavailable	The server is currently unable to handle the request due to temporary overloading or maintenance of the server.

Error Response Message Bodies

Introduction

Successful requests will return an HTTP status code of 200 (OK), 201 (Created), or 204 (No Content), to indicate the requested action has been successfully performed. In addition, the response might include a response message body (with an appropriate media type) containing a representation of the requested information. However, it is possible for a number of things to go wrong. The underlying causes are described (as discussed in the previous section) by HTTP status codes in the range 400-499 for client side errors and 500-599 for server side problems. The description of each request type SHOULD list the possible status codes returned by the request type.

If a response is returned with an error status code (400-499 or 500-599), the server SHOULD also return a response message body containing a messages data model, containing zero or more message data models, describing the error.

Data Models

The following generic data models are used to communicate error and status information. Note that these data models, while discussed in the context of reporting error conditions, are also suitable for a general event logging interface.

Messages Data Model

The entire list of messages included in an error response are encapsulated in a messages data model. The media type is application/json.

Field Name	Type	Occurs	Description
messages	Message	0..n	Zero or more message data models for each error response.

Message Data Model

An individual message contains the following fields:

Field Name	Type	Occurs	Description
action	String	0..1	Symbolic identifier of the action being performed by the service implementation that triggered the creation of this message.
code	String	0..1	Symbolic error code identifying the type of error reported by this message.
field	String	0..1	Name of the input field (from the request data model) with which this message is associated. If not specified, this message should be considered global to the entire request.
hint	String	0..1	Localized text further describing the nature of the problem, possibly including potential workarounds the API user could try.
severity	String	0..1	Label indicating the severity of the error condition represented by this message (SEVERE, WARNING, CONFIG, INFO, FINE, FINER, FINEST), in decreasing order of severity.
source	String	0..1	Symbolic identifier of the service implementation component that triggered this message.
stack-trace	String	0..1	Stack trace associated with this message.
text	String	1	Localized text describing the nature of the problem reported by this message.

SECURITY NOTE: The action, source, and stack-trace fields may convey sensitive information about the service implementation, and generally WILL NOT be included in messages returned to third party clients outside the Virima firewall. However, they MAY be used in messages transmitted between internal application components.

Version Request Type

Introduction

Each instance of an API request MUST include a request type that allows a client to determine the version of the particular API instance. The version should consist of the specification version(s) supported by this API instance, as well as an implementation version. This request type SHOULD have a URI matching {ServiceURI}/versions.

Version Data Model

The data model contains the following fields:

Field Name	Type	Occurs	Description
implementation_version	String	1	Implementation version identifier for this service instance.
specification_version	String	1	Comma-delimited list of the specification version(s) supported by this service instance.