Developing with Restful API

Discovery and access

​

Introduction

REST (REpresentational State Transfer) is an architectural style for the implementation of resource sharing systems. According to its creator, REST is the original and proper architectural style of the World Wide Web. The World Wide Web is currently used as a general purpose infrastructure to deliver services according to different architectural styles, however, over recent years, there was a great interest in providing services fully compliant with the REST architectural style. Therefore, many Web systems provide access to their functionalities through so-called RESTful APIs. Although the concept of APIs does not make sense from a rigorous REST point of view, the term RESTful API is now improperly used to refer a way to interact with a software system through request and response messages to resources identified by an URI. In RESTful APIs, message content is usually structured in JSON or XML format.

The ENERGIC OD VH follows this trend providing a simple way to interact with the hub by exchanging JSON objects with resources identified by URIs.

Conforming to the REST architectural style, the VH RESTful API gives direct access to resources supporting the Create-Retrieve-Update-Delete (CRUD) pattern. The main resources exposed by the VH RESTful API are:

 

• Sources: the list of data sources connected to the VH instance

• Datasets: the list of datasets accessible through the VH instance

• Dataset: the single dataset

 

According to REST constraints, each resource is identified by a URI. In the VH RESTful API, the resource URI includes a VH base endpoint and a mnemonic path conventionally defined:

 

• Sources                              <VH_base>/sources

• Datasets                           <VH_base>/datasets

• Dataset                              <VH_base>/datasets/{id}

 

Where {id} should be replaced with the specific dataset ID.

​

The base endpoint for the pan-European Virtual Hub is:

​

http://vh-eu.energic-od.eu/gi-cat/services/api-rest

​

Each resource supports on or more CRUD actions implemented as HTTP requests. For example, to retrieve the list of sources, the user must send a HTTP GET request to <VH_endpoint>/sources:

 

                       GET <VH_base>/sources

 

The user then receives back a JSON object including information on the data sources connected to the VH:

 

{

  "resultSet": {

    "size": 7,

    "start": 1,

    "pageSize": 7,

    "pageCount": 1,

    "pageIndex": 1

  },

  "reports": [

    {

      "id": "GBIF",

      "type": "composed",

      "title": "GBIF",

      "harvested": false

    },

    {

      "id": "WEBSRVENCAT",

      "type": "composed",

      "title": "Webservice Energy Catalog",

      "harvested": true

    },

    {

(…continue…)

 

The figure below shows a subset of the ENERGIC OD resource model, with direct interaction with resources made possible through REST interfaces implemented using HTTP verbs.

​

​

​

​

​

​

​

​

​

 

​

​

​

​

​

​

​

​

​

​

​

​

​

 

A subset of the VH resource model and related REST interface implemented in HTTP

​

The full RESTful API documentation available online provides a detailed description of the exposed resources, their URIs, supported actions and message format, including examples and live demos.

 

RESTful API documentation

The full documentation of the VH RESTful API is available at http://vh-eu.energic-od.eu/gi-cat/api-rest-docs

​

​