¿API? Todo lo que debes saber

Photo by Christopher Gower on Unsplash

Motivado por un futuro proyecto en el que participaré, quise realizar una investigación sobre todos los temas relacionados en el diseño y construcción de un API. Este compilado reúne variedad de autores y distintos tipos de fuentes, empezando por blogs hasta artículos de publicación científica. Recuerda que esto es un resumen y el contenido pertenece a cada autor consultado, el trabajo principal consistió en una agrupación de los temas más relevantes en un solo post.

1. ¿Qué es una API?

Una API (interfaz de programación de aplicaciones) es un conjunto de códigos de programación que permiten la transmisión de datos entre un producto de software y otro.

Las interfaces de programación de aplicaciones constan de dos componentes:

• Especificación técnica que describe las opciones de intercambio de datos entre soluciones con la especificación realizada en forma de una solicitud de protocolos de procesamiento y entrega de datos
• Interfaz de software escrita según la especificación que la representa.

Los especialistas de Red Hat señalan que las API a veces se consideran contratos, donde la documentación es un acuerdo entre las partes: “Si la parte envía primero una solicitud remota estructurada de una manera particular, así es como responderá el software de la segunda parte”. La documentación de la API es un manual para desarrolladores que incluye toda la información necesaria sobre cómo trabajar con la API y utilizar los servicios que proporciona.

Cada API contiene y se implementa mediante llamadas a funciones: declaraciones de lenguaje que solicitan al software que realice acciones y servicios particulares. Las llamadas a funciones son frases compuestas por verbos y sustantivos, por ejemplo:

• Iniciar o finalizar una sesión
• Restaurar o recuperar objetos de un servidor

Las llamadas a funciones se describen en la documentación de la API.

2. Tipos de API

En términos de políticas de lanzamiento, las API pueden ser privadas, asociadas o públicas.

• API privadas: Estas interfaces de software de aplicación están diseñadas para mejorar las soluciones y los servicios dentro de una organización. Los desarrolladores o contratistas internos pueden utilizar estas API para integrar los sistemas o aplicaciones de TI de una empresa, crear nuevos sistemas o aplicaciones orientadas al cliente aprovechando los sistemas existentes. La estrategia privada permite a una empresa controlar completamente el uso de la API.
• API de socios: Las API de socios se promocionan abiertamente, pero se comparten con socios comerciales que han firmado un acuerdo con el editor. El caso de uso común de las API de socios es la integración de software entre dos partes. Una empresa que otorga a sus socios acceso a datos o capacidades se beneficia de fuentes de ingresos adicionales. Al mismo tiempo, puede monitorear cómo se utilizan los activos digitales expuestos, garantizar si las soluciones de terceros que utilizan sus API brindan una experiencia de usuario decente y mantener la identidad corporativa en sus aplicaciones.
• API públicas: También conocidas como orientadas al desarrollador o externas, estas API están disponibles para desarrolladores externos. Un programa de API público permite aumentar el conocimiento de la marca y recibir una fuente adicional de ingresos cuando se ejecuta correctamente. Hay dos tipos de API públicas:
• Abiertas (gratuitas): La definición de API abierta sugiere que todas las funciones de dicha API son públicas y se pueden utilizar sin términos y condiciones restrictivos. Por ejemplo, es posible crear una aplicación que utilice la API sin la aprobación explícita del proveedor de API o tarifas de licencia obligatorias. La definición también establece que la descripción de la API y cualquier documentación relacionada deben estar disponibles abiertamente, y que la API se puede utilizar libremente para crear y probar aplicaciones.
• Comerciales: Los usuarios de API comerciales pagan tarifas de suscripción o utilizan las API con un sistema de pago por uso. Un enfoque popular entre los editores es ofrecer pruebas gratuitas, para que los usuarios puedan evaluar las API antes de comprar suscripciones.

Las API también se pueden clasificar según los sistemas para los cuales fueron diseñadas (API por casos de uso), en ese caso se puede hablar de:

