We use proprietary and third party's cookies to improve your experience and our services, identifying your Internet Browsing preferences on our website; develop analytic activities and display advertising based on your preferences. If you keep browsing, you accept its use. You can get more information on our Cookie Policy
Cookies Policy
Common aspects in FI-WARE Open Restful API Specifications - FIWARE Forge Wiki

Common aspects in FI-WARE Open Restful API Specifications

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

How to read FI-WARE RESTful API Specifications

It is assumed that readers of FI-WARE RESTful API Specifications are familiarized with the REST architecture style. In particular, with:

  • RESTful web services
  • HTTP/1.1
  • JSON and/or XML data serialization formats

Some special notations are applied to differentiate some special words or concepts. The following list summarizes these special notations.

  • A bold, mono-spaced font is used to represent code or logical entities, e.g., HTTP method (GET, PUT, POST, DELETE).
  • An italic font is used to represent document titles or some other kind of special text, e.g., URI.
  • Variables are represented between brackets, e.g. {id} and in italic font. When the reader finds one, it can assume that the variable can be changed by any value.

Authentication

Each HTTP request in a FI-WARE RESTful API may require the inclusion of specific authentication credentials. The specific implementation of a the API implemented by a given Generic Enabler (GE) may support multiple authentication schemes (OAuth, Basic Auth, Token) to be determined by the specific provider that implements the GE. You should determine the best way to authenticate against a given API. Remember that some authentication schemes may require that the API operate using SSL over HTTP (HTTPS).

Notwithstanding the above, all FI-WARE RESTful APIs will evolve to support an authentication mechanism based on OAuth relying on the capabilities of a product in compliance with the Identity Management GE Open Specifications.

Representation Transport

Resource representation is transmitted between client and server by using HTTP 1.1 protocol, as defined by IETF RFC-2616. Each time an HTTP request contains payload, a Content-Type header shall be used to specify the MIME type of wrapped representation. In addition, both client and server may use as many HTTP headers as they consider necessary.

Representation Format

FI-WARE RESTful APIs may support XML or JSON as representation format for request and response parameters. Each API specification indicates which of them is the default format.

The request format is specified using the Content-Type header and is required for operations that have a request body. The response format can be specified in requests using either the Accept header or adding an .xml or .json query extension to the request URI. If there is a conflict between Accept header and a query extension, the query extension takes precedence.

Note that it is possible for a response to be serialized using a format different from the request.

Limits

We can manage the capacity of the system in order to prevent the abuse of the system through some limitations. These limitations will be configured by the operator and may differ from one implementation to other of the GE implementation.

Rate Limits

These limits are specified both in human readable wild-card and in regular expressions and will indicate for each HTTP verb which will be the maximum number of operations per time unit that a user can request. After each unit time the counter is initialized again. In the event a request exceeds the thresholds established for your account, a 413 HTTP response will be returned with a Retry-After header to notify the client when they can attempt to try again.

Absolute Limits

In this case, absolute values are specified, e.g. maximum total amount of RAM (MB).

Determining Limits Programmatically

Applications can use the GET verb with the /limits URI in order to retrieve this information.

VerbURIDescription
GET /limitsReturns the current limits for your account


This operation must return Normal response code(s), e.g. 200 or 203 and will have to manage some possible errors like compute fault, service unavailable, unauthorized operation, forbidden, bad request, bad method or operation over limit.

This operation will not need a request body but each FI-WARE RESTful API specifies what is the list of normal response code(s) and the list of error response code(s) followed by some examples in appropriate representation format (XML and/or JSON) of potential responses to this operation.

Extensions

FI-WARE RESTful APIs may support the notion of extendability, which allows the introduction of new features in without requiring an update of the version of the API and also allows the introduction of vendor specific functionality.

Applications can use the GET verb with the /limits URI in order to retrieve this information.

VerbURIDescription
GET /extensionsList of all available extensions


This operation will not need a request body but each FI-WARE RESTful API specifies what is the list of normal response code(s) and the list of error response code(s) followed by some examples in appropriate representation format (XML and/or JSON) of potential responses to this operation.

Personal tools
Create a book