Introduction to REST API

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 RecoverPoint for VMs API to retrieve a specific protected VM (the resource), the API responds with the state of that user, including name, unique ID, consistency group ID, 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 the 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

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

  1. HTTP verb - defines what kind of operation to perform
  2. Header - allows the client to pass along information about the request
  3. Path to a resource
  4. Optional message body that contains data

HTTP verbs

There are five 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
  5. PATCH - Partially modifies 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 only sends data that can be understood and processed by the client.

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

GET /api/v1/rp-cluster/1e986bd0663f945

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.
401 UNAUTHORIZED Invalid authentication details are provided.
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.
405 METHOD NOT ALLOWED The HTTP method being requested is not allowed for the authenticated user.
409 CONFLICT Indicates that the request could not be processed because of a conflict in the request.
410 GONE The resource of this end point is no longer available.
415 UNSUPPORTED MEDIA TYPE Incorrect content type was provided as part of the request.
422 UNPROCESSABLE ENTITY Used for validation errors.
429 TOO MANY REQUESTS Request is rejected due to server load.
500 INTERNAL SERVER ERROR The generic answer for an unexpected failure if no more specific information is available.

Example of request and response

This example calls the RecoverPoint for VMs rp-clusters API. If you want to view all vRPA clusters, the request would look like this:

GET https://{plugin-server}/api/v1/rp-clusters Accept: application/json

A possible response header would look like this example:

``

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

Followed by the rp-clusters list in JSON format:

Body:

{
  "address": "10.0.0.1",
  "connectionStatus": "OK",
  "id": "1e986bd0663f945",
  "isRegistered": true,
  "name": "Venice",
  "rpSystemId": "9129107775554947261",
  "version": "5.3(m.404)"
}