• API de bases de datos: Las API de bases de datos permiten la comunicación entre una aplicación y un sistema de gestión de bases de datos. Los desarrolladores trabajan con bases de datos escribiendo consultas para acceder a datos, cambiar tablas, etc.
• API de sistemas operativos: Este grupo de API define cómo las aplicaciones utilizan los recursos y servicios de los sistemas operativos. Cada sistema operativo tiene su conjunto de API, por ejemplo, API de Windows o API de Linux.
• API remotas: Las API remotas definen estándares de interacción para aplicaciones que se ejecutan en diferentes máquinas. En otras palabras, un producto de software accede a recursos ubicados fuera del dispositivo que los solicita. Dado que dos aplicaciones ubicadas remotamente están conectadas a través de una red de comunicaciones, particularmente Internet, la mayoría de las API remotas están escritas en base a estándares web.
• API web: Esta clase de API es la más común. Las API web proporcionan transferencia de funcionalidad y datos legibles por máquina entre sistemas basados en web que representan la arquitectura cliente-servidor . Estas API entregan principalmente solicitudes de aplicaciones web y respuestas de servidores que utilizan el Protocolo de transferencia de hipertexto (HTTP).

3. Especificaciones API

El objetivo de las especificaciones API es estandarizar el intercambio de datos entre servicios web. En este caso, la estandarización significa la capacidad de diversos sistemas, escritos en diferentes lenguajes de programación y/o que se ejecutan en diferentes sistemas operativos, o que utilizan diferentes tecnologías, para comunicarse sin problemas entre sí.

• Llamada a procedimiento remoto (RPC)
• Protocolo de acceso a objetos de servicio (SOAP)
• Transferencia de estado representacional (REST)
• gRPC
• GraphQL

4. Diseño e implementación de un API

La simplicidad del diseño de la API depende del contexto. Un diseño en particular puede resultar simple para un caso práctico, pero muy complejo para otro, por lo que se debe equilibrar el nivel de detalle de los métodos de la API. Resulta útil pensar en la simplicidad en varios niveles, entre los que se incluyen los siguientes:

• Formato de datos: compatibilidad con los formatos propietarios, XML, JSON, o una combinación de ellos.
• Estructura del método: los métodos pueden ser muy genéricos y proporcionar un conjunto amplio de datos, o muy acotados para permitir solicitudes específicas. También se suelen adoptar en una determinada secuencia para abordar ciertos casos prácticos.
• Modelo de datos: el modelo de datos subyacente puede ser muy similar o muy diferente a lo que realmente se expone a través de la API. Esto tiene una repercusión en las capacidades de uso y de mantenimiento.
• Autenticación: los diversos mecanismos de autenticación tienen diferentes ventajas y desventajas. La elección del más adecuado dependerá del contexto.
• Políticas de uso: es preciso que sea sencillo trabajar con los derechos y las cuotas para los desarrolladores, los que a su vez deben ser fáciles de comprender.

Preguntas importantes que debe considerar

Para analizar detenidamente el diseño de su API, tenga en cuenta las siguientes cinco preguntas:

1. ¿Diseñamos la API para respaldar nuestros casos prácticos? El siguiente paso luego de identificar los principales casos prácticos es diseñar la API de modo que los respalde. La flexibilidad es importante para no excluir ningún caso práctico que sea menos frecuente, pero que se deba abordar para permitir la innovación.
2. ¿Implementamos las API de RESTful solo porque sí? Las API de RESTful están de moda en la actualidad, pero no se debería seguir esta tendencia solo por eso. Aunque se ajustan muy bien a ciertos casos prácticos, hay algunos estilos de arquitectura, como GraphQL, que resultan mejores para otros.
3. ¿Expusimos nuestro modelo de datos sin pensar en los casos prácticos? Las API deberían contar con el respaldo de una capa que se extraiga de su modelo de datos real. Como regla general, no implemente una API que se dirija directamente a su base de datos (aunque sí podría ser necesario en algunos casos).
4. ¿Qué regiones geográficas son las más importantes? ¿Hemos planificado nuestros centros de datos en función de ellas? El diseño de la API también debe abarcar elementos no funcionales, como la latencia y la disponibilidad. Asegúrese de elegir centros de datos cuya ubicación geográfica sea cercana a la mayoría de sus usuarios.
5. ¿Sincronizamos el diseño de la API con el resto de nuestros productos? Si la API no es el único producto de su empresa, asegúrese de que su diseño esté coordinado con el del resto de los productos. Es posible que decida separar el diseño de la API de los otros productos por completo. Incluso en ese caso, será necesario comunicar con claridad este plan de forma interna y externa.

¿Cómo diseñar un API?

a. Elementos básicos para un API

