#hateoas

https://gist.github.com/06d6e52d102bc4d93ffa

Le model Service représente une prestation, le model Option définit un ensemble de Service, qui forment ainsi l'option. Il nous faut le model OptionService car le prix d'une prestation dépend de l'option à laquelle elle est rattachée.

L'api que je souhaite exposer est donc la suivante :

https://gist.github.com/97d81fbe526384ea9c14

Commençons par créer le serializer qui pose le moins de problème :

https://gist.github.com/0f6295cfca59be7a4160

Nous utilisons ici des HyperlinkedModelSerializer pour afficher l'url des objets plutôt que des foreign_key afin de rester le plus unitaire possible.

Maintenant que le serializer est prêt, nous allons utiliser une ModelViewSet et un DefaultRouter pour pouvoir rapidement commencer à naviguer dans notre api :

https://gist.github.com/70609d53e735af72db26

https://gist.github.com/a234445e3ee636fa88de

Je me suis permis de créer quelques objet Service via l'admin Django pour avoir quelques données. Nous pouvons maintenant accéder à la liste des services via l'api :

https://gist.github.com/153a7780612627ba5d69

Ca c'était pour la partie facile ! Maintenant nous allons entrer dans le vif du sujet, la gestion de la relation many to many entre Option et Service via OptionService.

drf-nested-routers à la rescousse

Django REST Framework ne gère pas nativement le genre d'url que l'on veut obtenir, à savoir une url du style /options/1/services/2/ pour afficher l'objet OptionService qui relie l'option 1 avec le service 2.

Pour ce faire, nous allons avoir besoin du package drf-nested-routers. Une petite commande pip install drf-nested-routers suffira à l'installer.

Ce package va nous aider pour les routes mais ne gère pas correctement les relations avec les HyperlinkedRelatedField proposé par Django REST Framework. Nous allons donc créer notre propre HyperlinkedNestedRelatedField dérivé de HyperlinkedRelatedField. Je vous propose ce gist :

https://gist.github.com/39296bfe6db5925be663

Vous pouvez créer cette classe dans un module relations.py par exemple.

Nous allons grâce à cette classe pouvoir afficher la liste des services liés à une option via la classe OptionService sous la forme : /options/1/services/2/.

Nous sommes maintenant équipés pour créer les serializers et les vues qu'il nous manque. Commençons par les serializers:

https://gist.github.com/4f288d598f6ef7039cfd

Le paramètre view_name='optionservice-detail'fait référence au nom de la route que va générer drf-nested-router. Nous verrons ça juste après. Car avant de créer les routes, nous avons besoin de créer les vues qu'il nous manque :

https://gist.github.com/8f43d32bddabad1f196b

Ne prenez pas peur devant l'ampleur de ce gist. En fait il s'agit beaucoup de copier-coller depuis les classes de bases de Django REST Framework. Concentrons nous sur les modifications apportées :

dans la vue OptionServiceViewSet j'ai ajouté une variable lookup_url_kwargs au pluriel, il existe aussi une variable lookup_url_kwarg au singulier qui permet à Django REST Framework de faire quelques vérifications quant à la structure de l'URL. Comme ici nous avons plusieurs arguments dans l'url, la variable au pluriel nous permet d'itérer sur le tableau d'argument pour vérifier que les arguments figurent bien dans l'url (c'est l'objectif du for lookup_url_kwarg in self.lookup_url_kwargs dans la méthode get_object)

la méthode get_object() a été modifié pour filtrer en fonction des arguments reçu, à savoir option_pk et pk qui représente en fait ici l'id du service et non celui de l'objet OptionService !

Pour le reste les docstring sont suffisantes pour comprendre.

Dernière étape : configurer les routes grâce à drf-nested-routers. Ajouter dans votre fichier urls.py la configuration suivante :

https://gist.github.com/2c5a7e958f26cec28640

#hateoas Is documentation needed for HATEOAS/HAL/Hypermedia?  Sure the argument is that the reason for the existence of HATEOAS is that it is self documenting.  

Stories about how HAL is to services as browsers are to humans are all over the internet.  The problem is that I don’t need someone to program me to know where to find a URL in the first place.  No need to explain to me what fields I should care about.

As a programmer I care about what fields exist and what they mean.  Not just that a rel link exist.  

When we started building our Android app and came to a point in development, when we could finally wed our app to our internal RESTful API, we chose to do so with the help of a very nifty library called Retrofit build by the excellent developers at Square.

Retrofit turns your REST API into a Java interface. That's how it is described on Retrofit's project page over at GitHub and this is exactly the reason why we might regret ever using Retrofit. With Retrofit, you define a Java interface that represents your API, where the defined methods represent the API endpoints, and it is automagically turned into a Java object that works as advertised. Retrofit's magic heavily relies on Java annotations, which is not a bad thing by itself.

Let's look into how you would define an API endpoint using Retrofit.

