RESTful APIs getting started

This page is a starting guide for working with RESTtul APIs

API

An API or Application Programming Interface is a way of how one system talks to another. It is how the Instagram application on your phone talks to the backend server to request data. Without a common interface that both systems understand, (server understands the shape of the data to send and the client understands how to use the data) applications wouldn't be able to talk to each other.

REST API

REpresentational State Transfer is one of the architectures of an API. The REST API is all about a resource (some data stored somehow on the server(s)) and the way how this resource is being transferred to/from the client and what operations are permitted on a resource.

In RESTful APIs, there are endpoints that provide access to a resource. An endpoint is a URI under which data may or may not exist. An operation that can be performed on an endpoint is the method, also sometimes called the verb. There is a list of well-defined methods and each of them has a different semantic meaning.

A method is not defined by REST API but rather by the underlying HTTP protocol. APIs just use those methods to provide a way to get or modify the data on the server.

POST method semantically means that this operation creates a new entity (new data).

GET method means requesting the current state of the data. GET request can be about requesting a list of resources (like getting a list of Instagram posts) or about requesting a single resource (requesting a single Instagram post).

PUT operation semantically means updating the whole resource with the data that are transmitted in the request message payload.

PATCH is similar to PUT but it means to update only this part of the resource that is defined in the request payload. Other properties are unchanged.

DELETE method removes the data from the system.

There are more well-defined methods that you can use with your API. Read more about it on MDN pages.

HTTP Request

Each API method can be invoked by making an HTTP (in most cases) connection to a server and by sending the specially prepared message that every HTTP server understands.

The core Advanced REST Client role is to provide a UI for you to provide only relevant data to communicate with the server and it takes care of generating a valid HTTP message. It also reads the response from the server and presents it in a meaningful way to you so you don't waste your time decoding HTTP messages.

An HTTP message consists of 3 parts: start line, headers, and the message. The value of each part may vary depending on the request method.

The start line describes the requests. It contains the method name, the path to access the resource (the endpoint), and the protocol version.

GET /endpoint HTTP/1.1

Optional headers part of the message contains a list of meta-information that describes the request or the client. There is a list of predefined request headers that every HTTP server understands. It is also possible to use custom headers but only some servers will understand it.

Each line in the headers part of the message represents a single header. A header starts with a name, then the value separator - a colon - and after that the value of the header.

An example headers part:

Host: httpbin.org
Content-Type: application/json
user-agent: advanced-rest-client
accept: */*
content-length: 110459

Header names are case insensitive per the HTTP specification. Clients have no obligation to transform headers into a specific form. Headers in the example above are valid even though only some of them start with a capital letter.

Each of the headers has a meaning and the server uses the values to properly process the request. Read more about request headers on the MDN request headers reference page.

Optional payload or body part is the resource or data being transferred to the server. The body part must be separated from the previous part with an empty line. The body can be anything: an image, a text, some other binary data, or a combination of them.

Technically in some situations, it is possible to add a body part to GET and HEAD messages but most popular clients (including all HTTP clients on the web) disallow setting the body for these two methods. HTTP specification does not specify the body for those requests and there's no default behavior.

Full example of a HTTP message

POST /post HTTP/1.1
Host: httpbin.org
Content-Type: application/json
content-length: 23

{
  "data": "value"
}

HTTP Response

An HTTP response, the one that is sent from the server back to the client, is very similar to the HTTP request. The two differences are that the start line is formatted differently and it has a different set of headers (called response headers).

The start line consists of the HTTP version, status code, and optional status message.

HTTP/1.1 200 OK

Status code is pre-defined by the HTTP transport specification codes. And so:

• codes of group 100 (1xx) are used when a communication protocol is being negotiated; only HTTP client and server cares about this group

• codes of group 200 (2xx) indicates a success of the request

• codes of group 300 (3xx) indicates a redirect of some sort (resource location changed, there are multiple choices of a response, etc)

• codes of group 400 (4xx) indicates client errors (client not authorized, resource does not exists, etc)

• codes of group 500 (5xx) indicate server errors

Read more about the response status code, with the full list of predefined codes, on MDN status code page.

The most common status codes are:

• 200 - Successful request. If the request method is GET it means that the message part contains requested data

• 201 - Created - When a request method was POST it indicates that the data entity has been created

• 301 - The resource has been moved permanently to another location (endpoint)

• 307 - The resource has been moved temporarily to another location (endpoint)

• 401 - Unauthorized access to the resource. It usually means that authorization data are missing, invalid, or expired.

• 404 - Resource not found under given URI

• 500 - A server encountered a problem that resulted in an exception; the request processing was aborted

• 503 - The server is not yet ready to accept connections.

ARC shows additional non-standard status code: 0 (zero). It is reported when the application wasn't able to establish a connection to the server. There may be multiple reasons for that but most commonly is either URL is invalid (check hostname spelling) or the server is down. Less common: DNS cannot find the domain or is down.