Un esquema de autenticación

• Autenticación básica HTTP
• JSON Web Token (JWT)
• OAuth

Definiciones del tipo de llamada HTTP

• GET: Normalmente utilizado para recuperar una representación de un recurso
• POST: Método para enviar una entidad al recurso, por lo general, resulta en un cambio de estado.
• PUT: Es esencialmente un método para actualizar o reemplazar una entrada.
• PATCH: Se usa para actualizar o modificar una entrada, PATCH estará igualmente limitado como PUT, aunque en algunas implementaciones podría usarse para modificar entradas específicas que son únicas para el usuario; en este caso, la documentación sobre cómo se hace debe diferenciar entre los dos.
• DELETE: Se usa específicamente para eliminar una entrada

Definiciones de puntos finales: La primera forma en que podemos comenzar a agregar valor a esta definición de punto final es explicar específicamente qué hace y cómo se relaciona con otros puntos finales.

Estructuras, métodos y parámetros de URI: Para agregar más valor a esta definición de punto final, debemos documentar la estructura y los métodos para cada URI dentro de la API. Esto debería hacerse a un nivel tan profundo que el usuario medio debería tener todas las funciones a su disposición descritas, en detalle, para facilitar su uso.

Descripciones de métodos legibles por humanos: La idea de incluir descripciones legibles por humanos es menos un punto técnico y más centrado en el ser humano

Solicitudes y ejemplos

Respuestas esperadas

b. Mejores prácticas para el desarrollo de un API

Modelado de recursos: Las API REST pueden administrar diferentes tipos de recursos: documentos para instancias únicas de recursos, colecciones para grupos de recursos y controladores para acciones que no se pueden asignar lógicamente a los métodos HTTP estándar. Si bien el modelado de recursos para las API REST no es fundamentalmente diferente de las clases de modelado en la programación OO o las entidades en el modelado de datos, hay un par de prácticas de nomenclatura recomendadas que son típicas de las API REST: sustantivos singulares para documentos, sustantivos plurales para colecciones y solo verbos para controladores, no hay nombres CRUD en las URL, no hay transparencia de las tecnologías de implementación del lado del servidor (por ejemplo, PHP, JSP)

Identificación de recursos: Los identificadores de recursos deben ajustarse al formato de URI, que consiste en un esquema, autoridad, ruta, consulta y fragmento. En el caso de las API REST accesibles a través de la web, los URI suelen ser URL (localizadores uniformes de recursos) que les indican a los clientes cómo ubicar las API. Para mejorar la legibilidad de las URL, se recomienda utilizar guiones en lugar de guiones bajos, letras minúsculas en las rutas, “api” como parte del dominio y evitar la barra diagonal al final. Además, en su forma más pura, los servicios REST deben evitar declarar versiones de API en la URL.

Representación de recursos: Los recursos pueden admitir representaciones alternativas (por ejemplo, XML, JSON) y servir a diferentes clientes con diferentes formatos. La representación que se debe servir debe negociarse en tiempo de ejecución, y el cliente debe expresar su representación deseada mediante la instrucción de encabezado HTTP Accept . Esto fomenta la reutilización, la interoperabilidad y el acoplamiento flexible. Por lo tanto, las API deben utilizar la negociación de contenido en lugar de extensiones de archivo para especificar formatos (por ejemplo, .json o .xml ). Además, se recomienda que las API admitan JSON (válido) entre sus alternativas de representación.

Operaciones: Para administrar los recursos, las API REST deben basarse en el conjunto uniforme de operaciones (Post, Get, Put, Delete, Options, Head)

• Post, debe usarse para crear nuevos recursos dentro de una colección.
• Get, debe usarse para recuperar una representación de un recurso.
• Put, debe usarse para actualizar o crear recursos.
• Delete, debe usarse para eliminar un recurso.
• Opciones, debe usarse para recuperar las interacciones disponibles de un recurso.
• Head, debe usarse para recuperar metadatos del estado actual de un recurso.

c. Recomendaciones generales para el diseño de un API

Usar sustantivos en los nombres de los recursos

Al nombrar los recursos de la API REST, use sustantivos y evite los verbos.

Por ejemplo:

• /postspara el recurso que devuelve una colección de publicaciones de blog,
• /mepara el recurso que devuelve la información sobre el usuario actual.

Evite los recursos profundamente anidados

