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 the principles behind the design of the API.
- 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 portal is all about.
- 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.
- 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.
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.
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.”