Algunes recomanacions sobre el disseny d'APIs RESTful

Traducció de l’original en anglès. Llegeix-lo en: CastellanoEnglish

Vull recomanar-vos que mireu el vídeo de YouTube anomenat RESTful API design de Brian Mulloy. En aquest article faig un petit resum de les idees més importants del vídeo, per descomptat des del meu punt de vista:

RESTful API Design - Second Edition · Original a YouTube ↗
  • Usa substantius plurals concrets quan estiguis definint recursos.

  • La URL del recurs ha d'estar centrada en l'accés a la col·lecció d'elements i a l'element concret. Exemple:

  • /clients - obtenir tots els clients

  • /clients/23 - obtenir el client amb ID 23

  • Mapejar els mètodes HTTP als elements de manteniment (CRUD):

  • POST - CREATE

  • GET - READ

  • PUT - UPDATE

  • DELETE - DELETE

  • Workaround, si el teu client REST no suporta els mètodes HTTP, usar un paràmetre anomenat 'method' podria ser una bona idea. Per exemple, quan hagis d'usar un mètode HTTP PUT es podria canviar pel mètode HTTP GET i el paràmetre 'method=put' a la URL.

  • Aparta la complexitat darrere de la '?'. Usa paràmetres a la URL per filtrar o posar alguna informació opcional a la teva petició.

  • Com gestionar els errors:

  • Usa els codis de resposta HTTP per referir els codis d'error. Pots trobar una llista de codis de resposta HTTP a Wikipedia.

JSON response example can be like this:<br><pre>{ 'message':'problem description', 'more_info':'http://api.domain.tld/errors/12345' }</pre><br>

Workaround, si el client REST no sap com capturar els codis d'error HTTP i llançar un error perdent el control del client, pots usar el codi de resposta HTTP 200 i posar el camp 'response_code' a l'objecte de resposta JSON. És una bona idea usar aquesta funcionalitat com a opcional a través del paràmetre d'URL 'supress_response_code=true'.

Versionar l'API. Usa una lletra 'v' literal seguida d'un nombre enter abans de la referència al recurs a la URL. Podria ser la solució més simple i potent en aquest cas. Exemple: /v1/clients/

La selecció de quina informació es retornarà en la resposta es pot definir en els paràmetres de la URL, com en aquest exemple: /clients/23?fields=name,address,city

Paginació de la resposta. Usa els paràmetres 'limit' i 'offset', mantén-ho simple. Exemple: ?limit=10&offset=0

Format de la resposta, en aquest cas no estic del tot d'acord amb en Brian. Prefereixo usar la capçalera HTTP 'Accept' que la seva proposta. De tota manera les dues idees són:

  • Usar la capçalera HTTP 'Accept' amb la petició de format adequat a la resposta, per exemple, 'Accept: application/json' quan vols una resposta JSON.

  • o, usar l'extensió '.json' a la URL de la petició per obtenir la resposta en format JSON.

  • Usa el format Javascript per a la informació de data i hora, quan estiguis formatant objectes JSON.

A vegades les APIs necessiten compartir accions. Llavors no podem definir una acció amb un substantiu, en aquest cas usa un verb. És comú necessitar accions com: convert, translate, calculate, etc.

Cercar, hi ha dos casos:

  • Cercar dins d'un recurs, en aquest cas usa paràmetres per aplicar filtres.

  • Cercar a través de múltiples recursos, aquí és útil crear el recurs 'search'.

  • Comptar elements dins d'un recurs, simplement afegeix '/count' després del recurs. Exemple: /clients/count

  • En la mesura que puguis usa una única URL base per a tots els recursos de l'API, una cosa així com: 'http://api.domain.tld'.

  • Autenticació, simplement usa OAuth 2.0

Per mantenir la teva API KISS normalment és una bona idea desenvolupar SDK en diversos llenguatges, on pots posar més funcionalitats d'alt nivell que a l'API.

Dins d'una aplicació cada recurs té la seva pròpia API però no és una bona idea publicar-la al món, potser usar una API virtual en una capa per sobre és més segur i potent.