Web API¶

Introduction

The infrastructure offers a rich API that allows you to perform various support operations in the development and integration of your Domain within proprietary applications or in a third party system. In this chapter we explain what an API is, what are the reference standards followed, how authentication takes place and, in the last paragraph, how to test the API directly from the dedicated reference site.

Definition

A REST API (also known as RESTful API) is an application programming interface (API) that conforms to the constraints of REST architecture. REST stands for representational state transfer.

An API is a set of definitions and protocols for building and integrating an application software. It is sometimes referred to as a contract between an information provider and an information user - establishing the content required from the consumer (the call) and the content required by the producer (the response).

Every HTTP API invocation is composed of a request (sent by the client) and a response (sent back by the server).

To read more about REST API, refer to https://it.wikipedia.org/wiki/Representational_State_Transfer.

The anatomy of a request

It is important to know that a request is made up of four things:

1. Endpoint

2. Methods

3. Headers

4. Data (or body)

Endpoint

The root-endpoint (or base address) is the starting point of the API you’re requesting from. The root-endpoint of API is https://uniqloud.asem.it. The path determines the resource you’re requesting for. Every API has its own path. For example, the path to retrieve the devices list is /api/devices while the path to retrieve users list is /api/users.

Method

The method is used to represent the action take on the resource.

To read more about HTTP verbs, refer to https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html.

Headers

Headers are used to provide information to both the client and server. It can be used for many purposes, such as authentication and providing information about the body content.

HTTP Headers are property-value pairs that are separated by a colon. The example below shows a header that tells the server to expect JSON content.

Content-Type: application/json

Data

The data (sometimes called “body” or “message”) contains information you want to be sent to the server. This option is only used with POST, PUT, PATCH or DELETE requests.

The GET method is used in combination with the query string parameters (specified at the end of the path with a property-value pair, preceded by a question mark).

The response

Once the server receives the request from a client, it sends a response back to it.

The response consists of:

1. HTTP status code

2. Body

HTTP status codes are standardized as following:

• 200+ means the request has succeeded.

• 300+ means the request is redirected to another URL

• 400+ means an error that originates from the client has occurred

• 500+ means an error originating from the server

The body is optional and contains the response of the server.

To read more about HTTP Status codes, refer to https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html.

Authentication

To provide secure access, almost every REST API must have some sort of authentication. One of the most common headers is called Authorization.

Authentication vs Authorization

The distinction between authentication and authorization is important in understanding how RESTful APIs works and why connection attempts are either accepted or denied:

• Authentication is the verification of the credentials of the connection attempt. This process consists of sending credentials from the client to the server either in plaintext or encrypted form by using an authentication protocol.

• Authorization is the verification that the connection attempt is allowed. Authorization occurs after successful authentication.

In other words: Authentication is stating that you are who are you are, and Authorization is asking if you have access to a certain resource.

To access to APIs that require authentication you have first to invoke the authentication API in order to obtain the Bearer Token in response.

With that token you could invoke the others API specifying the token in the HTTP Header:

'Authorization': 'Bearer <token>'

To read more about JWT, refer to https://tools.ietf.org/html/rfc7519.

OData v4

To deal with Domain resources (Folders, Devices, Users, Groups and so on), the APIs are exposed using OData v4 protocol. OData (Open Data Protocol) is an ISO/IEC approved, OASIS standard that defines a set of best practices for building and consuming RESTful APIs.

We admit the following clauses: $select, $expand, $filter, $top, $orderby, $count.

To read more about OData v4: https://www.odata.org/documentation/.

API Reference

At the following URL: https://uniqloud.asem.it/api/ we provide the API documentation, compliant with OpenAPI 3.0.1 standard.

It’s accessible by Swagger UI tool, where you can find some example of request parameters, body etc… and you can try out each API by yourself.

The APIs that requires the Authentication are marked with a lock on the right; if you click on the lock you can enter the JWT bearer token to provide the right authentication to the API. You could also enter the JWT Bearer Token if you click on the Authorize button in the upper right part of the page, then all the API requests that require authentication will use that token.

To obtain a valid authentication token you first have to invoke the Authenticate API providing your credentials and you will be required to have a valid UBIQUITY X Connectivity services license.

In each API definition you can find a Try it out button to test the API. When you press it, you can easily change the request body example with your own values, then press the Execute button to send the request to the server.

To read more about OpenAPI and Swagger, refer to https://swagger.io/specification/.