A veces, los recursos deben estar anidados. Por ejemplo, un recurso anidado que representa comentarios de publicaciones de blog podría ser /posts/r83fj3/comments. Cuando se trabaja con recursos anidados, es mejor evitar anidaciones profundas. Dos niveles como en el ejemplo son suficientes en la mayoría de los escenarios.

Utilice ID de recursos no secuenciales

Es mejor usar identificadores no secuenciales (tal vez aleatorios) con recursos. Eso protegerá sus datos de los ataques de enumeración y también simplificará cosas como la combinación de conjuntos de datos si descubre que dos de sus recursos deben convertirse en uno mientras se conservan los identificadores de las entidades. Los UUID o cadenas aleatorias son lo suficientemente buenos. Por ejemplo /posts/r83fj3,

Represente acciones CRUD con verbos HTTP apropiados

Un recurso de API REST típico admite la operación de creación, lectura, actualización y eliminación. Echemos un vistazo a una forma canónica de respaldar el uso del /postsrecurso para administrar publicaciones de blog.

Un desarrollador debe usar estas solicitudes HTTP para esas operaciones:

• POST example.com/posts/para crear una nueva publicación de blog
• GET example.com/posts/r83fj3 para obtener una publicación de blog por su identificación
• PATCH example.com/posts/r83fj3para actualizar las propiedades especificadas de una publicación de blog por su identificación
• PUT example.com/posts/r83fj3 para reemplazar una publicación de blog por su identificación
• DELETE example.com/posts/r83fj3para eliminar una publicación de blog por su identificación

Evite acciones personalizadas (no CRUD)

Es posible que algunos recursos deban admitir acciones que no se asignan bien a los verbos HTTP. Por ejemplo, es posible que sea necesario publicar y anular una publicación de blog .

Un enfoque popular pero no RESTful sería utilizar URL como:

• POST /posts/d92hf73/publish
• POST/posts/d92hf73/unpublish

Esto va en contra de los principios REST porque /posts/d92hf73/publishno es una URL para un recurso. Veamos algunas formas de agregar soporte para publicar y anular la publicación de publicaciones de blog de una manera RESTful.

Un enfoque RESTful, pero no particularmente elegante, es usar PATCHsolicitudes como esta:

PATCH example.com/posts/d92hf73con parámetros como { “status”: “published” }o { “status”: “unpublished” }.

Otro enfoque es introducir un recurso anidado y llamarlo commandso actions, entonces la solicitud se vería así:

POST example.com/posts/d92hf73/commands { “name”: “publish” }

POST example.com/posts/d92hf73/commands { “name”: “unpublish” }

Este es un enfoque más RESTful y también mucho más ampliable, ya que permite agregar más URL a la API sin cambiar su interfaz.

El tercer enfoque consiste en introducir un recurso anidado que represente el concepto de “publicación”, como la palabra “publication" para este ejemplo.

• POST example.com/posts/d92hf73/publicationpara publicar una entrada de blog mediante la creación de una publicación.
• DELETE example.com/posts/d92hf73/publicationpara anular la publicación de una publicación de blog eliminando una publicación.

Use los verbos HTTP correctamente

Según los principios REST, el significado de una solicitud debe representarse con verbos HTTP. Veamos su significado y qué acciones expresan:

• POST example.com/postscrea un nuevo recurso
• GET example.com/posts/d92hf73recupera el recurso
• PATCH example.com/posts/d92hf73 actualiza las propiedades especificadas del recurso
• PUT example.com/posts/d92hf73 reemplaza el recurso
• DELETE example.com/posts/d92hf73elimina el recurso
• GET example.com/postsrecupera una colección de recursos

Las solicitudes GET deben ser idempotentes y nunca deben cambiar el estado del recurso. Además, también deben poder almacenarse en caché para obtener el mejor rendimiento de la API. PUTy las DELETEsolicitudes también deben ser idempotentes. POSTy PATCHno son idempotentes: cambian el estado del recurso.

Considere usar el encabezado ETag

Al realizar solicitudes UPDATE a una API, existe la posibilidad de que el recurso ya se haya modificado y la solicitud PUTo PATCHpueda sobrescribirlo.

Hay una forma de captar ese caso con el encabezadoETag. El encabezado HTTP de respuesta es un identificador para una versión específica de un recurso. El valor de este encabezado se calcula en el lado del servidor para la respuesta y puede ser un hash del recurso.

