A REST API stands for Representational State Transfer Application Programming Interface. Rest API is a type of web API that uses HTTP protocol to transfer data between a server and a client. REST APIs are designed to be lightweight and easy to use, making them ideal for building modern, scalable web applications and mobile apps.
A REST API resources are represented as URLs and are accessed using HTTP methods such as GET, POST, PUT, PATCH and DELETE. The server responds to these requests with appropriate HTTP status codes and, if applicable, a representation of the requested resource in the body of the response.
REST APIs are designed to be stateless, meaning that each request is self-contained and does not rely on information from previous requests. This allows for flexibility and scalability, as it allows clients to connect and disconnect from the API at will without affecting the overall system.
A REST API works by sending HTTP requests to a server and receiving HTTP responses in return. The server is typically a web server that is designed to handle these requests and provide the appropriate response.
1. A client sends an HTTP request to the server, specifying a particular resource and the desired HTTP method (e.g. GET, POST, PUT, DELETE).
2. The server receives the request and processes it, using the resource and HTTP method specified in the request to determine how to handle the request
3. If the request is successful, the server sends an HTTP response back to the client, containing the requested resource (if applicable) and an HTTP status code indicating the status of the request.
4. If the request is unsuccessful, the server sends an HTTP response with an appropriate HTTP error code (e.g. 500 for internal server error) and an error message in the body of the response.
A REST API, the client and server communicate using the HTTP protocol, which is a standardized set of rules for transferring data over the internet. The client initiates the request and the server responds with an appropriate response, using the HTTP methods and status codes defined in the HTTP specification.
| Method | Purpose | Property |
|---|---|---|
| GET | Get Method is used to retrieve data from a server. | Safe, Idempotent |
| HEAD | Headers Method are included in the response. Request resource metadata. | Safe, Idempotent |
| POST | POST Method is used to send data to the server, typically to create a new resource. | Not Safe, Not Idempotent |
| PUT | PUT Method is used to send data to the server, typically to update an existing resource. | Not Safe, Idempotent |
| TRACE | Message body contains the request message as received by the server | Safe, Idempotent |
| OPTIONS | OPTIONS Method is request a list of supported methods for a resources. | Safe, Idempotent |
| DELETE | DELETE Method is used to delete a resource from the server. | Not Safe, Idempotent |
| PATCH | PATCH Method is used to apply partial modifications to a resource, rather than replacing it entirely. | Not Safe, Not Idempotent |
| CONNECT | CONNECT Method is request a tunnel from a proxy to a designated server | Not Safe, Not Idempotent |
| Parameter | REST API | SOAP API |
|---|---|---|
| Acronym | Representational State Transfer | Simple Object Access Protocol |
| Meaning | REST is an architecture style for designing communication interfaces. | SOAP is a protocol for communication between applications |
| Design | REST API exposes the data. | SOAP API exposes the operation. |
| Transport Protocol | REST works only with HTTPS. | SOAP is independent and can work with any transport protocol. |
| Data format | REST supports XML, JSON, plain text, HTML. | SOAP supports only XML data exchange. |
| Performance | REST has faster performance due to smaller messages and caching support. | SOAP messages are larger, which makes communication slower. |
| Scalability | REST is easy to scale. It’s stateless, so every message is processed independently of previous messages. |
SOAP is difficult to scale. The server maintains state by storing all previous messages exchanged with a client. |
| Security | REST supports encryption without affecting performance. | SOAP supports encryption with additional overheads. |
| Use case | REST is useful in modern applications and public APIs. | SOAP is useful in legacy applications and private APIs. |
A URI acronym of Uniform Resource Identifier, is a sequence of characters that identify a name or a unique resource on the Internet. A URI contains Scheme, Authority, Path, Query, and a Fragment.
A URIs can be broken down into two main categories: URLs (Uniform Resource Locators) and URNs (Uniform Resource Names).
A URI, or Uniform Resource Identifier, is a string of characters that identify a name or a resource. URIs can be used to identify any type of resource, such as a web page, an image, a video, or a specific piece of information.
A URL, or Uniform Resource Locator, is a specific type of URI that specifies the location of a resource on the internet. URLs are used to access web pages and other resources on the internet, and typically include a protocol (such as "http" or "https"), a domain name, and a path to the specific resource.
A URN, or Uniform Resource Name, is another type of URI that is used to identify a resource by its name, rather than its location. URNs are used to provide a persistent and location-independent way to identify resources.
Between a URI or a URL and their usage is essential for every webmaster. For example, building a REST API using a predictable and hierarchical structure of a URI or a URL can improve the REST API performance. A query is an optional component that contains a query string of non-hierarchical data. It is often a string of key=value pairs. This component is preceded by a question mark.
Informational Codes (100 - 199) : The server acknowledges and is processing the request.
| Status Code | Function | Purpose |
|---|---|---|
| 100 | Continue | This interim status code means the server received the initial request, and the client should continue. |
| 101 | Switching Protocols | This code is a response to an Upgrade header field request and states the protocol the server will switch to. |
| 102 | Processing | This response indicates the server received and is processing the request, but no response is yet available. |
| 103 | Early hints | This code is used with the Link header and allows the browser to preload resources while the server prepares a response. |
Success Codes (200 - 299) : The server successfully received, understood, and processed the request.
| Status Code | Function | Purpose |
|---|---|---|
| 200 | OK | This is the standard response for successful HTTP requests. |
| 201 | Created | The request succeeded and a new resource was created. This is usually the response after POST or PUT requests. |
| 202 | Accepted | The request was accepted but is still in progress. It’s used for cases where another server handles the request or for batch processing. |
| 203 | Non-Authoritative Information | The data returned isn’t from the origin server. Instead, it’s a modified version collected from a third party. |
| 204 | No Content | The request was successfully processed, but there is no content. The headers may be useful. |
| 205 | Reset Content | The server fulfilled the request but asked the user to reset the document. |
| 206 | Partial Content | The server is delivering part of the resource. This response is used when the client sends a Range header to request only part of a resource. |
| 207 | Multi-Status | Provides the statuses of multiple resources, depending on how many sub-requests were made. |
| 208 | Already Reported | The members of a DAV:propstat element have already been listed and won’t be included again. |
| 226 | IM Used | The server completed a GET request. And the response indicates one or more instance-manipulation results. |
Redirection Codes (300 - 399) : The server received the request, but there’s a redirect to somewhere else.
| Status Code | Function | Purpose |
|---|---|---|
| 300 | Multiple Choices | The request has more than one possible response. And the user should choose one of them. |
| 301 | Moved Permanently | This redirect status code indicates the requested resource has permanently moved to a new URL. The browser displays the new URL. |
| 302 | Found | Previously known as “Moved Temporarily,” this code indicates the requested resource has temporarily moved to a new URL. |
| 303 | See Other | The server redirects the user to the requested resource with a GET request at another URL. |
| 304 | Not Modified | Used for caching purposes. The response hasn’t been modified, so the client can continue to use the same cached version of the requested resource. |
| 307 | Temporary Redirect | The requested resource temporarily moved to a different URL. The only difference vis-a-vis the 302 code is the user must not change the HTTP method used. |
| 308 | Permanent Redirect | The requested resource permanently moved to a different URL. The difference between this code and 301 is the user must not change the HTTP request method. |
Client Error Codes (400 - 499) : The server couldn’t find (or reach) the page or website. This is an error on the site’s side.
| Status Code | Function | Purpose |
|---|---|---|
| 400 | Bad Request | The server can’t or won’t process the request due to a client error. For example, invalid request message framing, deceptive request routing, size too large. |
| 401 | Unauthorized | The user doesn’t have valid authentication credentials to get the requested resource. |
| 402 | Payment Required | Reserved for future use; it was initially intended for digital payment systems. It’s very rarely used, and no standard convention regulates it. |
| 403 | Forbidden | The client doesn’t have access rights to the content. For example, it may require a password. Unlike the 401 HTTP error code, the server does know the client’s identity. |
| 404 | Not Found | The server can’t find the requested resource, and no redirection has been set. 404 errors can harm your SEO efforts. |
| 405 | Method Not Allowed | The server supports the request method, but the target resource doesn’t. |
| 406 | Not Acceptable | The server doesn’t find any content that satisfies the criteria given by the user according to the Accept headers requested. |
| 407 | Proxy Authentication Required | This is similar to a 401, but a proxy must authenticate the client to continue. |
| 408 | Request Timeout | The server timed out waiting because the client didn’t produce a request within the allotted time. |
| 409 | Conflict | The server can’t fulfill the request because there’s a conflict with the resource. It’ll display information about the problem so the client can fix it and resubmit. |
| 410 | Gone | The content requested has been permanently deleted from the server and will not be reinstated. |
| 411 | Length Required | The server rejects the request because it requires a defined Content-Length header field. |
| 412 | Precondition Failed | The client indicates preconditions in the header fields that the server fails to meet. |
| 413 | Content Too Large | The client’s request is larger than the server’s defined limits, and the server refuses to process it. |
| 414 | URI Too Long | The URI (Uniform Resource Identifier) requested by the client is too long for the server to process. |
| 415 | Unsupported Media Type | The request uses a media format the server does not support. |
| 416 | Range Not Satisfiable | The server can’t fulfill the value indicated in the request’s Range header field. |
| 417 | Expectation Failed | The server can’t meet the requirements indicated by the Expect request header field. |
| 421 | Misdirected Request | The client sends a request to a server that can’t produce a response. |
| 422 | Unprocessable Content | The client correctly sends the request, but the server can’t process it because of semantic errors or similar issues. |
| 423 | Locked | The requested method’s resource is locked and inaccessible. |
| 424 | Failed Dependency | The request failed because a request the initial request depended on also failed. |
| 425 | Too Early | The server is unwilling to process a request that might be replayed. |
| 426 | Upgrade Required | The server refuses to process the request using the current protocol unless the client upgrades to a different protocol. |
| 428 | Precondition Required | The server needs the request to be conditional. |
| 429 | Too Many Requests | The user sends too many requests in a certain amount of time. |
| 431 | Request Header Fields Too Large | The server can’t process the request because the header fields are too large. |
| 451 | Unavailable for Legal Reasons | The user requests a resource the server can’t legally provide. |
Server Error Codes (500 - 599) : The client made a valid request, but the server failed to complete the request.
| Status Code | Function | Purpose |
|---|---|---|
| 500 | Internal Server Error | The server has encountered an unexpected error and cannot complete the request. |
| 501 | Not Implemented | The server can’t fulfill the request or doesn’t recognize the request method. |
| 502 | Bad Gateway | The server acts as a gateway and gets an invalid response from an inbound host. |
| 503 | Service Unavailable | The server is unable to process the request. This often occurs when a server is overloaded or down for maintenance. |
| 504 | Gateway Timeout | The server was acting as a gateway or proxy and timed out, waiting for a response. |
| 505 | HTTP Version Not Supported | The server doesn’t support the HTTP version in the request. |
| 506 | Variant Also Negotiates | The server has an internal configuration error. |
| 507 | Insufficient Storage | The server doesn’t have enough storage to process the request successfully. |
| 508 | Loop Detected | The server detects an infinite loop while processing the request. |
| 511 | Network Authentication Required | The client must be authenticated to access the network. The error should include a link where the user can submit credentials. |