How should we build our cool new API? For a long time, REST was thought to be the only appropriate tool for building modern APIs. But in recent years, another tool was added to the toolbox, when Facebook published GraphQL, the philosophy, and framework powering its popular API. But first things first.

What is REST?

REST (Representational State Transfer) is an architectural style, and as such it defines a set of architectural constraints and agreements. An API which complies with the REST constraints is said to be RESTful. But before we get started with REST, let me clear some common misconceptions: REST is not a standard. REST is not a protocol either. REST is an architectural style consisting of architectural constraints and agreements, which are based on HTTP.

Want to get deeper into it? Learn more in the RESTful API Design Book.

HTTP

REST is designed to make optimal use of HTTP. This is a great advantage of REST, since HTTP-based infrastructure such as servers, caches, and proxies, are widely available. The success of the web-based on HTTP – provides living proof of the scalability and longevity of HTTP-based architectures. REST uses exactly these constraints and agreements that worked so well for the web and applies them to APIs.

Constraints

REST defines a number of constraints for API design. Many of the REST constraints are actually HTTP constraints, and REST leverages these HTTP constraints for APIs. The REST style ensures that APIs use HTTP correctly. These constraints limit the freedom of design, so not every design is allowed anymore. Succumbing to constraints sounds like a loss, but actually, it ensures that we get many desirable properties for free that we do not have to think about anymore. REST imposes the following constraints:

  • Use of HTTP capabilities as far as possible.
  • Design of resources (nouns), not methods or operations (verbs).
  • Use of the uniform interface, defined by HTTP methods, which have well-specified semantics.
  • Stateless communication between client and server.
  • Use of loose coupling and independence of the requests.
  • Use of HTTP return codes.
  • Use of media-types.

Resources

A resource is an abstract data model, which may be built hierarchically and contain sub-resources. Each resource (and even sub-resources) can be identified by its unique URI (Uniform Resource Identifier). A resource is a data structure, which can be serialized to various concrete representations, such as a JSON representation or an XML representation. To create, retrieve, update or delete a resource, a number of different methods are defined. However, not each resource may support all methods.

Methods

REST APIs mostly perform CRUD (Create, Read, Update, Delete) operations, which can be easily mapped to HTTP methods: creation can be performed by a POST, reading is performed by GET, updating is performed by PUT and deletion is performed by a DELETE. These HTTP methods constitute the Uniform Resource Interface; it is the same for all resources.

More …

Learn more in the RESTful API Design Book.