Versioning and Error Handling

Versioning in RESTful Web Services

RESTful web services should employ an implicit model for providing of API versioning information. Versions should not be explicitly included in the URIs but provided in a separate version resource which is located in the URI space of the corresponding RESTful service. The format of the version resource is explained below.

Versioning Resources

Field	Type	Resolution	Description
implementationVersion	String	mandatory	Implementation version for this service instance.
specificationVersion	String	mandatory	Specification version supported by this service instance.
compatibleSpecificationVersions	String[]	optional	Specification versions which this specification version of the service instance is compatible with.
compatibleImplementationVersions	String[]	optional	Implementation versions which this implementation version of the service instance is compatible with.

Error Handling for RESTful Web Services

Successful requests must generally return an HTTP status code of 200 (OK), 201 (Created), 202(Accepted), 204 (No Content), or 303 (See Other) in order to indicate that the requested action has been successfully performed. In addition, they might include a response message body (with an appropriate media type) containing a representation of the requested resources. If a response is returned with an error status code (400-499 for client error, 500-599 for server error) then the server should also return a response message body containing an error representation further describing the cause of the problem. More detailed codes further describing and categorizing some possible general errors are defined in the table below. Various RESTful web services may define more application error codes which are relative to the specific semantics and behavior of the particular web service. Such error codes shall be defined in similar manner in the specification of the RESTful web service.

Error Description

An error description should be transferred to the client each time the server encounters an error while processing the request. The resource describing errors shall be formatted as follows:

Field	Type	Resolution	Description
status	Integer	mandatory	HTTP status code. Please refer to the specification of the relevant RESTful web API for the list of possible HTTP error codes for the supported resource operations.
code	Integer	mandatory	Application-specific error code that further describes the error. Please refer to the specification of the relevant RESTful web API for the list of possible application-specific error codes for the supported resource operations. If the application-specific error code is set to 50010 Composite Error then multiple errors must have caused the generation of the error response. In this case fields source, description, hint, exception may be omitted and field errors must contain a collection of embedded Error Description representations describing each error.
description	String	optional	User-friendly description of the error which caused the generation of an error response. If the application-specific error code is set to 50010 Composite Error then this field may be omitted.
hint	String	optional	User-friendly hint that would help the user or developer better understand or resolve the error which caused the generation of an error response. If the application-specific error code is set to 50010 Composite Error then this field may be omitted.
source	String	optional	Name of the resource field or URI parameter which caused the generation of an error response. If the error is not sourced by a particular field or the application-specific error code is set to 50010 Composite Error then this field may be omitted.
exception	Exception	optional	Exception Description holding information for the exception, in case this error message is generated due to the underlying service implementation throwing an exception. If there is no particular exception associated with the error or the application-specific error code is set to 50010 Composite Error then this field may be omitted.
errors	Error Description []	optional	Collection of Error Description representations describing multiple errors which has caused the generation of an error response. This field is present if the application-specific error code is not set to 50010 Composite Error, otherwise it is omitted.

Exception Description

Field	Type	Resolution	Description
name	String	mandatory	Fully qualified name of the exception that was thrown by the underlying services.
code	Integer	optional	Code of the exception, if there is such that was thrown by the underlying services.
message	String	optional	Message description of the exception, if there is such that was thrown by the underlying services.
cause	Exception	optional	Cause of the exception, in case of nested exceptions that was thrown by the underlying services.
stacktrace	String	optional	Stack trace of the exception that was thrown by the underlying services.

API-specific Error Codes

It is recommended that RESTful web services define detailed application-specific error codes that further describe and categorize the possible errors which are relative to the specific semantics and behavior of the particular web service. Such error codes shall be defined in the specification of the RESTful web service and clarified in the resource operations. Several application-specific error codes that describe general errors are defined in the table below:

Error Status	Description
50000 Unknown Error	Identifies that the operation over the representation of a particular resource cannot be performed by the server due to the occurrence of unknown or unexpected error.
50010 Composite Error	Identifies that the operation over the representation of a particular resource cannot be performed by the server due to the occurrence of multiple errors which may originate from different fields and can be identifier with different application error codes, descriptions and hints. This error code is commonly used in case of resource operations that are neither transactional, nor atomic and result in multiple operations being invoked on the underlying services, e.g. creation of resources or update of multiple resource fields which may cause multiple validation and/or invocation errors. If this error code is set for the code then fields source, description, hint, exception may be omitted and field errors must contain a collection of embedded Error Description representations describing each error.
50001 Gateway Not Found	Identifies that the operation over the representation of a particular resource cannot be performed by the server due to the resource being associated with a certain gateway which does not exist or cannot be found by the server.
50002 Illegal Gateway State	Identifies that the operation over the representation of a particular resource cannot be performed by the server due to the resource being associated with a certain gateway which is not in the requested state, e.g. the gateway is disconnected or not accessible.
50020 Invalid LDAP Filter Syntax	Identifies that the requested filtering operation over a set of particular resources cannot be performed by the server due to invalid syntax of a provided via a query parameter LDAP filter.
50021 Invalid Field Representation Constraints Syntax	Identifies that the requested constraints for a particular resource or set of resources cannot be satisfied by the server due to invalid syntax of the provided expression. For more information, please see expand, exclude, include query parameters and X-Representation-Expand, X-Representation-Exclude, X-Representation-Include HTTP headers.
50030 Illegal Query Parameters	Identifies that the operation over the representation of a particular resource cannot be performed by the server due to the request containing invalid or incompatible query parameters.
50040 Illegal Pagination Parameters	Identifies that the operation over the representation of a particular collection resource cannot be performed by the server due to request containing invalid pagination parameters.
50050 Insufficient Permissions	Identifies that the operation over the representations of a particular resource is forbidden by the server due the client application not having the requested permissions.