El Projecte | Sobre nosaltres | Contribuir | Donacions | Llicència

HOME

En aquest tema, explorarem les millors pràctiques per dissenyar APIs RESTful robustes, escalables i fàcils d'utilitzar. Seguir aquestes pràctiques ajudarà a garantir que la teva API sigui coherent, segura i fàcil de mantenir.

Disseny Centrat en Recursos

Definició de Recursos

Recursos: Elements clau que la teva API exposa, com ara usuaris, productes o comandes.
URIs: Utilitza URIs clares i descriptives per identificar recursos. Per exemple, /usuaris, /productes, /comandes.

Exemples de Disseny de Recursos

GET /usuaris
GET /usuaris/{id}
POST /usuaris
PUT /usuaris/{id}
DELETE /usuaris/{id}

Ús Adequat dels Mètodes HTTP

Mètodes HTTP Comuns

GET: Recuperar informació.
POST: Crear un nou recurs.
PUT: Actualitzar un recurs existent.
DELETE: Eliminar un recurs.

Exemples de Mètodes HTTP

GET /productes
POST /productes
PUT /productes/{id}
DELETE /productes/{id}

Ús de Codis d'Estat HTTP

Codis d'Estat Comuns

200 OK: Sol·licitud exitosa.
201 Created: Nou recurs creat.
204 No Content: Sol·licitud exitosa sense contingut.
400 Bad Request: Sol·licitud invàlida.
401 Unauthorized: Autenticació requerida.
404 Not Found: Recurs no trobat.
500 Internal Server Error: Error del servidor.

Exemples de Respostes HTTP

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "nom": "Producte A",
  "preu": 100
}

Consistència en els Noms i Estructura

Noms Coherents

Utilitza noms coherents i descriptius per a recursos i camps.
Evita abreviatures i noms ambigus.

Estructura Consistent

Mantén una estructura consistent en totes les rutes de la teva API.
Utilitza convencions de nomenclatura com snake_case o camelCase de manera consistent.

Documentació Clara i Completa

Importància de la Documentació

Proporciona documentació detallada per a cada endpoint de la teva API.
Inclou exemples de sol·licituds i respostes.

Eines de Documentació

Swagger: Eina popular per a la documentació d'APIs.
Postman: Eina per provar i documentar APIs.

Versionat de l'API

Necessitat de Versionat

Permet introduir canvis sense trencar la compatibilitat amb versions anteriors.
Utilitza versionat en les URIs o en els encapçalaments.

Exemples de Versionat

GET /v1/usuaris
GET /v2/usuaris

Gestió d'Errors

Respostes d'Error

Proporciona missatges d'error clars i descriptius.
Inclou informació sobre com resoldre l'error.

Exemples de Respostes d'Error

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Invalid request",
  "message": "The 'email' field is required."
}

Autenticació i Autorització

Mètodes d'Autenticació

Token-Based: Utilitza tokens JWT per a l'autenticació.
OAuth: Utilitza OAuth per a l'autorització.

Exemples d'Autenticació

POST /login
Content-Type: application/json

{
  "username": "usuari",
  "password": "contrasenya"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Rate Limiting i Throttling

Importància del Rate Limiting

Protegeix la teva API contra abusos i sobrecàrregues.
Defineix límits de sol·licituds per usuari o IP.

Implementació de Rate Limiting

Utilitza encapçalaments HTTP per informar els usuaris dels límits i l'estat actual.

Exemples d'Encapçalaments de Rate Limiting

X-Rate-Limit-Limit: 1000
X-Rate-Limit-Remaining: 500
X-Rate-Limit-Reset: 3600

CORS i Polítiques de Seguretat

Configuració de CORS

Permet sol·licituds creuades des de dominis de confiança.
Configura encapçalaments CORS adequats.

Exemples de Configuració de CORS

Access-Control-Allow-Origin: https://exemple.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization

Conclusió

Seguir aquestes bones pràctiques en el disseny d'APIs RESTful ajudarà a crear APIs més robustes, segures i fàcils d'utilitzar. Recorda que la clau és mantenir la coherència, proporcionar documentació clara i gestionar adequadament la seguretat i els errors. Amb aquestes pràctiques, estaràs ben encaminat per desenvolupar APIs que siguin apreciades pels desenvolupadors i usuaris finals.

Bones pràctiques en el disseny d'APIs