What is REST API?

What is REST API?

What is REST API?

Hello Everyone

Welcome to CloudAffaire and this is Debjeet.

REpresentational State Transfer (REST) Application Programming Interface (API) is a set of rules for communication between devices and applications and is the backbone of any modern web application. REST was first defined by a computer scientist named Roy Fielding in his PhD thesis in the year 2000 and since then it has become the standard for inter communication between webservices and applications.

Now a days most of the applications exposes REST API endpoints to interact with it programmatically and its an essential skill required in the field of Cloud & DevOps. REST is based on six design principles that the API must adhere to in its design and architecture.

REST API design principals:

The REST architectural style defines six guiding constraints. When these constraints are applied to the system architecture, it gains desirable non-functional properties, such as performance, scalability, simplicity, modifiability, visibility, portability, and reliability. A system that complies with some or all of these constraints is loosely referred to as RESTful.

Uniform interface:

All API requests for the same resource should look the same, no matter where the request comes from. The REST API should ensure that the same piece of data, such as the name or email address of a user, belongs to only one uniform resource identifier (URI). Resources shouldn’t be too large but should contain every piece of information that the client might need.

Client-server decoupling:

In REST API design, client and server applications must be completely independent of each other. The only information the client application should know is the URI of the requested resource; it can’t interact with the server application in any other ways. Similarly, a server application shouldn’t modify the client application other than passing it to the requested data via HTTP.

Statelessness:

REST APIs are stateless, meaning that each request needs to include all the information necessary for processing it. In other words, REST APIs do not require any server-side sessions. Server applications aren’t allowed to store any data related to a client request.

Cacheability:

When possible, resources should be cacheable on the client or server side. Server responses also need to contain information about whether caching is allowed for the delivered resource. The goal is to improve performance on the client side, while increasing scalability on the server side.

Layered system architecture:

In REST APIs, the calls and responses go through different layers. As a rule of thumb, don’t assume that the client and server applications connect directly to each other. There may be a number of different intermediaries in the communication loop. REST APIs need to be designed so that neither the client nor the server can tell whether it communicates with the end application or an intermediary.

Code on demand (optional):

REST APIs usually send static resources, but in certain cases, responses can also contain executable code (such as Java applets). In these cases, the code should only run on-demand.

How REST API work?

REST APIs communicate via HTTP requests to perform standard database functions like creating, reading, updating, and deleting records (also known as CRUD) within a resource. For example, a REST API would use a GET request to retrieve a record, a POST request to create one, a PUT request to update a record, and a DELETE request to delete one. All HTTP methods can be used in API calls. A well-designed REST API is similar to a website running in a web browser with built-in HTTP functionality.

The state of a resource at any particular instant, or timestamp, is known as the resource representation. This information can be delivered to a client in virtually any format including JavaScript Object Notation (JSON), HTML, XLT, Python, PHP, or plain text. JSON is popular because it’s readable by both humans and machines—and it is programming language-agnostic.

Request headers and parameters are also important in REST API calls because they include important identifier information such as metadata, authorizations, uniform resource identifiers (URIs), caching, cookies and more. Request headers and response headers, along with conventional HTTP status codes, are used within well-designed REST APIs.

What is REST API?

REST API HTTP methods:

REST has different HTTP methods that allows an application or client to perform CRUD operation with the REST API endpoints.

GET:

GET method is used to retrieve resource information or to get information from a REST API endpoint. If the request is success, the endpoint response with a status code of 200 along with the requested data and if failed, response will contain the respective status codes like 404 or 400 etc.

POST:

POST method is used to create a new resource. If the resource is created successfully the response will contain status code 201 and if failed, response will contain the respective status codes like 404 or 409 etc.

PUT:

PUT method is used to update or replace an existing resource. If the resource is updated successfully the response will contains status code 200 and if failed, response will contain the respective status codes like 404 or 204 etc.

PATCH:

PATCH is similar to PUT request but can update a subset of the resource without replacing the entire content. For example, if you want to update a specific field in your data then use PATCH request and if you want to update the entire content then use PUT request. If the resource is updated successfully the response will contains status code 200 and if failed, response will contain the respective status codes like 404 or 204 etc.

DELETE:

DELETE method is used to delete an existing resource. If the resource is deleted successfully the response will contains status code 200 and if failed, response will contain the respective status codes like 404 etc.

Note: These are the most common HTTPS method used in REST but there are other HTTP methods like HEAD, CONNECT, TRACE that are also supported by REST. Get details on all HTTPS methods using this link.

REST API HTTP Status Code:

When you perform some request using the above HTTP methods to an REST API endpoint, the endpoint will return a response to your request with a status code which depicts the status of your request (weather it succeed or failed).

200 OK:

Request accepted; response contains result. This is a general-purpose response code that can be returned from any request. For GET requests, the requested resource or data is in the response body. For PUT or DELETE requests, the request was successful and information about the result (such as new resource identifiers, or changes in resource status) can be found in the response body.

201 CREATED:

