Què és i com fer una API REST

RESTful APIs

Abans de res, necessitem entendre i saber exactament que es considera una API REST. REST vol dir REpresentational State Transfer i traduït sería algo com "Transferència d'estat representacional". Més clar? Potser no... 😅

REST es una arquitectura de software per a sistemes distribuïts com és la web, centrada en la transferència de dades i ens serveix per a connectar o comunicar diferents sistemes basats en el protocol HTTP.

En resum, REST ens serveix com deiem anteriorment, per a obtenir i generar dades, tornant aquestes en formats específics com el XML o el JSON.

I què és una API?

Doncs una API o Interfície de Programació d'Aplicacions, és un conjunt de definicions i de protocols que es fan servir per a desenvolupar i integrar el programari de les aplicacions.

Les APIs ens permeten comunicar els nostres productes i/o serveis entre ells, sense saber com s'han desenvolupat internament, oferint una capa de connexió flexible amb la que es comunicaràn entre elles amb contractes pre-establerts.

Podríem dir que aquests contractes dels que parlem son el resultat d'aquestes definicions XML o JSON que el REST ens defineix.

Utilitzant el protocol HTTP i els seus verbs

A les APIs REST o RESTful APIs, s'utilitzen els verbs d'HTTP com a accions, i els endpoints són els recursos sobre els cuals actuem. Utilitzarem els diferents verbs d'HTTP segons el seu significat semàntic:

• GET: Recupera recursos
• POST: Crea recursos
• PUT: Actualitza o crea recursos
• DELETE: Elimina recursos

Aquests són els 4 pilars bàsics d'una API REST, i amb aquests 4 verbs hem de ser prou capaços de desenvolupar tot el necessari.

Ús dels verbs HTTP

GET /noticies
Aquest endpoint ens hauría de retornar una llista de notícies. I més endavant, veurem les recomanacions per retornar llistats llargs. Però per exemple hauríem de poder veure una resposta, en el cas de JSON com la següent:

{
    "titol": "Títol de la primera noticia",
    "contingut": "Cos o contingut de la notícia",
    "autor": "Oriol"
},
{
    "titol": "Títol de la segona noticia",
    "contingut": "Cos o contingut de la segona notícia",
    "autor": "Fernando"
}

GET /noticia/32
Aquest endpoint, per exemple, ens tornaría la notícia amb el ID 32. Ens retornaría un recurs únic o un sol registre. Similar als d'abans mostrats, però únicament un amb més o menys informació segons necesitem:

{
    "titol": "Títol de la notícia 32",
    "contingut": "Cos o contingut de la notícia",
    "autor": "Oriol"
}

POST /noticia
Amb aquest endpoint el que aconseguirem es enviar mitjançant el protocol POST les dades necessàries per crear un recurs a la nostra API. Normalment l'enviament d'aquestes dades ha de complir un contracte previament acordat. En aquest cas, el contracte mantindrà la mateixa estructura que pel mètode GET, que es el títol, contingut i autor de la notícia. Així doncs el cos o body d'aquest missatge sería el següent:

{
    "titol": "Títol de la nova notícia",
    "contingut": "Cos o contingut de la notícia",
    "autor": "Oriol"
}

PUT /noticia/32
Aquest mètode serveix principalment per actualitzar un recurs existent i, de forma voluntaria podrem fer que si aquest no existeix, tembé el crei. La diferència amb el POST es que PUT hauría de ser exclusivament per actualitzar un recurs i POST per crear-lo. Però més endavant repassarem i profunditzarem en aquestes qüestions.

DELETE /noticia/32
El mètode delete, com obviament pensareu, serveix per eliminar un recurs de la nostra API. Aquest mètode no té per que tenir cos, pot tenir-lo o no, però no es necessari. Si que necessitarem indicar d'alguna forma el recurs que volem esborrar, en aquest cas, li indiquem el ID 32.

Veient que això se'ns allarga i se'ns allargarà, farem varies publicacions per continuar les característiques de les API. Esperem que us sigui d'utilitat! 🙋‍♂️