REST API for technical writers: a primer

REST API for technical writers: a primer

REST APIs are a type of API that involves a user making data requests to servers and servers responding with the requested information, as long as the user (called client) follows the standard protocol. HTTP is the protocol used for this data exchange.

REST APIs, or RESTful APIs, are APIs that conform to the principles of the REST architectural style, defined by DR. Roy Fielding, a pioneer in web technologies and one of the authors of HTTP and URL specifications.

REST is the preferred “framework” for the web. But it isn't really about web services (i.e., machine-readable APIs that return data in JSON or XML). Rather, REST is a recommendation—a description of how the modern web ought to be designed and built. It is supposed to be RESTful!

The Principles of REST

REST is defined by a set of principles called "constraints." For a web application to qualify as RESTful, it must apply these constraints:

  • Client-Server Architecture: The user’s interface concerns must be separate from the server’s, allowing both systems to evolve independently.

  • Statelessness: Each request from a user to the server must contain all the information necessary to understand and process the request.

  • Uniform Interface: There must be a uniform way to interact with resources, like the use of standard HTTP methods (GET, POST, PUT, DELETE) and standard formats (JSON or XML) for data exchange.

  • Cacheability: Responses from the server should indicate whether they can be cached (stored temporarily) or not. A well-managed caching improves performance.

Read the Wikipedia page for a full list and a more detailed discussion of REST's architectural constraints.

In general, REST gives developers a huge amount of flexibility that they don’t get using other APIs. This explains the widespread popularity of REST in building scalable and compatible web services.