REST API

A RESTful (Representational State Transfer) web service is a web service that is designed with an architecture specially for distributed systems. All RESTful web services on a server together are called REST API (Application Programming Interface).

REST APIs are often associated with the HTTP protocol but are neither a standard nor a protocol. So, there are – per definition - different protocols that can be used to communicate with REST APIs, HTTP is only the most common one.

A REST API has to follow six different architectural definitions that are mentioned in the specification:

• Client-Server model: Data and user interface have to be divided by definition.
• Statelessness: Client and server have to communicate stateless. Every client request must deliver all the information that the server needs to process the request.
• Caching: Information can be classified as cacheable or not-cacheable. A client can cache server responses for future requests, but this information might be outdated.
• Consistent interface: REST interfaces must be usable from different endpoints in the same way, due to their consistent interface.
• Layered systems: A REST API has to be a multilayered, hierarchical built system.
• Code-On-Demand (optional): The functions of clients have to be extendable with reloadable and executable program parts.

How to request resources from a REST API

As mentioned before, HTTP(S) is just one of the possibilities to implement a REST API but is the only one that has importance for this documentation. The following section will contain a short description how to request resources from a REST API that is implemented with HTTP(S).

A resource on a HTTPS REST API is identified with its URL. There are two different possibilities how a URL can be offered by a webservice. On the one hand, a URL can only consist of path parameters and on the other hand it could contain query parameters. The following example will explain the difference between these two possibilities.

A URL is built with three parts:

1. Domain name
2. Path parameters
3. Query parameters

When the weather for the city Verl should be requested from a fictional Beckhoff weather service, the URL without query parameters could look like:

https://www.beckhoff-weather.com/forecast/city/verl

With the usage of query parameters, the URL could look like:

https://www.beckhoff-weather.com/forecast?city=verl

The first part https://www.beckhoff-weather.com is the domain name of the webserver, which is translated to an IP address with the help of a DNS-Server. The path parameters /forecast/city/verl specify on which resource of the server the request should be processed. Another possibility is to use a query parameter like forecast?city=verl to request a specific resource on a path.