Skip to content

API: Understanding our RESTful approach

If you were to describe the integration approach with the Parse.ly API to a colleague in one line, you could say, “it’s a RESTful API implemented with HTTP and JSON”. That’s a mouth-full. This page describes some of the principles behind the design of the API.

Principles

  • HTTP and HTTPS as transports: We chose HTTP for its ubiquity. You should be able to test our API right from your web browser. It should be a single line of code to start making requests from your programming language of choice, including JavaScript.
  • JSON as an interchange format: JSON is a lightweight and human-readable format. JSON’s only real drawback vs. something like XML is that there is no good way to define a JSON “schema” to document the formats formally. So, we will just substitute out a formal schema for documentation and examples.
  • Documented: We should document our API and interchange formats in a way that makes it easy for our users to find what they’re looking for and make the requests and interactions that they need to get their work done. That’s what this documentation is all about.
  • Practicality beats purity: There is a lot of talk about “purely RESTful” APIs out there. But a lot of this talk isn’t rooted in reality. REST suggests you use HTTP methods like GET, POST, PUT, and DELETE. However, making HTTP requests with a method other than GET is complicated in web browsers. We only support the GET method, which allows us to support JSON-P and client-side JavaScript integrations easily. It also means there’s one less thing to remember when working with our API: just use GET.
  • Meaningful error states: When there are problems finding requested data or if a service is down, we should have some well-established error states that can be handled gracefully by our clients. This also involves being practical: for example, it might mean returning HTTP status code 200, but with an error message encoded in the JSON response document, allowing graceful client-side error handling.
  • Supports JSON-P: For purely client-side (JavaScript) integrations with our API, the most convenient standard available is “JSON with padding”, aka JSON-P. This is not a standard part of REST, but it is supported throughout our API via the `callback` query parameter.
  • Well-tested: The API should be tested, and, once it leaves “beta” state, it should be versioned and have a high degree of reliability and consistency.
  • Performant: No endpoints should be slow. Practically speaking, most endpoints should return in <200ms and should rarely take longer than 1000ms.

Design Goals

We were inspired in our design guidelines by the excellent book by Leanard Richardson and Sam Ruby, RESTful Web Services, published by O’Reilly. We highly recommend you pick up a copy of the book if you ever need to design a service of your own.

Give every “thing” a URI

As described by the author:

Use URIs to identify everything that merits being identifiable, specifically, all of the “high-level” resources that your application provides, whether they represent individual items, collections of items, virtual and physical objects, or computation results.

Communicate statelessly

This quote summarizes it best:

It’s important to stress that although REST includes the idea of statelessness, this does not mean that an application that exposes its functionally cannot have state — in fact, this would render the whole approach pretty useless in most scenarios. REST mandates that state be either turned into resource state, or kept on the client.

The way the Parse.ly team interprets this guideline is to “prefer stateless communication, otherwise, idempotence, otherwise, documentation!”. Obviously, you can’t make things stateless, but making them idempotent is probably a good idea, and if you can’t at least make it idempotent, then we better have documented it.

Use multiple endpoints

We assign unique URIs to various analytics listings, metadata drill-downs, recommendation/search engines, etc. This follows the practice described here:

An application might add a few million customer URIs to the Web; if it’s designed the same way applications have been designed in CORBA times, its contribution usually is a single “endpoint” — comparable to a very small door that provides entry to a universe of resource only for those who have the key.

Last updated: August 16, 2023