Este valor se puede enviar al servidor cuando se vuelve a cargar el mismo recurso para verificar si es necesario volver a recuperarlo o cuando este recurso se actualiza para verificar que el recurso no ha cambiado entre el momento en que se recuperó y siendo enviado de vuelta.

En el primer caso, el valor se devuelve en el If-None-Matchencabezado de la solicitud y, si ese valor es el mismo que el ETagdel recurso, la API puede responder 304 Not Modifiedcon el cuerpo vacío. Esto es útil si el recurso es costoso de construir en el servidor.

En el segundo caso, la API debe verificar si el ETagvalor sigue siendo el mismo; de lo contrario, devolverá una 412 Precondition Failedrespuesta de error. Esto permite detectar casos en los que el recurso ha sido modificado antes POSTde que otra solicitud reciba la solicitud y evita que se sobrescriban los datos.

Respuestas

Al devolver un recurso, es mejor usar una estructura JSON simple, es decir:

{
  "id": "d92hf73",
  "title": "Prácticasrecomendadaspara las API REST públicas",
  "body": "Foo bar ...",
  "createdAt": "2020-08-30 11:17:09 UTC "
}

Esta es una estructura muy simple: solo incluye atributos para describir el recurso. ¿Qué pasa si quisiéramos agregar más información a este objeto JSON?

Si está familiarizado con el componente HATEOAS de la arquitectura REST, es posible que desee incluir enlaces a entidades y comandos relacionados que se pueden ejecutar en el recurso. Digamos que podemos publicar o eliminar una publicación y que una publicación tiene comentarios y un autor.

Hay dos maneras de hacer esto:

{
  "id": "d92hf73",
  "title": "Prácticasrecomendadaspara las API REST públicas",
  "body": "Foo bar ...",
  "createdAt": "2020-08-30 11:17:09 UTC ",
  "commentsUrl ":" <https://example.com/posts/d92hf73/comments> ",
  "authorUrl ":" <https://example.com/author/f9f3ks0> ",
  "publishUrl ":" https: // ejemplo .com / posts / d92hf73 / publishing ",
  "deleteUrl ":" <https://example.com/posts/d92hf73> "
}

Otra forma es:

{
  "data": {
    "id": "d92hf73",
    "title": "Prácticasrecomendadaspara las API REST públicas",
    "body": "Foo bar ...",
    "createdAt": "2020-08-30 11 : 17: 09 UTC "
  },
  " enlaces ": {
    "commentsUrl ":" <https://example.com/posts/d92hf73/comments> ",
    "authorUrl ":" <https://example.com/author/f9f3ks0> " ,
    "publishUrl": "<https://example.com/posts/d92hf73/publication>",
    "deleteUrl": "<https://example.com/posts/d92hf73>"
  }
}

Las respuestas de la colección pueden usar un sobre para envolver los artículos de la colección. Aquí hay un ejemplo, donde las publicaciones de blog se devuelven debajo de la clave data. La clave linken este ejemplo contiene URL que apuntan a la página siguiente y anterior con publicaciones.

GET example.com/api/posts?page=2&limit=10

{
  "data": [{
    "id": "d92hf73",
    "title": "Prácticasrecomendadaspara API REST públicas"
  }, {
    "id": "hwp8a2j",
    "title": "REST vs GraphQL"
  }],
  "links": {
    "nextUrl": "d92hf73 ",
    "prevUrl": "example.com/posts"
  }
}

Las respuestas de la colección no tienen que usar un sobre. En este caso, la API puede devolver las URL de paginación en encabezados de respuesta HTTP como en este ejemplo:

GET example.com/api/posts?page=2&limit=10

[
  {
    "id": "d92hf73",
    "title": "Prácticasrecomendadaspara API REST públicas"
  },
  {
    "id": "hwp8a2j",
    "title": "REST vs GraphQL"
  }
]

Encabezado de respuesta HTTP:

Link: <https://example.com/api/posts?page=1>; rel=”prev”, <https://example.com/api/posts?page=3>; rel=”next”, <https://example.com/api/posts?page=34>; rel=”last”, <https://example.com/api/posts>; rel=”first”

Considere usar JSON: API

Si prefiere usar un estándar existente para dar formato a las respuestas en su API, entonces puede usar JSON API. Es relativamente popular y proporciona una estructura de respuesta estándar. https://jsonapi.org/

