Learn The Basics of RESTful APIs

Learn the basics of REST / RESTful APIs and RESTful web services with applications and examples

Visualization of how REST APIs work

1. What is REST?

REST is a software architectural style that defines the set of rules to be used for creating web services

REST stands for Representational State Transfer

API stands for Application Programming Interface

2. Architectural Constraints of RESTful APIs

• Uniform Interface: There should be a uniform way of interacting with the server.
• Stateless: The server doesn’t have to store anything related to the session.
• Cacheable: Every response should include whether the response is cacheable and how long it stays in the cache.
• Client-Server: REST applications should have a client-server architecture.
• Layered System: There can be many intermediate servers between the client and the end server. There should be multiple layers in the application architecture.
• Code on Demand: Optionally, servers can provide executable code to the client.

3. What Are RESTful Web Services?

Web services that follow the REST architectural style are known as RESTful web services.

RESTful systems consist of a client and a server.

4. Basics of REST APIs

Interaction between client and server is provided by HTTP.

The client requests resources from the server and the server has resources.

HTTP Methods Used for Requests

• GET: Retrieves one or more resources identified by the request URI
• POST: Creates a new resource
• PUT: Updates an existing resource
• DELETE: Deletes an existing resource

Task API Example

Authentication may be required for safety while using HTTP Methods.

HTTP Status Codes Used for Responses

• 200 ( OK ): The request has succeeded.
• 201 ( CREATED ): The request has been fulfilled and resulted in a new resource being created.
• 202 ( ACCEPTED ): The request has been accepted for processing, but the processing has not been completed.
• 400 ( BAD REQUEST ): The request could not be understood by the server due to malformed syntax.
• 401 ( UNAUTHORIZED ): The request requires user authentication.
• 403 ( FORBIDDEN ): The server understood the request, but is refusing to fulfill it.
• 404 ( NOT FOUND ): The server has not found anything matching the Request-URI.
• 500 ( INTERNAL SERVER ERROR): The server encountered an unexpected condition which prevented it from fulfilling the request.
• 502 ( BAD GATEWAY ): The server, while acting as a gateway or proxy, received an invalid response from the upstream server it accessed in attempting to fulfill the request.

REST Response Formats

• JSON
• XML
• HTML
• TEXT

5. A Basic Example to REST APIs

In this example, we will use Swagger Inspector to send requests to an example Pet Store API’s Server.

We also installed the Swagger Inspector’s chrome extension to use the Inspector.

from the Pet Store API’s documentation

Sending a GET Request for petId = 1:

GET http://petstore.swagger.io/v2/pet/1

The JSON response is:

{
    "id": 1,
    "category": {
        "id": 1001,
        "name": "Animal"
    },
    "name": "Scooby",
    "photoUrls": [
        "img/test/dog.jpeg",
        "img/test/dog1.jpeg"
    ],
    "tags": [
        {
            "id": 2001,
            "name": "Pet"
        },
        {
            "id": 2002,
            "name": "Animal"
        }
    ],
    "status": "available"
}

Also, the HTTP Response Status is 200 ( OK ) which means “The request has succeeded.”

Sending a GET Request for petId = 10

GET http://petstore.swagger.io/v2/pet/10

The JSON response is:

{
    "code": 1,
    "type": "error",
    "message": "Pet not found"
}

Also, the HTTP Response Status is 404 ( Not Found) which means the pet with id = 10 is not found.

Creating a Pet with petId = 10

POST http://petstore.swagger.io/v2/pet

We have to fill the requests body with the given way in the documentation for both POST and PUT requests:

the request’s body:

{
  "id": 10,
  "category": {
    "id": 1005,
    "name": "Birds"
  },
  "name": "Paradise",
  "photoUrls": [
    "string"
  ],
  "tags": [
    {
      "id": 1005,
      "name": "Parrot"
    }
  ],
  "status": "available"
}

after sending the request, we get the JSON response which is the same as our request’s body:

{
    "id": 10,
    "category": {
        "id": 1005,
        "name": "Birds"
    },
    "name": "Paradise",
    "photoUrls": [
        "string"
    ],
    "tags": [
        {
            "id": 1005,
            "name": "Parrot"
        }
    ],
    "status": "available"
}

Also, the HTTP Response Status is 200 ( OK ) and our pet is created but, it would be better if the API developer sets a 201 ( Created ) status code for creating resources.

6. Video References

What is REST API? | REST API Tutorial | REST API Concept…

What is REST? What is a RESTful API?

Effective Design of RESTful APIs

7. References

HTTP Status Codes

REST API Architectural Constraints — GeeksforGeeks

What is REST? | Codecademy

Understanding And Using REST APIs — Smashing Magazine