This response code is returned from PUT or POST, and indicates that a new resource was created successfully. The response body might for example contain information about a new resource, or validation information (for example, when an asset is updated).

204 NO CONTENT:

Indicates that the request was accepted but that there was nothing to return. This is returned when the request was processed, but no additional information about the result has been returned.

400 BAD REQUEST:

The request was not valid. This code is returned when the server has attempted to process the request, but some aspect of the request is not valid, for example an incorrectly formatted resource or an attempt to deploy an invalid event project to the event runtime. Information about the request is provided in the response body, and includes an error code and error message.

401 UNAUTHORIZED:

Is returned from the application server when application security is enabled, and authorization information was missing from the request.

403 FORBIDDEN:

Indicates that the client attempted to access a resource which they do not have access to. This might be encountered if the user accessing the remote resource does not have sufficient privileges; for example, by having the WBERestApiUsers or WBERestApiPrivilegedUsers role. Users who attempt to access private event projects owned by other users might also see this error, but only if they have the WBERestApiUsers role rather than the WBERestApiPrivilegedUsers role.

404 NOT FOUND:

Indicates that the targeted resource does not exist. This might be because the URI is malformed, or the resource has been deleted.

405 METHOD NOT ALLOWED:

Returned when the targeted resource does not support the requested HTTP method; for example, the functions resource only allows GET operations.

406 NOT ACCEPTABLE:

The data format requested in the Accept header or accept parameter is not supported by the targeted resource. That is, the client has requested that data is returned in a particular format, but the server is unable to return data in that format.

409 CONFLICT:

Indicates that a conflicting change has been detected during an attempt to modify a resource. The response body provides further information.

415 UNSUPPORTED MEDIA TYPE:

The data format of the request body, specified in the Content-Type header, is unsupported by the targeted resource.

500 INTERNAL SERVER ERROR:

An internal error occurred in the server. This might indicate a problem with the request, or might indicate a problem in the server-side code. Error information can be found in the response body.

Note: These are the most common HTTP status code used in REST but your response to a request may contain some other status code. Please get details on all the available HTTP status codes using this link.

REST API HTTP request and response format and components:

REST API HTTP Request Format:

REST API HTTP Request Components:

A request message from a client to a server includes, within the first line of that message, the method to be applied to the resource, the identifier of the resource, and the protocol version in use and optionally multiple header fields (general header, request header, entity header) and message body.

HTTP Method:

The Method token indicates the method to be performed on the resource identified by the Request-URI. The method is case-sensitive.

Request URI:

The Request-URI is a Uniform Resource Identifier (section 3.2) and identifies the resource upon which to apply the request.

Note: The four options for Request-URI are dependent on the nature of the request. The asterisk “*” means that the request does not apply to a particular resource, but to the server itself, and is only allowed when the method used does not necessarily apply to a resource.

HTTP Version:

HTTP (HyperText Transfer Protocol) is the underlying protocol of the World Wide Web. Developed by Tim Berners-Lee and his team between 1989-1991, HTTP has gone through many changes that have helped maintain its simplicity while shaping its flexibility. This changes are combined into major release for HTTP version as follows

Note: HTTP/1.0 or HTTP/2.0 are currently used in most of the REST API endpoints.

CRLF:

CRLF refers to the special character elements “Carriage Return” and “Line Feed.” These elements are embedded in HTTP headers and other software code to signify an End of Line (EOL) marker.

General Header:

There are a few header fields which have general applicability for both request and response messages, but which do not apply to the entity being transferred. These header fields apply only to the message being transmitted.

Request Header:

The request-header fields allow the client to pass additional information about the request, and about the client itself, to the server. These fields act as request modifiers, with semantics equivalent to the parameters on a programming language method invocation.

Entity Header:

Entity-header fields define metainformation about the entity-body or, if no body is present, about the resource identified by the request. Some of this metainformation is OPTIONAL; some might be REQUIRED by portions of this specification.

Example Request:

REST API HTTP Response Format:

REST API HTTP Response Components:

After receiving and interpreting a request message, a server/application responds with an HTTP response message.

Status Code:

The Status-Code element is a 3-digit integer result code of the attempt to understand and satisfy the request. The first digit of the Status-Code defines the class of response. The

last two digits do not have any categorization role. There are 5 values for the first digit:

  • 1xx: Informational – Request received, continuing process
  • 2xx: Success – The action was successfully received, understood, and accepted
  • 3xx: Redirection – Further action must be taken in order to complete the request
  • 4xx: Client Error – The request contains bad syntax or cannot be fulfilled
  • 5xx: Server Error – The server failed to fulfil an apparently valid request

Response Header:

The response-header fields allow the server to pass additional information about the response which cannot be placed in the Status-Line. These header fields give information about the server and about further access to the resource identified by the Request-URI.

Example Response:

Hope you have enjoyed this first article in REST API. In the next blog post, we will explore how to interact with REST API endpoints from command line using curl. To get more details on REST API, please refer below documents

https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

https://datatracker.ietf.org/doc/html/rfc2616

Leave a Reply

Close Menu