data.fao.org API implementations

The data.fao.org website is being designed and developed following the Service Oriented Architecture (SOA) approach that includes a clear decoupling between the presentation and the process layer (see previous article for more information). This means that many resources such as information, maps, documents, photos, and more, can be easily shown in data.fao.org. It also means that operations performed by the website will be provided by a service. These processes will also be accessible directly through data.fao.org API implementations, without the intermediation of the Web interface.

The objective of the project is to provide APIs in a useful way in order to achieve our goal of bringing data together from many different FAO sources. There are two kinds of APIs provided by data.fao.org:

• Resource management APIs
• Process APIs

Resource Management APIs

The resource management APIs will allow you to add, retrieve, update, delete, browse and search resources inside the data.fao.org catalog, through the Web process in RESTful style (http://en.wikipedia.org/wiki/RESTful).

Resource management APIs provide the following two ways to access a resource:

• By a Universally Unique Identifier (UUID). For example: 22fcb0de-64bc-4ae0-a8f1-f2a190c79c1b
• By a “friendly name”, composed by the resource type collection name (for example: datasets, images, photos, documents, etc.), the database name (for example: glipha, countryprofiles, aquastat, etc.) and the resource name (for example: livestock-production, flag-argentina, etc.).

The UUID is more suitable for application-to-application communication because it is more efficient, compact, immutable and will never change even if the resource is renamed or moved to another database, unlike the “friendly name.”

The “friendly name” instead, is more easy to use by a “human” user because it is a significant identifier, unique only in the data.fao.org context, while the UUID is a “machine” code and therefore hard to remember.

In data.fao.org, a resource is a complex object that can be composed by more than one component. For example, a photo is a resource composed by a set of metadata and one or more binary streams containing the image files at different resolutions, a statistical dataset can be composed by metadata, statistical data and data structure, etc. The resource components in data.fao.org are called “datastream” and can be managed through the resource management APIs.

The following URL patterns are used to access the resource descriptors and the data streams:

• http://data.fao.org/uri/<resource-uuid>[/<datastream>]?<parameters>
• http://data.fao.org/resources/<resource-type-collection-name>/<database>/<resource-name>[/<datastream>]?<parameters>

Process APIs

Process APIs provide additional processes not strictly related to the CRUD (create, read, update and delete) operations on the data.fao.org resources.

Some examples of process APIs are:

• Multidimensional query - executes a multidimensional query on the data.fao.org data warehouse end and returns the result in different formats (for example: XML, JSON, CSV, etc.).
• Document conversion - performs the conversion of a document from one format to another (for example: PDF, HTML, DOC, ODT, etc.).
• Text translation - automatically translates a text fragment from one of the six official FAO language to another, using FAO specialized vocabulary.
• Map rendering - renders a map image using static geospatial layers and statistical information.
• And so on.

The following URL pattern can be used to access the process APIs: http://data.fao.org/api/<api-category>/<api-name>?<parameters>

Invoking APIs

To invoke resource management and process APIs, it is necessary to specify an API key called “authKey”, for example, c6fe9f2e-43ec-4fbe-b849-7ec361975d6c, that can be obtained after a self registration procedure directly from the data.fao.org website. This key can be specified either as a query string parameter or as an HTTP header and allow the human user or the client application to access the data.fao.org information or process. In the case of a client application, the key is bound to an IP address or web domain and the security layer of data.fao.org rejects any call coming from a different machine.

The requests and the responses of the APIs can be localized in different languages. To obtain a result in a specific language it is necessary to specify the query string parameter “lang” or the HTTP header “Accept-Language” (for example: en, fr, ar, etc.).

Moreover, it is also possible to obtain the result of a data.fao.org API call in different formats by specifying the required format in the “output” query string parameter (for example: XML, JSON, JSONP, CSV, etc.) or by specifying the relative MIME-Type in the “Accept” HTTP header (for example: application/xml, application/json, text/csv, etc.).

Other parameters and HTTP headers can be specified by calling a data.fao.org API. These are described in the API technical documentation.

Author: Dario Dentale