RESTful API fundamentals

HTTP and REST

Hypertext Transfer Protocol (HTTP) as the protocol is suitable for transferring different content types like HTML, JSON, XLM format documents, images, audios, videos multimedia, and etc. Hence, HTTP resource can be a document, a photo, or any other digital content. Each resource is identified by a Uniform Resource Identifier (URI) — the most common form of URI is the Uniform Resource Locator (URL), which is known as the WWW address and tells a bit how (scheme, domain, port and etc.) to get a resource. Therefore, URI points to a resource. It could be used different HTTP methods in a request for downloading, creating, changing, updating or deleting a resource: GET, POST, PUT, PATCH, or DELETE. With URL and HTTP methods we could do almost everything with digital resources located on servers.

Representational State Transfer (REST) is an architectural pattern defined based on HTTP. JavaScript Object Notation (JSON) is a digital content standard for REST request and response, it is recommended and most commonly used content for REST services. REST response is representation of the state of a resource. REST resources are located on servers – by a resource representational state transfer client receives representation of resource state.

RESTful

Because REST is just an architectural pattern it is very important to follow constraints defined for the pattern — the implementations that follow the REST architecture pattern are called RESTful web services. The first constraint — REST is a web (WWW) service, hence client with a server should communicate using HTTP. The second constraint — HTTP resources in REST are plural nouns, – that distinguishes from HTTP methods that are verbs in REST. For instance, if you want to define how to retrieve list of any item details from a server you should define this like that: GET http://domain:port/items. The third rule for REST is web service maturity. Mature web services let decoupling clients from servers — four different maturity levels, starting at level 0, of REST are described by Richardson REST Maturity Model.

If plural nouns as HTTP resource names and verbs as HTTP methods being used for a web service it is service at level 2. However, if someone wants to define true Restful web service then he should consider about maturity level 3 — hypermedia controls — content negotiation and HATEOAS. There are number of other things that should be taken into account for defining REST web services: HTTP headers, query parameters, status codes and etc. It could be applied number of other constraints and concepts for REST web services — statelessness, cacheability, uniform interface and etc.

API

Application Programing Interface (API) is set of rules how one application should interact with another application. Hence, REST web service is implementation of API — most of REST web services are APIs, so they are being called RESTful APIs. There are number of other constrains and concepts that should be followed for RESTful APIs. API gateway, important concept for RESTful APIs, is responsible for request routing, API composition, filtering and etc. All API requests from external clients first should go to the API gateway.

RESTful APIs could be created in design-first or develop-first approach. The both approaches should have the same outcome — an API source code and API documentation. Documentation, created in RAML, Swagger or OpenApi is important, because APIs are developer-centric — it should be clear how to consume RESTful API endpoints in other applications. There could be applied number of other best practices for RESTful APIs — versioning, scaling, API portal and etc.