Web API
Web API is an interface that facilitates communication between software applications. It allows you to develop and integrate your domain into proprietary applications or third-party systems. RESTful API invocations consist of a request sent by the client and a response returned by the server.
Client Request
A RESTful API request includes three main components:
- HTTP action: It defines the action to be performed on the URL endpoint resource.
HTTP action GET
Read
POST
Create
PUT
Update/Replace
PATCH
Partial update/Modify
DELETE
Delete
- URL endpoint: It consists of an URL link representing the resources that you want to access, such us text, images, documents or data. The root-endpoint (or base address) is the API starting point from which you are sending your request, whereas the path determines the resource that you request. Every API has its own path (for example, the path to retrieve a devices list is: /api/devices, while the path to retrieve a user's list is: /api/users). The API root-endpoint is https://uniqloud.asem.it
- Body message: It includes properties and values to create or update a given resource. A body message might include headers. Headers are property-value pairs that are separated by a colon and used for entering information about the body content. The following example shows a header informing the server to expect JSON content:
Content-Type: application/json
Server response
Once the server has received an http request from a client, it sends a response that consists of two parts:
- The HTTP status code:
- 200: The request has succeeded.
- 300: The request is redirected to another URL.
- 400: An error that originates from the client has occurred.
- 500: An error originating from the server has occurred.
- The body: The response body is optionally provided and its message may vary depending on the server response.
Authentication and Authorization
Connection attempts might be accepted or denied, depending on whether authentication or authorization fail or are successful.
- Authentication is a process used to verify the access credentials during the connection attempt. Credentials are sent from the client to the server either in plaintext or encrypted form through an authentication protocol.
- Authorization is a process used to confirm that the connection attempt that you are trying to establish is allowed. An authorization may occur only after a successful authentication.
Before accessing APIs that require authentication, invoke the authentication API in order to obtain the Bearer token in response. The 'Authorization': 'Bearer <token>' allows you to invoke other APIs to specify the token in the http header.
OData v4 protocol
OData (Open Data Protocol) is an open protocol that allows the creation and consumption of RESTful APIs, as they deal with domain resources (devices, users, groups, and so on). OData is compliant with OASIS standards that define a set of practices for building and consuming RESTful APIs.
The following clauses are accepted: $select, $expand, $filter, $top, $orderby, $count.