Scribd
Cargar
19 vistas7 páginas

Guía General para API

La guía proporciona recomendaciones para el diseño y desarrollo de APIs, incluyendo elegir un enfoque como REST o GraphQL, usar nombres descriptivos y coherentes, implementar versionamiento, documentación, uso correcto de HTTP methods, manejo de errores, autenticación, y realizar pruebas.

Cargado por

Booksfree21
Derechos de autor
© © All Rights Reserved
Nos tomamos en serio los derechos de los contenidos. Si sospechas que se trata de tu contenido, reclámalo aquí.
Formatos disponibles
Descarga como PDF, TXT o lee en línea desde Scribd
19 vistas7 páginas

Guía General para API

La guía proporciona recomendaciones para el diseño y desarrollo de APIs, incluyendo elegir un enfoque como REST o GraphQL, usar nombres descriptivos y coherentes, implementar versionamiento, documentación, uso correcto de HTTP methods, manejo de errores, autenticación, y realizar pruebas.

Cargado por

Booksfree21
Derechos de autor
© © All Rights Reserved
Nos tomamos en serio los derechos de los contenidos. Si sospechas que se trata de tu contenido, reclámalo aquí.
Formatos disponibles
Descarga como PDF, TXT o lee en línea desde Scribd
Está en la página 1/ 7

Guía básica para

API

Axel A.V
Contenido

Elegir un enfoque ............................................................................................................ 3


Usar nombres de recursos y endpoints que sean descriptivos y coherentes. .......... 4
Versionamiento ................................................................................................................ 5
Documentación exhaustiva............................................................................................. 5
Uso consistente de métodos HTTP ............................................................................... 5
Gestión de errores adecuada ......................................................................................... 6
Autenticación y autorización .......................................................................................... 7
Pruebas exhaustivas ....................................................................................................... 7
Elegir un enfoque

Existen varios enfoques que se pueden elegir, entre ellos:

REST (Representational State Transfer):

Descripción: REST es un estilo arquitectónico que se basa en el uso de los métodos


HTTP (GET, POST, PUT, DELETE, etc.) y en la representación de recursos mediante URLs.
Se enfoca en la simplicidad y la escalabilidad.

Características clave:

❖ Uso de URIs (Uniform Resource Identifiers) para identificar recursos.


❖ Utilización de métodos HTTP para operaciones CRUD (Create, Read, Update,
Delete) en recursos.
❖ Transferencia de datos en formatos estándar como JSON o XML.
❖ Stateless: Cada solicitud de cliente debe contener toda la información necesaria
para comprenderla.
❖ Uso de códigos de estado HTTP para indicar el resultado de una solicitud.

GraphQL:

Descripción: GraphQL es un lenguaje de consulta para APIs que permite a los clientes
solicitar solo los datos que necesitan. A diferencia de REST, donde el servidor define la
estructura de respuesta, en GraphQL, el cliente especifica qué datos desea.

Características clave:

❖ Permite a los clientes definir su estructura de respuesta.


❖ Evita el problema de "sobre o infraconsulta" de datos.
❖ Un solo punto de entrada para consultas.
❖ Tipos de datos definidos por el esquema GraphQL.
SOAP (Simple Object Access Protocol):

Descripción: SOAP es un protocolo de comunicación que define una estructura XML para
el intercambio de mensajes entre aplicaciones a través de HTTP, SMTP y otros protocolos.
A menudo se utiliza en servicios web basados en estándares.

Características clave:

❖ Utiliza un formato XML estructurado para mensajes.


❖ Ofrece soporte para seguridad y transacciones.
❖ Define un contrato formal de servicio mediante documentos WSDL (Web Services
Description Language).
❖ Es más rígido y pesado en comparación con REST.

Usar nombres de recursos y endpoints que sean descriptivos


y coherentes.

• Seguir una convención de nomenclatura: Utiliza una convención de nomenclatura


coherente en toda la API. Por ejemplo, puedes optar por nombres en minúsculas
separados por guiones bajos (snake_case) o en formato CamelCase. Lo más
importante es ser coherente en todo el conjunto de la API.

• Utiliza sustantivos para los recursos: Los nombres de recursos deben ser
sustantivos que representen claramente los datos o las entidades que se están
manipulando. Por ejemplo, si estás construyendo una API para gestionar usuarios,
el recurso principal podría llamarse "usuarios".