Utilice códigos de respuesta HTTP significativos con respuestas vacías

POSTEs posible que las solicitudes para crear un recurso no devuelvan contenido y, en su lugar, utilicen el 201 Createdestado HTTP y establezcan el Locationencabezado de respuesta HTTP para indicarle al cliente de la API cómo recuperar el recurso.

En algunas API POST, PATCH, PUTlas solicitudes pueden volver porque no hay datos de procesamiento de solicitudes se realiza de forma asíncrona. En este caso, la solicitud puede devolver el 202 Acceptedestado HTTP para indicar que la solicitud se ha puesto en cola para su procesamiento.

Cuando POST, PATCH, PUT, DELETEsolicitudes no semánticamente tienen que devolver cualquier respuesta, deben responder con 204 No contentHTTP de estado de respuesta.

Utilice respuestas enriquecidas de error

Las respuestas de error no solo deben representar información de error, sino también utilizar códigos de estado HTTP correctos. Si los datos enviados por el cliente API causaron un error, entonces el código debe ser uno de los códigos 4xx. Si el error fue causado por un problema en el lado del servidor, debe ser uno de los códigos 5xx.

Las respuestas de error deben contener información suficiente para describir el error para el cliente API, el desarrollador del cliente API y, en algunos casos, para el usuario del cliente API. Una respuesta de error puede verse así:

POST example.com/api/posts

{
  "errorCode": 123,
  "errorMessage": "El título de la publicación de blog es demasiado largo",
  "developerMessage": "el título no puede tener más de 255 caracteres",
  "info": "<https://docs.example.com/api/errors/123> "
}

A veces, pueden ocurrir muchos errores al manejar una solicitud de API, por ejemplo, al validar los datos enviados en el cuerpo de la solicitud POST. En ese caso, una respuesta de error puede verse así:

POST example.com/api/posts

[
  {
    "errorCode": 123,
    "errorType": "validationError",
    "errorMessage": "El título de la publicación de blog es demasiado largo",
    "developerMessage": "el título no puede tener más de 255 caracteres",
    "info": "https: //docs.example.com/api/errors/123 "
  },
  {
    " errorCode ": 123,
    " errorType ":" validationError ",
    " errorMessage ":" El cuerpo de la publicación del blog es demasiado corto ",
    " developerMessage ":" body no puede estar vacío ",
    " info ":" <https://docs.example.com/api/errors/123> "
  }
]

Los desarrolladores de API generalmente comienzan con respuestas de error como esta:

POST example.com/api/posts

Error message here.

Pero luego migran hacia { "error": "Error message here" }y luego tal vez [{ "error": "Error message here" }, { "error": "Another error message here" }]. Por lo tanto, puede ser una buena idea admitir varios errores en una respuesta desde el principio.

Control de versiones de API

Es mejor diseñar y construir la API REST de una manera que no requiera control de versiones. En otras palabras, los desarrolladores de API deben evitar romper los cambios a toda costa. Si tiene que introducir cambios importantes a gran escala, está publicando una nueva API. Si tiene que cambiar tanto un recurso específico que se vuelve incompatible con su versión actual, ¿tal vez debería ser un recurso nuevo?

Sin embargo, si decidió introducir el control de versiones, aquí hay dos estrategias para ello:

• Versión como parte de la URL,
• Versión en un encabezado de solicitud.

Versión como parte de la URL

Se pueden especificar versiones:

• A nivel de dominio: api2.example.com/postsLa ventaja es que las versiones están lo más "alejadas" entre sí como sea posible y dos versiones se pueden implementar de manera completamente diferente. Este enfoque es el más cercano a tener API sin control de versiones. Una cosa buena desde la perspectiva de REST es que las URL de los recursos permanecen "puras", no necesitan contener ningún fragmento como "v1". Solo apuntan a los recursos.
• Como un fragmento de ruta: example.com/api/v3/postsLas ventajas de este enfoque son similares a las del anterior, pero la URL no parece particularmente “pura”. Pero eso no siempre es un problema desde un punto de vista pragmático.
• Como parámetro de solicitud: example.com/api/posts?version=3La ventaja es que sin la versión especificada explícitamente, los desarrolladores de API pueden optar por recurrir automáticamente a la versión compatible más reciente o más antigua. Por un lado, las migraciones ocurrirán "automáticamente", por el otro, que pueden romper los clientes de API si los desarrolladores de API introducen cambios importantes.

