What is REST?

REST stands for REpresentational State Transfer. It is an architecture for designing loosely coupled applications over HTTP. REST is often used in the development of web services.

A REST API is an application program interface (API) that uses HTTP requests to GET, PUT, POST, and DELETE resources. When a RESTful API is called, the server transfers to the client a representation of the state of the requested resource.

For example, when a developer calls the PowerProtect Data Manager API to retrieve a specific user (the resource), the API responds with the state of that user, including name, unique ID, role of the user, and more.

The representation of the state can be in JSON format.

Architecture constraints

RESTful APIs adhere to these architectural constraints:

1. Client–server – Separating user interface from the data storage improves the portability of the user interface across multiple platforms and improves scalability by simplifying the server components.
2. Stateless – Each request from client to server must contain the necessary information to understand the request and cannot use any stored context on the server. Session state is kept on the client.
3. Cacheable – Cache constraints require that the data in a response to a request is labeled as cacheable or non-cacheable. If a response is cacheable, a client cache is granted the right to reuse that response data for subsequent requests.
4. Uniform interface – To obtain a uniform interface, multiple constraints are needed to guide the behavior of components. REST is defined by four interface constraints: identification of resources, manipulation of resources through representations, self-descriptive messages, and hypermedia as the engine of application state.
5. Layered system – The layered system style enables an architecture to have layers of hierarchy. It constrains each component within its own layer.
6. Code on demand (optional) – REST allows client functions to be extended by downloading and running code in the form of applets or scripts. This simplication reduces the number of features that must be implemented ahead of time.

Resource

The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, temporary service, collection of other resources, nonvirtual object, and so on. REST uses a resource identifier to identify the resource involved in an interaction between components.

The state of a resource at any given timestamp is known as resource representation. A representation consists of data, including metadata that describes the data and hypermedia links that can assist the clients in transition to the next desired state.

The data format of a representation is known as a media type. The media type identifies a specification that defines how a representation is processed. A RESTful API looks like hypertext. Every addressable unit of information includes an address.

Resource methods

Another important aspect of REST are the resource methods to perform the desired transition. The common methods are HTTP methods, or verbs: GET, POST, PUT, and DELETE.

Making requests

REST requires that a client make a request to the server to retrieve or modify data on the server. A request generally consists of:

1. An HTTP verb, which defines what kind of operation to perform
2. A header, which allows the client to pass along information about the request
3. A path to a resource
4. An optional message body that contains data

HTTP verbs

There are four HTTP verbs that are used in requests to interact with resources:

1. GET — Retrieves a specific resource (by ID) or a collection of resources
2. POST — Creates a new resource
3. PUT — Updates a specific resource (by ID)
4. DELETE — Removes a specific resource by ID

Headers and accept parameters

In the header of the request, the client sends the type of content that it is able to receive from the server. This information is called the Accept field. It ensures that the server does not send data that cannot be understood or processed by the client.

For example, a client accessing a resource with ID 13 in a user resource might send a GET request like this one:

GET /api/v2/users/13
Accept: application/json

Response codes

Responses from the server contain status codes to alert the client about the success of the operation. As a developer, you do not need to know every status code (there are many of them), but you should know the most common ones and how they are used:

Status Code	Name	Meaning
200	OK	The standard response for successful HTTP requests. Usually returned by a GET or PUT method.
201	CREATED	The standard response for an HTTP request that results in a resource being successfully created. Usually returned by a POST method.
204	NO CONTENT	The standard response for successful HTTP requests where nothing is being returned in the response body. Usually returned by a DELETE method.
400	BAD REQUEST	The request cannot be processed because of bad request syntax, excessive size, or another client error.
403	FORBIDDEN	The client does not have permission to access this resource.
404	NOT FOUND	The resource could not be found at this time. It is possible it was deleted or does not exist yet.
500	INTERNAL SERVER ERROR	The generic answer for an unexpected failure if no more specific information is available.
503	SERVICE UNAVAILABLE	The service is currently unable to handle the request because of a temporary overload or scheduled maintenance.

Example of request and response

This example calls the PowerProtect Data Manager users API. If you want to view all users, the request would look like this:

GET https://<your-ppdm-server>:8443/api/v2/users
Accept: application/json

A possible response header would look like this example:

Status Code: 200 (OK)
Content-type: application/json

Followed by the users list in JSON format:

Body:
"users" : [ {
      "id" : "00000000-0000-4000-a000-000000000000",
      "roleId" : "2bc90020-7675-0136-29e9-5bbd3ce729b0",
      "firstName" : "adminFirst",
      "lastName" : "adminLast",
      "username" : "admin",
      "password" : "**********",
      "emailAddress" : "admin@address.com",
      "forcePasswordChange" : false,
      "createdDate" : "2019-07-31T22:38:30.807+0000"
    }]