The idea of “Representational State Transfer” (REST) consists of a software architecture for data exchange between software systems (client-server). The special feature compared to other architectures is the very simple implementation, the concentration on resources and the statelessness.
All communication via REST focuses on the resource and not the action. A resource is always uniquely addressed and then the basic actions of creating, reading, changing or deleting can be carried out. In this context, stateless means that all descriptive parameters are exchanged between client and server. The advantage here is that there are no sessions. Without sessions, client and server systems can be scaled freely because each REST call is completed and understandable on its own, without the preceding or following ones.
The API (Application Programming Interface) is the respective implementation of the REST architecture of a concrete system. It is then referred to as a RESTful API. The resources that can be addressed via REST are defined in the interface.
For the respective resources, there are associated parameters that describe the resource and that are modified via REST.
For the RESTful API of a system, the provider usually provides API documentation in which all resources and their parameters can be viewed.
An example of good API documentation is the REST interface of our ticket system Target Process, which can be viewed here: Target Process REST API.
In a production environment, a REST-enabled system might provide the following resources, for example:
- /production/production order
- Parameters: ID, order number, quantity, product, deadline, …
- Parameters: ID, material number, quantity, batch, …
- Parameter: ID, status, current order, next maintenance, operating hours, …
The architectural idea of Representational State Transfer does not prescribe a technology for implementation. In practice, however, REST is always implemented with the HTTP protocol. The resources are addressed with a unique URI (Uniform Resource Identifier), as known from the web browser. The parameters of the resource are appended as a query (also known as URL parameters).
The actions on the resources are implemented in HTTP with the standard actions GET, POST, PUT and DELETE. The following standard applies:
- GET retrieves one or more resources
- POST creates a new instance of a resource
- PUT writes data to a resource and thus changes it
- DELETE deletes an instance of a resource
A REST call to retrieve a specific production order from a REST-enabled ERP system could then look like this via an existing http connection:
The second line specifies to the ERP system the format in which the response is to be made.
A possible response in JSON format would be:
„Artikel“: “Produkt A”,
A real example of a REST call can be tried out, for example, on the page of the weather forecast service OpenWeatherMap.
If the link is called with the web browser (per click), a GET request is sent to the service. As a result, the service responds with the weather forecast for the location London.
The endpoint in this case is: api.openweathermap.org/data/2.5/forecast
The resource is the “forecast” with the associated parameters “q” for the location and “mode” for the format. A detailed example of how to call this API can be found in our instruction article for retrieving weather data from OpenWathermap with the OPC Router.
The data format of the response of a REST endpoint is not prescribed and can therefore in principle be arbitrary. In practice, the format depends on the function of the endpoint. In most cases, the data is delivered as a JSON or XML document. If a normal web page is queried via a REST call, the response is in HTML.
The structure of XML/JSON responses must be documented by the operator of the REST interface, as there is no possibility of self-description here.