Versión en un encabezado de solicitud

El cliente de API también puede especificar la versión de API requerida mediante:

• Un encabezado de solicitud HTTP personalizado Accepts-version: 23Accepts-version: 23
• Un encabezado de solicitud estándar Accept: application/vnd.example.v23+jsonAccept: application/json; version=23

Si la API utiliza el almacenamiento en caché, es importante asegurarse de que se tenga en cuenta el valor de ese encabezado de solicitud al almacenar en caché una respuesta.

Utilice solo números de versión principales

Use solo números de versión principales, como v11, no use versiones menores, como v2.2.1

Utilice la última versión si no se especifica ninguna versión

Si no se especifica una versión, use la última porque eso le pedirá a los desarrolladores del cliente API que especifiquen la versión deseada si ven errores cuando sus clientes API están haciendo llamadas. Con la versión más antigua utilizada de forma predeterminada, no hay forma de informar automáticamente a los desarrolladores del cliente API que hay una nueva versión disponible.

Utilice versiones coherentes en todos los recursos de la API

Es decir, /postsy los /merecursos para una API de blog siempre deben tener las mismas versiones compatibles, aunque solo algunos de los recursos pueden haber cambiado entre las versiones.

Utilice el encabezado de respuesta de Sunset para comunicar el final de la vida útil de los recursos

Utilice el Sunsetencabezado de respuesta para indicar que una versión de un recurso quedará obsoleta. Otro enfoque es devolver aleatoriamente el 410 Gonecódigo de respuesta HTTP, pero eso puede romper inesperadamente a algunos clientes.

Autenticación

La mejor práctica es utilizar OAuth2. Es muy utilizado y muchos desarrolladores están familiarizados con él. No invente su propio mecanismo de autenticación. Con OAuth, podrá deshabilitar a un cliente específico para que no acceda a su API y también a aplicaciones específicas.

Sin embargo, puede haber casos en los que puede permitir que los clientes de la API usen tokens de acceso. En ese caso, la API debería permitir muchos tokens por usuario. De lo contrario, será imposible para los clientes lanzar sus tokens sin interrupción / tiempo de inactividad.

d. Seguridad de un API

Todo el tráfico de la API debe enviarse a través de HTTPS, para que pueda cifrarse en tránsito.

Usar limitación y estrangulamiento de frecuencia

Es importante utilizar la limitación de la tasa de solicitudes por cliente de API para detectar clientes que realizan demasiadas solicitudes y pueden interrumpir el servicio de API.

Una API debe admitir el código de respuesta 429 y los encabezados como Retry-Afterpara proporcionar información cuando se debe reintentar una solicitud. También es ideal para apoyar las cabeceras como X-RateLimit-Limit, X-RateLimit-Remainingy X-RateLimit-Reset. Con suerte, los RateLimit-*encabezados se convertirán en estándar pronto.

Considere cuotas diarias o mensuales para la cantidad de solicitudes

Un API debe tener cuotas sobre el número de solicitudes por mes o día para cada cliente de API. Eso permite controlar el acceso a la API para clientes individuales y evitar el uso de demasiados recursos informáticos para atender solicitudes.

Es mejor no intentar implementar límites de velocidad y cuotas usted mismo y utilizar un producto de puerta de enlace API de terceros.

e. Experiencia de desarrollador

Las API están diseñadas para que las utilicen otros desarrolladores. Por lo tanto, los desarrolladores de API deberían facilitar que los desarrolladores de clientes comiencen a usar sus API.

Mantener la coherencia

Todo en la API debe ser coherente: nombres, representación de errores, identificadores, códigos de error, códigos de estado, encabezados, todo debe ser predecible.

Proporcionar documentación de calidad para desarrolladores

La documentación, los ejemplos y las bibliotecas cliente en lenguajes populares deberían estar disponibles de la forma más gratuita posible.

La documentación debe describir la API en un alto nivel, explicar qué es cada recurso, enumerar las solicitudes admitidas, así como las respuestas exitosas y los errores. Cada tipo de salida que produce la API debe documentarse y debe tener ejemplos de aspecto realista.

Asegúrese de que sus documentos de API estén actualizados. Idealmente, debería poder generarlos a partir del código fuente de la API.

