An Introduction to REST

Background

When we talk about our API, we use terms like “REST” and “RESTful.” “REST” stands for Representational State Transfer. It’s an architectural style that’s an alternative to RPC or SOAP-based web services.

While there’s no official REST standard, there are common approaches and best practices used across the engineering community that help define how RESTful APIs should work. For example, most RESTful APIs follow six specific constraints or design rules.

Most APIs aren’t fully RESTful, including the Claromentis API. But we follow most of the practices and common definitions of the style. For example, the Claromentis API has what we call “resources,” which are typically nouns like “articles” or “categoried”. You take action on resources using the standard HTTP methods: POST, GET, PUT, and DELETE.

RESTful HTTP Methods

You may see these standard HTTP methods referred to as CRUD, or Create, Read, Update, Delete. Although CRUD has roots in database operations, you can also map those operations to the standard HTTP methods. For example, use a POST request to create a new resource, a GET request to read or retrieve a resource, a PUT request to edit a resource, and a DELETE request to delete a resource.

RESTful Features of the Claromentis API

Nouns

RESTful APIs are based on resources, and share a well-defined and uniform interface. URLs and URIs in the API don’t typically contain verbs because verbs can’t be resources. That’s why we try to limit verbs to the HTTP method part of your request.

We also refer to “endpoints” in our documentation. Endpoints are URIs (as opposed to URLs) for individual resources. For example, find a collection of lists by requesting the /lists/ endpoint, or access individual lists at /lists/:list_id.

HTTP methods and response codes

We do our best to use standard HTTP methods with accurate and well-known status codes in the Claromentis API, but here are some additions and deviations.

GET requests are safe, and won’t alter a resource. PUT and DELETE methods are idempotent. POST isn’t safe or idempotent. If your firewall rules don’t support HTTP methods like PUT or DELETE, use the X-HTTP-Method-Override header. Pass the method you want to use in the X-HTTP-Method-Override header and make your call using the POST method. The override won’t work with any other method, so if you try and use the override header with a GET, PATCH, PUT, or DELETE method, you’ll receive an error.

Additionally, the 204 No Content error doesn’t include JSON body content to parse. This is most common with DELETE requests, and could cause issues if your JSON parser doesn’t handle empty responses well.

Deviations from REST

Verbs we use

In some places in the Claromentis API, we need to deviate from common REST guidelines. Completely removing verbs isn’t possible for every request, for example, when approving a document. Although there are some RESTful workarounds we could use, they’re typically more confusing than they are useful.

To address this, we break from REST architecture for certain actions. For example, when approving a draft document, you would make a PUT request to the /document/:doc_id/approve endpoint. All action endpoints are namespaced this way.

Generic MIME types

Some companies or vendors will use a custom MIME type for their RESTful APIs instead of the generic JSON type (application/json). For the Claromentis API, we use the generic JSON content type, because the benefits of customization are more theoretical than practical for our API.

Now that you know a bit more about the REST architecture and how we use it in the Claromentis API, be sure to check out the Getting Started and API Reference pages.