• Evita verbos en los nombres de los endpoints: Los verbos no deben formar parte
de los nombres de los endpoints. En lugar de usar nombres como /obtener_usuario
o /crear_usuario, utiliza rutas como /usuarios para obtener una lista de usuarios y
/usuarios (POST) para crear uno nuevo.
• Usa plurales para las colecciones: Cuando se trata de colecciones de recursos
(por ejemplo, una lista de usuarios o productos), usa nombres en plural para las rutas.
Por ejemplo, /usuarios en lugar de /usuario.

• Incluye subrecursos para relaciones complejas: Si tienes relaciones complejas


entre recursos, puedes utilizar subrecursos para representarlas de manera más clara.
Por ejemplo, si tienes usuarios y cada usuario tiene un conjunto de publicaciones,
puedes usar /usuarios/{id}/publicaciones para acceder a las publicaciones de un
usuario específico.

• Evita acrónimos y abreviaciones ambiguas: Siempre es mejor evitar acrónimos y


abreviaciones que puedan ser ambiguos o confusos. Si decides utilizar acrónimos,
asegúrate de que sean ampliamente reconocidos y comprendidos en tu industria.

• Sé descriptivo en los parámetros de consulta: Si utilizas parámetros de consulta


en tus endpoints, dales nombres descriptivos. Por ejemplo,
/productos?categoria=electronicos es más claro que /productos?cat=elec.

Versionamiento
Incluir una versión en la URL de la API para garantizar la compatibilidad hacia el futuro
(por ejemplo, /v1/resource).

Documentación exhaustiva
Proporciona documentación clara y detallada que explique cómo usar la API, qué
endpoints están disponibles y qué se espera de cada uno.

Uso consistente de métodos HTTP


Utiliza los métodos HTTP (GET, POST, PUT, DELETE, etc.) de manera coherente y
semántica. Por ejemplo, usa GET para recuperar datos, POST para crear, PUT para
actualizar y DELETE para eliminar.
Definir formato para las peticiones y respuestas

Es necesario definir un formato de petición y respuesta coherente, puede ser JSON o


XML.

Gestión de errores adecuada


➢ Proporcionar códigos de estado HTTP adecuados y mensajes de error claros en
caso de problemas. Utilizar un esquema consistente para los errores. Los códigos
de estado HTTP para las respuestas:
GET:
200 OK: La solicitud fue exitosa y se devolvió la información
solicitada.
404 Not Found: El recurso solicitado no fue encontrado en el
servidor.

POST:

201 Created: La solicitud fue exitosa y se creó un nuevo recurso.


400 Bad Request: La solicitud no pudo ser procesada debido a un
error en la sintaxis o contenido de la solicitud.
409 Conflict: La solicitud no pudo ser completada debido a un
conflicto con el estado actual del recurso.

PUT (Actualizar completamente un recurso):


200 OK: La solicitud fue exitosa y se actualizó el recurso.
204 No Content: La solicitud fue exitosa, pero no hay contenido para
devolver.

DELETE:
200 OK: La solicitud fue exitosa y el recurso fue eliminado
correctamente.
204 No Content: La solicitud fue exitosa, pero no hay contenido para
devolver.
404 Not Found: El recurso a eliminar no fue encontrado en el
servidor.
Autenticación y autorización
Implementa una capa de seguridad sólida, como OAuth, para proteger la API. Garantiza que
los usuarios tengan el acceso adecuado a los recursos. Otra alternativa es utilizar JSON
Web Tokens (JWT) los cuales son tokens seguros y autenticados que se pueden utilizar para
la autorización y autenticación en una API. Puedes emitir y verificar JWT en tu API utilizando
bibliotecas JWT específicas para tu lenguaje de programación.

Sobre cómo utilizar JWT en PHP (Laravel): https://jwt-auth.readthedocs.io/en/develop/


Sobre cómo utilizar JWT en .NET: https://github.com/jwt-dotnet/jwt
Sobre cómo utilizar JWT en Java: https://github.com/auth0/java-jwt

Pruebas exhaustivas
Realiza pruebas exhaustivas de la API para garantizar su funcionamiento correcto y su
rendimiento bajo carga. Se puede hacer uso de Postman o alguna otra herramienta.

También podría gustarte