El proceso de incorporación debería ser súper rápido y fácil para que los desarrolladores comiencen a usar su API.

Brindar soporte a los desarrolladores de clientes de API

Es probable que los desarrolladores usen varios lenguajes cuando trabajen con su API, por lo que sería fantástico proporcionarles ejemplos del uso de su API en diferentes idiomas.

Lo que sería aún mejor es proporcionarles bibliotecas de código abierto alojadas en GitHub que podrían usar en sus proyectos.

Es una buena idea monitorear esos repositorios de GitHub para ver si los desarrolladores abren PR o problemas.

También es una buena idea monitorear sitios de preguntas y respuestas como Stack Overflow para ver si las personas están haciendo preguntas sobre su API. Una dirección de correo electrónico de soporte para que los desarrolladores de clientes se pongan en contacto con los desarrolladores de API puede resultar muy útil.

Si puede crear una comunidad de desarrolladores en GitHub, o Stack Overflow, o en su propio sitio web alrededor de su API, será fantástico y también permitirá que los desarrolladores de clientes de API se apoyen entre sí.

Considere proporcionar herramientas para desarrolladores

Considere proporcionar información a los usuarios de su API sobre cómo usan su API: qué solicitudes realizan, cuántas exitosas y fallidas obtuvieron, qué tan cerca están de alcanzar los límites del plan actual. Probablemente no sea aplicable a todas las API, pero para algunas podría ser muy útil para fines de depuración.

5. Documentación de la API

No importa cuántas oportunidades brinde la API para crear o extender productos de software, seguiría siendo un fragmento de código inutilizable si los desarrolladores no entendieran cómo trabajar con él. La documentación de la API bien redactada y estructurada que explica cómo utilizar e integrar de forma eficaz una API de una manera fácil de comprender hará que un desarrollador esté feliz y ansioso por recomendar la API a sus pares.

La documentación de la API es un manual de referencia con toda la información necesaria sobre la API, incluidas funciones, clases, tipos de retorno y argumentos.

Numerosos elementos de contenido constituyen una buena documentación, como:

• Una guía de inicio rápido
• Información de autenticación
• Explicaciones para cada llamada a la API (solicitud)
• Ejemplos de cada solicitud y devolución con una descripción de respuesta, mensajes de error, etc.
• Muestras de código para lenguajes programáticos populares como Python, Java, JavaScript o PHP
• Tutoriales o videotutoriales
• Ejemplos de SDK (si hay SDK disponibles) que ilustran cómo acceder al recurso, etc.

La documentación puede ser estática e interactiva. Este último permite probar las API y ver los resultados de retorno y, por lo general, consta de dos columnas: humano y máquina. La columna humana contiene descripciones de la API, y la de la máquina tiene una consola para realizar llamadas y contiene información que interesará a los clientes y servidores cuando prueben la API.

Ejemplos de documentación de API

• API de Stripe https://stripe.com/docs/api
• API de Twilio https://www.twilio.com/docs/usage/api
• API de Dropbox https://www.dropbox.com/developers/documentation
• API de GitHub https://docs.github.com/en/rest/guides/getting-started-with-the-rest-api
• API de Twitter https://developer.twitter.com/en/docs/twitter-api/v1/tweets/search/overview

Referencias

• What is API: Definition, Types, Specifications, Documentation https://www.altexsoft.com/blog/engineering/what-is-api-definition-types-specifications-documentation/
• What is an API? https://www.redhat.com/en/topics/api/what-are-application-programming-interfaces
• ¿En qué consiste el diseño de API? https://www.redhat.com/es/topics/api/what-is-api-design
• 5 Examples of Excellent API Documentation (and Why We Think So) https://nordicapis.com/5-examples-of-excellent-api-documentation/
• 7 Items No API Documentation Can Live Without https://nordicapis.com/7-items-no-api-documentation-can-live-without/
• Best Practices for Designing Developer-Friendly REST APIs https://levelup.gitconnected.com/best-practices-for-building-developer-friendly-rest-apis-e6a419fcbd38
• Open API definition https://github.com/okffi/open-api-definition/blob/master/en/open-api-definition.md
• REST APIs: A Large-Scale Analysis of Compliance with Principles and Best Practices https://link.springer.com/chapter/10.1007/978-3-319-38791-8_2#CR16