5 pasos para crear una API exitosa

Es la naturaleza del desarrollo de software. Los desarrolladores crean software con el usuario final en mente. Parece bastante simple, pero a veces esos usuarios también son compañeros desarrolladores. No necesitan cosas desglosadas para ellos. Ni siquiera necesitan la simplicidad. Todo lo que quieren es acceder, una forma de integrar su software con el de ellos. Aquí es donde entra en juego una API (interfaz de programación de aplicaciones). Espero resaltar cinco pasos que puede seguir para crear una API exitosa.

Haz tu tarea

Cuando se trata del desarrollo de software, ninguno de nosotros quiere reinventar la rueda. En este punto, casi todas las grandes empresas web tienen API para sus productos de software. Estudie estas API e intente retomar las diferentes decisiones de diseño que se utilizaron para crearlas.

Existen muchas tecnologías diferentes, pero la mayoría de las API que verá utilizarán una interfaz RESTful o SOAP. Si no sabe qué interfaz API utilizará, le sugiero que adopte un enfoque RESTful utilizando el protocolo HTTP. Es más simple que SOAP, actualmente es más popular y será más fácil comenzar a usar un producto de software basado en la Web.

Se consistente

Una de las cosas que los desarrolladores aprecian más es la consistencia. Esto incluye, entre otras cosas, direccionabilidad, argumentos de entrada, formatos de salida y manejo de errores.

Cuando se utiliza un enfoque RESTful, hay muchos esquemas de nombres de URI diferentes. Cada uno tiene sus partidarios, así que solo elige uno y quédate con él. Lo mismo ocurre con la estructura de entrada y salida. La mayoría de las API admiten el uso de XML y JSON como formatos de entrada y salida. Sugeriría admitir ambos, pero elegir un formato predeterminado.

Para la entrada, sus requisitos de entrada deben nombrarse de manera coherente y deben tener sentido en el contexto de la llamada API que está realizando. Para la salida, asegúrese de estar utilizando diseños de estructura de datos comunes. Si está ajustando el resultado de una llamada API en un Etiqueta XML, considere hacer eso con sus otras llamadas.

Es una práctica común incluir algún tipo de indicador de estado en los datos de salida que envía de vuelta al cliente. Cuando se utiliza un enfoque API RESTful, esto debe hacerse utilizando códigos de estado HTTP. Por ejemplo, si acaba de procesar una solicitud PUT en un objeto de datos existente, el código de estado HTTP que incluya en su respuesta variará según el resultado de la solicitud.

En lugar de un indicador arbitrario que indica el estado de la llamada, se puede usar un código de estado estándar "200 OK" para indicar que la solicitud fue exitosa, mientras que se podría usar un código de estado "400 Solicitud incorrecta" para indicar que la solicitud fue malformado. Hay bastantes códigos de estado HTTP que se pueden usar en diferentes situaciones.

Use OAuth

La mayoría de los productos de software implicarán algún tipo de autenticación de usuario para acceder a recursos protegidos para ese usuario. Cuando se trata de API, es una mala práctica que el cliente recopile las credenciales de usuario para enviarlas a su servidor. Aquí es donde entra OAuth.

OAuth proporciona muchos beneficios sobre la autenticación de nombre de usuario / contraseña de terceros. Sobre todo, el cliente nunca tiene acceso a las credenciales del usuario. El usuario es redirigido a su servidor cuando inicia sesión. Después de que el usuario inicia sesión en su sitio, se lo redirige de nuevo al cliente donde el cliente recibirá un token de acceso para usar en futuras solicitudes de recursos protegidos.

Otro beneficio importante de usar OAuth es la capacidad del usuario para cancelar el acceso del cliente en cualquier momento. Si el usuario decide que, por cualquier razón, ya no desea que el cliente pueda acceder a los recursos protegidos en su nombre, simplemente va a una interfaz que ha creado y cancela el acceso del cliente.

Empezar temprano

Una de las cosas más importantes que puede hacer para que su API sea un éxito es comenzar temprano. Cuando escriba esa función para crear alguna entrada en su base de datos, continúe y tómese el tiempo extra y escriba una interfaz API para ella.

Escribir buena documentación

Nada mata una API más rápido que no tener una buena documentación. Si bien algunos desarrolladores pueden tomar una API mal documentada y descubrir cómo se supone que funciona, la mayoría no querrá hacerlo.

Debe documentar cada llamada a la API que tenga disponible y clasificar sus llamadas a la API por el tipo de datos sobre el que actúan. Además de documentar los puntos finales para las propias llamadas API, debe definir sistemáticamente los argumentos de entrada necesarios y opcionales, así como las estructuras de datos de salida. Los argumentos de entrada deben enumerar un valor predeterminado si hay uno, y también indicar el formato de datos esperado, como un número o una cadena. Por último, cada llamada a la API debe tener una lista de condiciones de error y códigos de estado.

Para completar su documentación, asegúrese de incluir uno o dos ejemplos de escenarios comunes de entrada y salida para cada llamada a la API.

Desarrollo API: Mantenlo simple

Si bien puede parecer que desarrollar una API es un esfuerzo complicado, la idea de una API en sí misma no es un concepto nuevo y hay una gran cantidad de documentación disponible sobre cada tema que tratamos aquí. Solo asegúrese de utilizar buenas prácticas donde pueda encontrarlas y de proporcionar una interfaz consistente y bien documentada.