Com crear una API REST: disseny, seguretat i desplegament

Per crear una API REST, fes una llista dels recursos que gestiona la teva aplicació (usuaris, comandes, reserves), dona a cadascun una URL com /orders i /orders/{id}, i fes servir els mètodes HTTP per a les accions: GET per llegir, POST per crear, PATCH per actualitzar, DELETE per eliminar. Retorna JSON amb codis d'estat significatius, valida cada entrada, exigeix autenticació i comprovacions de permisos per registre al servidor, i pagina les llistes. Després documenta els endpoints i desplega l'API darrere d'HTTPS.

Aquesta guia cobreix les decisions de disseny, un conjunt de rutes treballat, prompts per a un constructor d'aplicacions amb IA i els errors que causen forats de seguretat. Si les API són noves per a tu, comença per què és una API.

Quan necessites una API REST

• El teu frontend web ha de desar i carregar dades d'un servidor
• Una aplicació mòbil, un soci o una eina d'automatització necessita accedir a les teves dades
• Altres serveis t'envien esdeveniments (webhooks)
• Repartiu la feina entre un equip de frontend i un de backend

REST és l'estil més comú, però no l'únic. REST vs GraphQL explica quan encaixa millor un endpoint de consulta flexible.

Disseny primer: recursos i rutes

Escriu els noms que fa servir la teva aplicació i què hi fa la gent amb ells. Per a una aplicació simple de reserves:

Aquestes rutes corresponen a crear, llegir, actualitzar i eliminar; vegeu què és CRUD. Convencions que val la pena seguir:

• Noms en plural i sense verbs a les URL: /bookings, no /getBookings.
• Només un nivell d'anidament quan aclareix la propietat: /bookings/{id}/notes.
• Accions que no són CRUD poden ser subrecursos: POST /bookings/{id}/cancel és més clar que un PATCH amb camps màgics.
• Noms coherents per als camps, com created_at a tot arreu.

Codis d'estat i errors

Fes servir els codis HTTP estàndard perquè els clients sàpiguen què ha passat sense analitzar text:

Retorna els errors en una única forma JSON coherent, per exemple {"error": {"code": "slot_taken", "message": "Aquesta hora ja no està disponible."}}, i mai no incloguis traces de pila ni errors de la base de dades a les respostes.

Opcions i compromisos

Pas a pas

1. Llista els recursos i les rutes tal com s'ha dit, incloent qui pot fer cada crida.
2. Modela les dades a la teva base de dades amb els camps i les relacions que necessites.
3. Construeix primer les rutes de lectura, després les de crear, actualitzar i eliminar.
4. Valida l'entrada a cada escriptura amb una biblioteca d'esquemes: camps obligatoris, tipus, longituds, valors permesos. Rebutja els camps desconeguts.
5. Afegeix autenticació, i després autorització per registre: carregar /bookings/42 ha de comprovar que la reserva 42 pertany a qui fa la crida, no només que algú ha iniciat sessió.
6. Pagina cada llista i limita la mida de la pàgina.
7. Limita la velocitat del login i de les rutes costoses. Vegeu límits de peticions.
8. Configura CORS només si navegadors d'altres dominis han de cridar l'API, i enumera aquests orígens explícitament. Com solucionar errors de CORS explica els errors que veuràs.
9. Escriu documentació i proves per a cada ruta, incloent-hi els casos d'error.
10. Desplega amb els secrets en variables d'entorn, HTTPS, registres i una comprovació de salut.

Prompts per al teu constructor amb IA

Scaffold:

Crea una API REST per a reserves amb aquestes rutes: GET /api/health, GET /api/bookings (paginada, màxim 50 per pàgina), POST /api/bookings, GET /api/bookings/:id, PATCH /api/bookings/:id, DELETE /api/bookings/:id. Guarda les dades a la nostra base de dades. Valida els cossos de les peticions amb una biblioteca d'esquemes i rebutja els camps desconeguts. Retorna els errors en JSON com {"error": {"code", "message"}} amb els codis HTTP correctes (400, 401, 403, 404, 409). Guarda els secrets en variables d'entorn.

Seguretat:

Exigeix inici de sessió a totes les rutes de reserves. A cada lectura, actualització i eliminació, comprova al servidor que la reserva pertany a l'usuari actual; si no hi pertany, retorna 404. Mai no acceptis IDs d'usuari ni rols del cos de la petició. Limita POST /api/bookings a 20 per minut per usuari. Registra els errors al servidor sense retornar traces de pila.

Documentació:

Escriu una descripció OpenAPI d'aquestes rutes, i un README breu amb exemples de peticions i respostes per a cadascuna.

Provar la teva API

Prova-la des de fora del frontend, perquè els atacants ho faran:

• Cada ruta funciona amb entrada vàlida i retorna la forma i el codi documentats
• Els camps que falten o no són vàlids retornen 400 amb un missatge clar
• Sense token retorna 401 a cada ruta protegida
• L'usuari A que demana el registre de l'usuari B pel seu ID obté 404 o 403
• Les llistes estan paginades; un limit enorme es limita
• Les creacions duplicades o en conflicte retornen 409, no 500
• Els límits de peticions retornen 429
• Les respostes d'error no contenen traces de pila, SQL ni secrets
• CORS només permet els orígens que tu vols

Errors habituals

• Comprovar l'inici de sessió però no la propietat. És el forat més habitual en les API: qualsevol usuari amb sessió pot llegir qualsevol registre canviant l'ID.
• Confiar en el client. Els preus, els rols i els IDs d'usuari del cos de la petició es poden editar.
• Retornar files completes de la base de dades. Els hashes de contrasenyes i els camps interns es filtren. Tria què inclou cada resposta.
• Llistes sense límit. Una única petició per a tots els registres pot alentir tota l'aplicació.
• 200 OK amb un missatge d'error dins. Els clients i el monitoratge no poden saber que ha fallat.
• CORS configurat per permetre-ho tot en una API que usa cookies.
• Sense comprovació de salut ni registres, així que t'assabentes de les caigudes pels usuaris.

Per a una revisió més àmplia abans del llançament, consulta la llista de comprovació de seguretat per a aplicacions construïdes amb IA.

Construir una API REST a Mythex

Pots demanar a Mythex una API com a part de la teva aplicació o com a servei propi. La recepta de documentació backend d'API REST té un prompt inicial: indica el teu framework i les rutes, demana errors JSON clars, guarda els secrets en variables d'entorn i inclou un Dockerfile. Els backends en contenidor en Node, Python, C#, Java i altres es publiquen amb un Dockerfile, i Mythex gestiona el desplegament des de Publicar (backends d'API). Un projecte pot tenir un lloc web i un servidor d'API un al costat de l'altre, i pots canviar entre tots dos a la previsualització. Guarda les claus com a secrets del projecte, i si l'API necessita una base de dades, demana-la al xat. Per a tasques programades al voltant de la teva API, consulta com executar tasques en segon pla.

Preguntes