public interface ExampleAPI { @GET("/cars/{car}/driver") public Driver getCarDriver(@Path("car") String car); }

The @GET("/cars/{car}/driver") annotation tells Retrofit, that the API endpoint for the getCarDriver method is /cars/{car}/driver and the HTTP method to use is GET. The {car} part in the URL is actually a placeholder that can be filled by parameters passed to the method at runtime using the @Path annotation.

This approach requires the application to hardcode (with the exception of placeholders and such) every single API endpoint used by the application. This, in turn, assumes prior knowledge of said endpoints and led us to our whole API architecture based on this assumption.

So, instead of our API sending out hypermedia with hyperlinks to connected resources and thus employing Hypermedia as the Engine of Application State (HATEOAS), our API relies on the clients to guess, or rather know its whole architecture.

Why is this bad? Because now, whenever a single endpoint's signature, including endpoint URL and expected parameters, changes, every single client acting upon the API has to implement this change. This leads to unnecessary code changes and application deployments.

Python toolkit for REST / HATEOAS APIs

You have data stored somewhere and you want to expose it to your users through a RESTful Web API. Eve is the tool that allows you to do so.

Eve provides a robust, feature rich, REST-centered API implementation, and you just need to configure your API settings and behavior, plug in your datasource, and you’re good to go. See Features for a list of features available to Eve-powered APIs.

In a perfect world code would talk with code and do so seamlessly.  Sadly, as is the case with everything that man has built, APIs come in different shapes and sizes and getting them to talk with each other can sometimes be the major pain in your posterior.

The most common way of thinking of APIs/webservices today is going RESTful. It is common because it is efficient, simple and (if done well) can be an elegant way of opening up your system to the outside world.

I will try to list down a few best practices (as they are called) which are rather common sense checklist that one must keep in mind before venturing out to design an API:

Versioning - Even if you are making an API that only talks to your own front-end code hosted on the same box, it makes sense to have a version number for your API. Most frameworks that help you build quick and robust APIs already give a provision to include a version number, if the one you are using does not, make sure you do that extra bit of adding one to the endpoint url. It would make the life of clients interacting with your API a lot easier when something changes. The way you include is a matter of aesthetics! I personally like to have something of this sort:

http://api.awesomeapp.com/v1/users

You can include it as a query parameter as well, which brings us to the next point.

Clean URL vs query parameters - Again, this is a matter of choice. No really! Ideally, let the juice of the request be clean and use query parameters for things like 'offset', etc. The 'juice of the request' is the end-point name, version number of the API, etc. examples:

http://api.awesomeapp.com/v1/users/id http://api.awesomeapp.com/v1/users?offset=1000&fromId=1234

RESTFul is old school (and it kicks ass) - REST is nothing new. It is not a new protocol,  just a new way of looking at API with old (experienced) eyes. REST is built on the good old http protocol. The basic idea is to use the http methods (GET, POST, PUT, DELETE) along with an end-point (and throw in your common sense along). Here's the common sense bit: Take GET for example for the resource 'users'. If the url points to a specific record (which is the case when, say, an 'id' is appended at the end) return that record, otherwise return a list of records.

Returning lists - Not many systems would like to receive hundred thousand records when they query your API! Always use lazy-loading of objects and limit the number of records that are fetched together and sent back in the response. Use 'offset', etc. in the query parameters to get the remaining set. (Streaming APIs are a different beast that we'll kill in another episode)

HATEOAS is your best friend - I recommend that you visit that link and read more on HATEOAS! In short what it means is that when you send your response, let's say, for a list of users, make sure that each user node in that list has a uri pointing to that particular user. Which brings us to the next point.

Data exchange - I would highly recommend using JSON as the format of data exchange between the server and the client. JSON format is clean, easily extendable and almost every language has great JSON parsers that make life easy for you. If you are using something like MongoDb as your database, the implementation becomes a piece of cake because Mongo uses BSON and in most cases all you'll have to do is use the request and response interchangeably to communicate between the server and client.

Authentication - There are many options. The option that you should never opt is an API without authentication!!! I would suggest you to go for OAuth (there are different versions - look for a future post on this site for which one to use or go read the rfc notes). It is the recommended way of authentication for web-services and there are tons of libraries that you can use to create your own OAuth provider.

Don't be a snobbish web-service - Be good to the client! Do proper error handling and always return proper (documented) error messages/codes in the same format that success responses go. For example, don't throw a 404 HTTP error code response, have an error code inside your 200 response that tells the client that the request failed, etc. Include URIs to help documentation in the error response or at the least give detailed error messages.

Good to haves - Here are a few things that are good to bundle with your API implementation. They go well with the point number 8 above:

Build a test client that let's your users experiment on a test data set.

Have an API schema entry point. This should list out all entry points of the API (think of this as the top level of a perfect HATEOAS implementation)

Design the APIs in such a way that even when the implementation behind the scenes changes, the API end-points remain the same (this is in fact one of the most important thing to consider in API design!)