Upgraded docs version is here ✨

Your documentation experience is getting an upgrade. Check it out now!

Go To Beta

Docs upgrade is here. Check it out!

Go To Beta
API ReferenceIntegrationsKnowledge Base

API Basics

What are REST APIs🔗

REST is an architectural style or design pattern for APIs. When a client request is made through a RESTful API, it transfers a representation of the state of the requested resource. Web services that follow the REST architectural style are called RESTful web services.

A RESTful web application exposes information about itself in the form of information about its resources. It also enables the client to take actions on those resources, such as creating new resources (for example, creating a new user) or changing existing resources (for example, editing a post).

Example🔗

Use the Razorpay Payments API to fetch specific payment (the resource) details. The API response returns the payment state, including payment amount, currency, payment method and more. The representation of the state can be in a JSON format.

/payments/:id

What the server does when the client calls an API depends on the following information:

  • An identifier for the resource: This is the URL for the resource, also known as the endpoint.
  • Operation you want to perform on the resource (in the form of an HTTP method or verb): GET, POST, PUT, PATCH and DELETE.

HTTP Methods🔗

HTTP defines a set of request methods, also known as HTTP verbs, to indicate the desired action for a given resource.

Given below is the list of methods commonly adopted by Razorpay APIs:

Verb

Description

Example

GET

Requests a representation of the specified resource. Requests using GET should only retrieve data.

Fetch all payments received by you.

POST

Submits an entity to the specified resource, often causing a change in state or side effects on the server.

Create a Payment Link.

PUT

Replaces all current representations of the target resource with the request payload.

Edit customer details.

DELETE

Deletes the specified resource.

Delete an Invoice.

PATCH

Applies partial modifications to a resource.

Update a Subscription.

Parameters🔗

Parameters are options you can pass with the endpoint to influence the response.

There are four types of parameters:

  • Path Parameters: Path parameters are part of the endpoint itself and are not optional.
  • Query Parameters: Query parameters appear after a question mark (?) in the endpoint. Each parameter is listed in the query string right after the other, with an ampersand (&) separating them.
  • Request Parameters: Request parameters are included in the request body and are used to send data via the REST API.
  • Response Parameters: Response parameters represent the response to a request.

HTTPS Status Codes🔗

HTTP response status codes indicate whether a specific HTTP request is successfully completed. Responses are grouped into five classes:

  • Informational responses (100–199)
  • Successful responses (200–299)
  • Redirection messages (300–399)
  • Client error responses (400–499)
  • Server error responses (500–599)

Refer to Mozilla docs to know about status codes.

Let us look at the success and error response status codes.

Success Responses🔗

Given below is the list of the most commonly encountered success responses:

Status Codes

Description

201 Created

The request succeeded, and a new resource was created. This is typically the response sent after POST requests or some PUT requests.

202 Accepted

The request has been received but not yet acted upon. It is noncommittal since there is no way in HTTP to send an asynchronous response later indicating the outcome of the request. It is intended for cases where another process or server handles the request or batch processing.

Error Responses🔗

Given below is the list of the most commonly encountered error responses:

Status Codes

Description

400 Bad Request

The server cannot or will not process the request due to something that is perceived to be a client error.

401 Unauthorized

Although the HTTP standard specifies "unauthorized", semantically, this response means "unauthenticated". That is, the client must authenticate itself to get the requested response.

404 Not Found

The server can not find the requested resource. In the browser, this means the URL is not recognised. In an API, this can also mean that the endpoint is valid, but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorised client. This response code is probably the most well known due to its frequent occurrence on the web.

500 Internal Server Error

The server has encountered a situation it does not know how to handle.

502 Bad Gateway

This error response means that the server got an invalid response while working as a gateway to get a response needed to handle the request.

503 Service Unavailable

The server is not ready to handle the request. Common causes are a server that is down for maintenance or is overloaded.

504 Gateway Timeout

This error response is given when the server acts as a gateway and cannot get a timely response.

×