Ves al contingut principal

Una crida API

L'especificació d'una API o API Spec, és la documentació que descriu el comportament d'una API, seria també com un contracte de l'API. La finalitat d'aquesta documentació és guiar al desenvolupador que va integrar la utilització de l'API al sistema. Hi ha diverses eines i estàndard creats específicament per descriure una API REST com són RAML, Swagger i el estàndard OpenAPI.

Els components que defineixen una API Spec són:

Verb HTTP

Els verbs propis del protocol HTTP es varen definir per treballar les operacions més bàsiques sobre els recursos API. Els més utilitzats són:

  • GET: llista de recursos. Detall d'un sol recurs.
  • POST: creació d'un recurs
  • PUT: modificació total d'un recurs
  • PATCH: modificació parcial d'un recurs
  • DELETE: eliminació d'un recurs. En algunes ocasions es tracta d'un soft delete, és a dir, no s'elimina definitivament un recurs si no únicament es marca com eliminat o desactivat. Si l'usuari no té l'autenticació adient, la sol·licitud fallarà.
URL orientada a recursos

La definició de els URL, són els endpoint de l'API, és a dir, les entitats que tinguin coherència dins el context de l'API. Per exemple en una API d'un sistema que gestiona llibres, autors, editorials, col·leccions, etc. Les entitats que veuríem reflectides en els URL orientats a recurs serien:

  • /api-llibres/v0/autors: identifica els recursos anomenats autors [tots els autors]
  • /api-llibres/v0/autors/{id-autor}: identifica un recurs, autor [un autor concret]
  • /api-llibres/v0/autors/{id-autor}/llibres: identifica els llibres d'un autor en específic
  • /api-llibres/v0/llibres: identifica els recursos, llibres
  • /api-llibres/v0/editorials: identifica els recursos editorials
  • /api-llibres/v0/editorials/{id-editorial}/llibres: identifica els llibres d'una editorial
Capçaleres HTTP

Les capçaleres HTTP de les sol·licituds són les metadades que s'intercanvien entre el client i el servidor. Per exemple, la capçalera d'una sol·licitud indica el format de la sol·licitud i la resposta, pot proporcionar informació sobre l'estat de la sol·licitud, etc...

Dades o Body content
Les sol·licituds de la API REST poden incloure dades perquè els mètodes POST, PUT i altres funcionin de forma correcta

Paràmetres
Les sol·licituds a la API RESTful poden incloure paràmetres que donin al servidor més detalls sobre el que han de fer, tipus d'ordenació, paràmetres d'una consulta...

Amunt