What is a REST API?

TransIP provides the option to manage domain and VPS services through a REST API. In this article we explain the basics of what makes an API RESTful. More general information on API's can be found here.

In addition, we provide an overview of the type of requests that can be used with the TransIP REST API and which responses can follow.

REST API

REST (Representational State Transfer) is a style of software architecture for the design of network applications. The  fundamentel concept of a RESTful API is the 'resource'. All information which can be defined is a resource: a document, image, collection of resources, non virtual object (e.g. a persoon) etc. REST uses a resource identifier to identify a resource.

The status of a resource at any given moment is called a 'resource representation' and contains data, metadata which describes the data and hypermedia links which helps clients to change its state.

The data format of a  'resource representation' is known as a 'media type' and determines how the resource representation should be processed. RESTful API's therefore look like hypertext: Every addressable unit of information carries an address, either explicitly (e.g., link and id attributes) or implicitly (e.g., derived from the media type definition and representation structure).

Another important thing associated with REST is resource methods to be used to perform the desired transition. Ideally, everything that is needed to change the resource state shall be part of API response for that resource – including methods and in what state they will leave the representation.

Guiding Principles of REST

REST knows six guiding principles to which an API must adhere in order to be called 'RESTful':

1. Client server: By separating the user interface concerns from the data storage concerns, we improve the portability of the user interface across multiple platforms and improve scalability by simplifying the server components.
    
2. Stateless: Each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server. Session state is therefore kept entirely on the client. Informatie about the API user is not stored on the server.
    
3. Cacheable: Cache constraints require that the data within a response to a request be implicitly or explicitly labeled as cacheable or non-cacheable. If a response is cacheable, then a client cache is given the right to reuse that response data for later, equivalent requests. The response will therefore contain a sort of version number, so that the client knows which version of the data it already has. This also applies for example to the array which is returned when you request the specifications fo a VPS with our REST API.
    
4. Uniform interface: By applying the software engineering principle of generality to the component interface, the overall system architecture is simplified and the visibility of interactions is improved. In order to obtain a uniform interface, four architectural constraints are needed to guide the behavior of components:
   • Identification of resources
   • Manipulation of resources through representations (see resource representations above)
   • Self-descriptive messages
   • Hypermedia as the engine of application state. The application in the context of a website is the web server which you're running and hypermedia the hyperlinks/links which the server sends in reply to requests.
      
5. Layered system: The layered system style allows an architecture to be composed of hierarchical layers by constraining component behavior such that each component cannot see beyond the immediate layer with which they are interacting. In the context of TransIP's services the layered system usually refers to a layer of servers.
    
6. Code on demand (optional): REST allows client functionality to be extended by downloading and executing code in the form of applets or scripts. This simplifies clients by reducing the number of features required to be pre-implemented.

API requests and responses

An API communicates using requests and responses. In the API restaurant example your order is a request, and the provided meal is a response. There are various types of requests which can be used, depending on the implementation of the specific API. In the TransIP REST-API the following requests are used:

• GET : Requests a 'resource' from a server, where a resource is a special variable (the resource representation) which contains a reference to an external resource. The data can then be modified and sent back to the server usign a een PUT request. Retrieving a list of available products would be an example of a GET-request.
• POST : A client adds a new resource, for example when you order a product using an API or add a new DNS record to a domain
• PUT : Updates a resource with new data, existing data is removed. This is used for example if you update the description of a VPS or modify a DNS record for a domain.
• PATCH : While not always used in API's, PATCH is present in our REST API. PATCH is used for a partial update of a resource, for example to stop or start a VPS.
• DELETE : Is used for the deletion of resources.

The API uses JSON objects and arrays for all requests and responses which can be performed by the API.

Responses

For the responses an HTTP status code is used. At a succesful request a 2xx HTTP status code will be returned:

In case of an error one of the following status codes will be returned:

This concludes our article on REST API's. Should you have any questions left regarding this tutorial, do not hesitate to contact our support department. You can reach them via the ‘Contact Us’ button at the bottom of this page.