What is an API?

The term API means "Application Programming Interface" and traditionally refers to an "application layer" that somehow exposes an application's business logic in a uniform way, so that it can be used by all external applications that want to interact with that application.

In the context of a web application, this translates into a layer of web services that client applications can use to obtain and/or update the application's data. These services may come with different names, shapes and formats, but nowadays it is common for them to take the shape of a REST API.

For more information on good practices and concepts, please see https://restfulapi.net/

What is a REST API?

REST stands for "Representational State Transfer" and is a design standard used to create APIs that use the HTTP protocol to communicate.

The article describing this "standard" can be found at http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm.

The HTTP protocol is an excellent platform to support an API because all modern devices with a connection to the Internet today already use it.

In essence, HTTP is a request/response system. The client (the external application) sends a request to a specific endpoint and that endpoint (the API) issues a response.

There are several aspects of the HTTP protocol that are important in the context of a Web API:

• Resources - REST uses resources with an address to define the structure of the API. These are the URLs that must be used to access the entities and operations available in the API.
• Request Verbs - describe what you want to achieve by using the resource. There are several verbs available: GET, POST, PUT, DELETE. More information: https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html.
• Request Headers - are additional instructions sent in the request. For example, authorization details or the desired response type. More information: https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.
• Request Body - the data sent in the request. For example, in a POST (to create a new record) the data is sent in the body in JSON or XML format
• Response Body - the response data returned from the server, also in JSON or XML
• Response Status Code - the response code that indicates the status of the request to the client. More information: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html.

In a REST API, resources are usually the entities provided by the application (customer, item, supplier, order, etc.).

The verb sent in the request tells the API which operation should be performed on the entity. For example, a GET indicates that you want to retrieve an entity's data. A POST means that you want to create a new entity.

It is usual to use implicit REST API conventions to facilitate their use in a uniform way for all entities.

Here are some examples of possible API addresses and requests:

PRIMAVERA Web API

The Web API for cloud products follows, therefore, the Web API REST logic and provides access to all system entities, allowing you to perform all operations on these entities (create, update, remove, view and list).

To use the Web API, the following conditions must be met:

• Requests must be made in the context of a user. Therefore, first you need to create a user account and a subscription.
• The external application needs to be registered in the system to access the security token that allows the identification of the requests made by that application
• Web API requests must be configured according to the instructions of the OAuth protocol and the authentication system.

Endpoints

The Jasmin Web API provides service endpoints in a specific route format.

Base URL:

https:///api/{account}/{subscription}/{module}/{resource}/

The route always has the same structure, with the following variable elements:

• {account}: identifies the customer account that will be used in the request
• {subscription}: identifies the customer subscription that will be used in the request. A customer can have several different subscriptions.
• {module}: identifies the module to which the resource request belongs. Resources in are categorized into modules based on their themes (sales, purchases, taxes, etc.)
• {resource}identifies the resource that will be used in the request

Example:

https:///api/9999/9999-9999/sales/invoice/

The GET, POST or DELETE operations (verbs) are available for each endpoint.

More information: What are Web API endpoints?

Examples of Endpoints

As is natural in REST Web APIs, the URL and request parameters depend on the operation to be performed. Below you can find some concrete examples for the sales order entity (resource):

• To get a list of all sales orders (with the GET verb):

  https:///api/{tenant}/{subscription}/sales/orders
  

• To retrieve a page with a list of all sales orders (with the GET verb):

  https:///api/{tenant}/{subscription}/sales/orders
  

• To create a new order (with the POST verb):

  https:///api/{tenant}/{subscription}/sales/orders
  

• To retrieve a specific order using its id (with the GET verb):

  https:///api/{tenant}/{subscription}/sales/orders/53c4ee41-bd16-41f9-a348-3b24cbb4d8c8
  

• To retrieve a specific order using its key (with the GET verb):

  https:///api/{tenant}/{subscription}/sales/orders/ECL/2017/12
  

• To cancel a specific order (with the DELETE verb):

   https:///api/{tenant}/{subscription}/sales/orders/ECL/2017/12
  

Input Parameters

As noted above, the endpoints of Web API require account identification and customer subscription for all requests.

Other parameters must be provided in order depending on the endpoint and the specific operation.

In some cases, these parameters need to be specified in the request headers (for example, authentication information). In other cases, they must be specified in the endpoint URL (such as the entity identifier to obtain it in a GET or the page number and size in entity list queries).

Finally, there are other cases, such as creating an entity, where the data must be provided in JSON format in the message body.

The Web API reference documentation specifies the exact request parameters for each case.

Results

The results returned for each request depending on the type of request and the entity concerned.

For certain requests, such as eliminating an entity, the result will only be a status code. In most cases, a status code and the response data will be returned in the message body. For example, the result of an entity query using its key will include the whole entity in JSON format.

More information: Format of requests and responses

Authentication

The Web API requires authentication for all requests. The authentication method used is the OAuth 2.0 standard.