7 bad tips to the REST API designer

Adaptation of the article REST WORST PRACTICES, © Jacob Kaplan-Moss. The article is written in relation to Django, but the information will be relevant for a wide range of specialists.

I think that the best way to understand how to do, to study how to do is NOT necessary. I present to your attention the bad advice to the designers of the REST API.

A few weeks ago, I sent this text to a colleague who asked for my advice on designing a REST API in Django. Since then, I have quoted myself several times, in connection with which I decided to publish these tips, it is possible that someone else will find them valuable.

Combine models and resources

In the REST world, a resource is a central concept. It is very tempting to simply take a model (a row in a table), to say that this is a resource - one model, one resource. This solution fails as soon as a problem arises - to present some kind of composite resource and certainly falls into strongly denormalized models.
')
Imagine a Superhero model: this is the only GET / heros / superman / request that should return all its characteristics: a list of friends, a list of related artifacts, etc. See, data associated with a resource can actually come from several models. It is also useful to recall the facade pattern - a resource is a facade for models, and not a specific model.

Hard-sew specific API access control subsystem

The access control method must be pluggable. The access control module must determine which operations on which objects are allowed — this is the only way to make something complex work.

So you can implement any scenario and maintain control over the access control system. For example, in one system you may need to implement anonymous read, read / write when accessing with a developer token and full access for HTTP authentication with administrator data through the admin panel.

Make the returned data format dependent on the type of resource.

It is very tempting, for various reasons, to use a different format of results depending on the type of resource. But this is a very bad idea, because this approach makes client code very complex.

Recall the Yahoo APIs - the ResultSet / Result format is the same everywhere. Also Atom (GData).

The main idea is that client code should not know how to parse many different data formats.

Let your API support only one return data format.

JSON is, of course, cool and needs to be supported from the very beginning. But with the development of the system should be able to select the format of the output, for example, AtomPub.

Moreover, the output format should be defined natively, through the HTTP Accept header, and not through extra constructions like? Format = xml.

Overload the semantics of standard HTTP protocol methods

Most of the REST APIs I've seen display the main standard HTTP methods (POST / GET / PUT / DELETE) into the corresponding CRUD methods (create / retrieve / update / delete). This is not a good idea, because some resources can use the POST-as-creator-related-resources pattern, while others can use POST-as-editing for backward compatibility with HTML forms. Any form must be valid.

Moreover, such systems do not allow the use of advanced HTTP methods. WebDAV defines several useful methods, as well as the new HTTP PATCH method is officially part of the standard. No one says that you should limit yourself to four main HTTP methods, it’s only that these methods are widely supported, because non-standard HTTP requests can simply be ignored by the web server.

Use indexes to define links between resources.

So you want one resource to refer to another. For example, PhotoAlbum refers to Photo objects. Usually you do it something like this:

{ 'album': 'whatever', 'photos': [1, 2, 3, 4] } 

Just specify the object ID, right? Sadly, this means that client code should “just know” how to construct URLs for Photo resources. This also means that the client and server code become dependent. As a bonus, you get all the problems associated with the incompatibility of the API and client code. Almost all the APIs on our planet make this error, so the slightest change in the URL format will automatically break all the clients of your API.

Just use ready URLs:

 { 'photos': ['http//example.com/ph/1', ...] } 

Or, if the hair stand on end from duplication, tell us the URL format:

 { 'photos': [1, 2, 3], 'photo_uri_template': 'http://example.com/ph/{id}' } 

Tie the REST API to your application

Any large API should have a dedicated server (s) for its work: performance characteristics and the factors on which they depend are so different from ordinary web applications that large APIs require separate, specially configured servers. It is a fact. Moreover, if the API server crashes, it should not affect the publicly accessible website.

All success in designing API!