REST API with an example

What is a REST API?

A REST API (also known as RESTful API) is an application programming interface (API or web API) that conforms to the constraints of REST architectural style and allows for interaction with RESTful web services. REST stands for representational state transfer and was created by computer scientist Roy Fielding.

An API is a set of definitions and protocols for building and integrating application software. It’s sometimes referred to as a contract between an information provider and an information user—establishing the content required from the consumer (the call) and the content required by the producer (the response). For example, the API design for a weather service could specify that the user supply a zip code and that the producer reply with a 2-part answer, the first being the high temperature, and the second being the low.

In other words, if you want to interact with a computer or system to retrieve information or perform a function, an API helps you communicate what you want to that system so it can understand and fulfill the request.

You can think of an API as a mediator between the users or clients and the resources or web services they want to get. It’s also a way for an organization to share resources and information while maintaining security, control, and authentication—determining who gets access to what.

Another advantage of an API is that you don’t have to know the specifics of caching—how your resource is retrieved or where it comes from.

Restful Methods with an example

The below diagram shows mostly all the verbs (POST, GET, PUT, and DELETE)

1. POST – This would be used to create a new employee using the RESTful web service

2. GET - This would be used to get a list of all employee using the RESTful web service

3. PUT - This would be used to update all employee using the RESTful web service

4. DELETE - This would be used to delete all employee using the RESTful services

Let's take a look from a perspective of just a single record. Let's say there was an employee record with the employee number of 1.

The following actions would have their respective meanings.

1. POST – This would not be applicable since we are fetching data of employee 1 which is already created.

2. GET - This would be used to get the details of the employee with Employee no as 1 using the RESTful web service

3. PUT - This would be used to update the details of the employee with Employee no as 1 using the RESTful web service

4. DELETE - This is used to delete the details of the employee with Employee no as 1

image: guru99.com

What’s been done to improve APIs?

As APIs have developed into the now-ubiquitous web API, several efforts have been made to make their design a little easier and their implementation more useful.

A little SOAP, a lot of REST

As web APIs have spread, a protocol specification was developed to help standardize information exchange: Simple Object Access Protocol, more casually known as SOAP. APIs designed with SOAP use XML for their message format and receive requests through HTTP or SMTP. SOAP makes it easier for apps running in different environments or written in different languages to share information.

Another specification is Representational State Transfer (REST). Web APIs that adhere to the REST architectural constraints are called RESTful APIs. REST differs from SOAP in a fundamental way: SOAP is a protocol, whereas REST is an architectural style. This means that there’s no official standard for RESTful web APIs. As defined in Roy Fielding’s dissertation “Architectural Styles and the Design of Network-based Software Architectures,” APIs are RESTful as long as they comply with the 6 guiding constraints of a RESTful system:

• Client-server architecture: REST architecture is composed of clients, servers, and resources, and it handles requests through HTTP.

• Statelessness: No client content is stored on the server between requests. Information about the session state is, instead, held with the client.

• Cacheability: Caching can eliminate the need for some client-server interactions.

• Layered system: Client-server interactions can be mediated by additional layers. These layers could offer additional features like load balancing, shared caches, or security.

• Code on demand (optional): Servers can extend the functionality of a client by transferring executable code.

• Uniform interface: This constraint is core to the design of RESTful APIs and includes 4 facets:
  

  • Resource identification in requests: Resources are identified in requests and are separate from the representations returned to the client.

  • Resource manipulation through representations: Clients receive files that represent resources. These representations must have enough information to allow modification or deletion.

  • Self-descriptive messages: Each message returned to a client contains enough information to describe how the client should process the information.

  • Hypermedia as the engine of application state: After accessing a resource, the REST client should be able to discover through hyperlinks all other actions that are currently available.

These constraints may seem like a lot but they’re much simpler than a prescribed protocol. For this reason RESTful APIs are becoming more prevalent than SOAP.

In recent years, the OpenAPI specification has emerged as a common standard for defining REST APIs. OpenAPI establishes a language-agnostic way for developers to build REST API interfaces so that users can understand them with minimal guesswork.

Another API standard to emerge is GraphQL, a query language and server-side runtime that’s an alternative to REST. GraphQL prioritizes giving clients exactly the data they request and no more. As an alternative to REST, GraphQL lets developers construct requests that pull data from multiple data sources in a single API call.