How PrizmDoc Editor Stays RESTful

In the modern web, the concept of being “RESTful” is commonplace. The design concept has been around for many years now, which means there are a million and a half-existing articles and tutorials that explain what that person believes are the fundamentals, so I am going to try and avoid doing that here. Instead, I want to give a light overview of the generally agreed upon pillars of what makes a concrete RESTful service and how we have been able to apply those pillars to our own PrizmDoc Suite plus any specifics that we have decided were best suited for our project’s needs.

To begin, just in case you are unfamiliar, REST is a set of principles that one can choose to use to design a web service project. It focuses on managing a system’s resources and how to handle resource and application state over HTTP. Across the many articles that talk about the fundamentals or best practices of a RESTful web service, there seem to be a few consistent themes that we can extrapolate and identify as the basic principles that we will use as a reference in this article:

• Explicit use of HTTP methods (verbs)
• Statelessness
• Using JSON (or XML) for data transfer
• Proper use of status codes

 

Explicit Use of HTTP Methods

For the sake of consistency and readability, a RESTful web service should use HTTP methods (GET, POST, PUT, DELETE) as they are defined in their protocol.

In PrizmDoc Editor, we have a collection of documented public API routes that an integrator will need to use to manage their documents and sessions. For documents, we allow for both uploading and downloading a document:

Download Document

GET /api/v1/documents/:documentId

 
Upload Document

POST /api/v1/documents

 
Since both of these routes go through the same service (using the same API base route), it is important that we are explicit with which HTTP method we use in order to avoid confusion for both the integrator as well as our own development team. For all of our GET routes, as defined in the HTTP method protocol, it is expected that no changes will be made to any data by the server, but rather it will fetch the requested resource and return it with no side effects, whereas POST will, in fact, trigger an update to the internal document store with the addition of a new document.

In addition to the correct use of the methods, we are also utilizing another important REST principle in how we structure our URIs. It is generally agreed upon that within a RESTful web service, URIs should be structured in a way that makes it predictable and easily understood as to what that route is going to do. We want to avoid using query strings as much as possible, and we also don’t want to have route names that state what their operation is (ex: /getDocument), so we combine the practice of explicit HTTP methods with a URI naming convention that uses a directory-like structure (starting with a base and getting more specific as you go) in order to make our API as clear as possible:

GET /api/v1/sessions/:sessionId/document
GET /api/v1/sessions/:sessionId/document/:format
GET /api/v1/sessions/:sessionId/document/files
GET /api/v1/sessions/:sessionId/document/files/*

 
These routes also demonstrate another RESTful practice we utilize here, and that is versioning. Part of our base API path includes a version number (v1). This makes it easy to upgrade the API when breaking changes are introduced so that we don’t break existing users with new functionality. To learn more about statelessness, using JSON or XML for data transfer, and proper status codes, download my full article here.