Web Services - REST
Introduction
All the ESPON 2020 Database Web Services are currently hosted at https://database.espon.eu/api/ (for delivery D4).
The ESPON 2020 Database REST Web Services were developed so far for three major purposes:
- ESPON Database User Interfaces
- Other ESPON Tools: TIA Tool
- External Users
The last two categories are served by the same list of Web Services for the moment (which are public - example: https://database.espon.eu/api/public/indicators/). When there will be some special requests from other ESPON Tools to develop dedicated/personalized Web Services, they will be added in the second category and made private.
The REST Web Services used in the ESPON DB were developed using the Django REST Framework (http://www.tomchristie.com/rest-framework-2-docs/), which is a flexible and powerful toolkit for easily building Web APIs. This framework was chosen due to numerous features, such as: authentication policies, serialization support, flexible views and extensive documentation and community support.
Serializers allow complex data (such as querrysets and model instances) to be converted to Python datatypes that can then be easily rendered into JSON, XML or other formats. Serializers also provide deserialization to convert parsed data back into complex types. In ESPON Database Project we have created serializers classes for all the major tables/concepts (i.e. indicator, project, dataset, group, nomenclature, etc.), to be able to expose them further on as Web Services (views). Once the serializers were created, we have defined the views (ViewSets) for all the Web Services. ViewSets provide different useful operations for the serializers attribtes and handle automatically the constructions of URLs.
Web Services usage
Filters
For all Web Services, we have pagination (considering the increasing number of data that are now available in the database) and filtering options in the API interface. The filtering is available for all the listed attributes available for the selected table and it is provided using the Django REST Framework support for the generic filtering backends that allow to easily construct complex searches and filters. Generic filters can also present themselves as HTML controls in the browsable API and admin API (see Figure 1).
Fig:1 Web Services filtering (click to enlarge)
Common messages for the REST Web Services
REST APIs uses the status line part of an HTTP response message to inform clients of their query results. The status line syntax is defined by RFC 2616 and we propose to consider the following codes to help the clients in processing the response body correctly (Table 1)
Codes | Description |
200 | Successful and includes response body |
201 | Created. There may also be times when a new resource is created as a result of some controller action, in which case 201 would also be an appropriate response. The newly created resource can be referenced by the URI(s) returned in the entity of the response, with the most specific URI for the resource given by a Location header field. The origin server MUST create the resource before returning the 201 status code. If the action cannot be carried out immediately, the server SHOULD respond with 202 (Accepted) response instead. |
202 | Accepted. Its purpose is to allow a server to accept a request for some process (perhaps a batch-oriented process that is only run once per day...) without requiring that the user agent’s connection to the server persist until the process is completed. The entity returned with this response SHOULD include an indication of the request’s current status and either a pointer to a status monitor (job queue location) or some estimate of when the user can expect the request to be fulfilled. |
401 | Unauthorized. The client tried to operate on a protected resource without providing the proper authorization. It may have provided the wrong credentials or none at all. The response must include a WWW-Authenticate header field containing a challenge applicable to the requested resource. |
403 | Forbidden. You don't have permission to access [directory] on this server |
404 | Not Found. The REST API can’t map the client’s URI to a resource but may be available in the future. |
405 | Method Not Allowed. The client tried to use an HTTP method that the resource does not allow. Ex: the resource could support GET and POST, but not PUT or DELETE. |
500 | Internal Server Error. Server error, independent from client activity. |
Tab:1 Web Services HTTP response messages
Due to performance reasons, some of the Web Services created to serve specifically for the ESPON Database Search and Download interface have a particular structure and limited information on the items (only what is needed to be visible in the user interface).
The public version of these services is more general and comprises full information needed by public use.
All Web Services retrieve a list of items from the database (indicators, datasets, projects, …). If one wants to retrieve details only about a specific item, he can use the same URL plus adding the item id at the end: URL/<id>. Examples for this will be shown next.
To be able to use the data from the Web Services, the user must make use of a specialized software client, able to parse the data JSON structure.
List of Web Services used in th ESPON User Interface
Fig:2 Web Services list (click to enlarge)
REST Web Service retrieving the list of indicators:
https://database.espon.eu/api/select/indicators/
REST Web Service retrieving the indicator data:
https://database.espon.eu/api/select/indicator-data/
REST Web Service retrieving the list of sets (datasets or ligh grouping):
https://database.espon.eu/api/select/sets/
REST Web Service retrieving the list of projects:
https://database.espon.eu/api/select/projects/
REST Web Service retrieving the list of nomenclatures:
https://database.espon.eu/api/select/nomenclatures/
REST Web Service retrieving the list of geometries:
https://database.espon.eu/api/select/gis/
REST Web Service retrieving the detail information for a specified item:
Format: https://database.espon.eu/api/select/indicators/<id>
Example: https://database.espon.eu/api/select/indicators/391/
Due to performance reasons, the Web Services created to serve specifically for the ESPON Database Search and Download interface have a particular structre and limited information on the items (only what is needed to be visible in the user interface).
Other Web Services will be develop in the same style for the Search and Downlaod interface, to serve all the Search and Advanced Search fields and not only.
List of external Web Services:
So far, we have develop Web Services to allow connection of other ESPON Tools to the ESPON Database, such as TIA Tool. These Web Services were develop on demand, based on the requests made by the TIA Tool development team.
All the external Web Services will be enhanced in the future with security features as Django REST Framework allows authentications mechanisms to be integrated directly within the Web Services functionality.