What is a REST API?

A REST API (also called RESTful API) is a web interface which is built according to the specifications of the REST standard. REST APIs are used by web services and other systems to make selected resources (data) available to tother systems. These resources can then be specifically addressed, retrieved or changed using a REST client.

Due to its simplicity and flexibility, the REST API is one of the most popular web interfaces and widely used in various areas. Whether online services such as PayPal and LinkedIn, industrial software applications or even household appliances – REST APIs are often the first choice when systems need to communicate with each other in an uncomplicated way.

A REST API specifies how REST clients can interact with a web service or another system that implements the API. One example is the online weather service OpenWeatherMap. Through its REST API, the service receives requests with location parameters and returns the corresponding weather data. How exactly the service works in the background remains hidden from the requesting client.

How does a REST API work?

A REST API facilitates the exchange or modification of data between different systems, using the well-known HTTP protocol. By making use of the HTTP methods GET, POST, PUT and DELETE, data can not only be retrieved via a REST API, but also modified or deleted (if the REST API allows this).

In this section, we explain the basic functionality of a REST API using the weather service OpenWeatherMap as an example.

Structure of a REST API

Every REST API has a URL (also known as a host name or host URL) that can be used to address it.

Example: https://api.openweathermap.org/data/2.5/

The REST API itself is made up of various resources. These represent information that is stored on a server and can be addressed via an endpoint or the corresponding URI (Uniform Resource Identifier).

For example, to address the „weather“ endpoint and the underlying resource of the OpenWeatherMap REST API, the following URL is required:

https://api.openweathermap.org/data/2.5/weather

In addition, a REST API usually comes with a documentation that provides information about the available endpoints as well as possible parameters and data formats (see below).

Communicating with a REST API

In practice, communication with a REST API is done via the HTTP protocol.

Various HTTP methods (commands) can be used. These specify how the addressed resource should be interacted with. A GET request requests information from a REST API, while POST and PUT requests can be used to create new resources or change existing resources. The DELETE command deletes a specific resource.

POST, PUT and DELETE requests can for example be used to publish, modify or delete blog posts on a website.

Many web services such as OpenWeatherMap only provide information and can be addressed via GET requests. However, many devices such as the Cubis® II laboratory balance can also be addressed via REST and can even be operated externally in this way.

Example for a GET request:

In response to a valid GET request, the REST API returns a representation of the requested resource (data). This representation can be transmitted in various data formats, with HTML, JSON and XML being used most frequently.

Additional parameters are used to tell the endpoint which components of the resource are to be delivered. For example, the „weather“ endpoint of the OpenWeatherMap API can be addressed with the parameters „id“ and „appid“. The „id“ parameter is a city code, while a verification code (API key) must be transmitted via the „appid“ parameter.

Such a GET request could look like this:

GET https://api.openweathermap.org/data/2.5/weather?id= 2839763&appid=123456789abcdefghij

If the API key is correct, current weather data is returned in JSON format.

Advantages of a REST API

REST APIs are regarded as flexible and secure interfaces for communication between different systems. The standardized structure and the use of established Internet technology result in low barriers to entry.

The most important advantages of a REST API include the following:

Simple integration: REST APIs are structured according to the same pattern, use the HTTP protocol and are relatively easy to use. This enables flexible integration into a wide range of platforms, services and systems, regardless of the operating systems and programming languages used.

Scalability: REST is characterized by the principle of statelessness, i.e. a single request contains all the information required to process this request. There is no intermediate storage by the server and data is provided independently of the requesting clients. This means that requests can be distributed across several servers (load balancing) and the REST API can be easily expanded to include new servers at any time.

Security: In practice, REST makes use of the security mechanisms of HTTPS communication. In addition to HTTPS encryption, authentication methods such as OAuth or OpenID can be used. It is also possible to filter requests through firewalls.

REST API examples

Due to the widespread use of REST, there are numerous examples of REST APIs. Below we have listed a few of them:

• OpenWeatherMap: For the examples in this article, we referred to the REST API of the weather service OpenWeatherMap. You can find out how the retrieval of current weather data works in detail in our step-by-step guide: Query weather data from OpenWeather with REST.
• Microsoft Teams: Messages and links can be sent in Microsoft Teams via a REST API. Detailed instructions can be found here: Connect Microsoft Teams via REST Plug-in.
• PayPal: Using the PayPal REST APIs, operators of online stores or similar services can communicate with the PayPal servers and integrate the payment service into their website.
• ThingWorx: ThingWorx is an IoT platform that can be used to centrally visualize and manage Internet-enabled devices, sensors and machines. In our step-by-step guide to the REST connection of the ThingWorx platform, we show how data can be read from the device profiles or written to the device profiles via a REST API.
• Zebra label printer: In addition to many web services, industrial and household devices also make use of REST APIs in a variety of ways. The REST API of a Zebra label printer, for example, can be used to transmit print jobs to the device. Further information can be found here.
• Cubis® II laboratory balance: The Cubis® II by Sartorius also implements a REST API., enabling not only the retrieval of measured values, but also external control of the balance.

In our article Industrial Use of REST APIs – Five Practical Examples, we go into more detail about various use cases of REST APIs in the industry.