Header Ads Widget

Ticker

6/recent/ticker-posts

8 claves para crear una API realmente utilizable

 

8-claves-para-crear-una-api-nordic-apis

Al crear una API, es muy fácil lanzar algo que "simplemente funciona". Para algunos desarrolladores que no están trabajando en una empresa de API donde la API es un componente central de su negocio, es posible que vean la creación de una API como una distracción de sus tareas principales y se apresuren a sacar un producto que haga el trabajo que es. se supone que debe hacerlo, pero poco más que eso.

A primera vista, puede parecer un MVP (producto mínimo viable), pero hay algunas diferencias clave entre las dos situaciones:

  • Los MVP están diseñados para evolucionar en función de los comentarios de los clientes, mientras que es más probable que los usuarios finales acepten las API "tal cual".
  • Un MVP generalmente se enfrentará a otros productos, mientras que una API puede ser la única solución disponible en un determinado nicho.
  • Ya sea B2B o B2C, un MVP tiene clientes que están realmente interesados ​​en cómo funciona y hacia dónde se dirige. Es más probable que tanto los proveedores como los consumidores vean con bastante apatía una API lanzada al mercado.

Los estándares de diseño de API han avanzado mucho, pero aún así el resultado es a) es fácil lanzar una API descuidada sin recibir mucho calor yb) las API pueden seguir siendo descuidadas sin mucha presión para cambiar.

Las cosas realmente no deberían ser así. Una API eficaz y utilizable puede desbloquear nuevos segmentos de mercado, crear posibilidades de asociación y convertirse en una herramienta extremadamente útil en la caja de herramientas creativas de su empresa. Con todo eso en mente, queríamos resumir los principales factores que tienen un gran impacto en la usabilidad de una API.

1: Diseño / Experiencia

Ya se ha escrito mucho sobre esto, incluso en nuestro blog , pero vale la pena repetirlo una vez más. Anteriormente citamos a Ronnie Mitra, director de diseño de API en API Academy, quien tiene lo siguiente que decir sobre el diseño de API:

"Si su API está mal diseñada, mal documentada y mal soportada y no están obligados a usarla, puede apostar que no lo harán ".

Por supuesto, es más fácil decirlo que hacerlo para crear una API verdaderamente eficaz, pero creemos que es algo a lo que siempre deberían aspirar quienes crean una API. Ya sea que desee llamarlo Experiencia de desarrollador (DX), Diseño u otra cosa, es importante que los proveedores de API hagan todo lo posible para que la implementación de una API sea lo más sencilla posible. DX implica aumentar la transparencia con documentación accesible, disminuir el tiempo de incorporación y mejorar la estética de su portal de desarrollador en todos los frentes.

2: Tecnología

¿Cómo se accederá a su servicio web? Al refinar la pila de API subyacente, haga coincidir la tecnología con lo que su audiencia de desarrolladores desea consumir.

  • Protocolos : Considere cómo desea que sus datos sean accedidos REST, SOAP, Apache Thrift, etc .
  • Formatos : admite tipos de devoluciones que sean relevantes para tu audiencia y sus hábitos de consumo (JSON, XML, etc.). En determinadas iniciativas de API de datos abiertos, gubernamentales y empresariales, esto podría incluso ser CSV o PDF.
  • Hipermedia : considere agregar controles que permitan la navegación inteligente, el etiquetado, la paginación y más.
Para obtener más información sobre hipermedia: cómo utilizar las API de hipermedia para entregar HTML con diseño web adaptable

3: Pruebas externas

No hay muchas circunstancias en las que lanzaría un nuevo producto a la naturaleza sin probarlo en un grupo de enfoque de clientes potenciales o existentes. Aplique esta misma mentalidad de producto a la propiedad del producto API.

Servicios como Peek facilitan a los redactores, diseñadores y desarrolladores obtener una visión rápida de lo que la gente piensa sobre su sitio. Desafortunadamente, la necesidad de experiencia técnica significa que es más difícil obtener este tipo de comentarios de los consumidores potenciales de API.

Lanzar una API como una beta abierta y monitorear activamente un foro de comentarios no es una mala idea porque tranquiliza a los consumidores desarrolladores de que, si hay problemas con la API, existe al menos alguna posibilidad de que se solucionen con el tiempo.

El simple hecho de tener un estado beta abierto fomenta la retroalimentación mucho más que una versión tradicional. Ampliar las funciones de prueba podría implicar ofrecer entornos virtuales para que los usuarios desarrolladores modelen el comportamiento de la API en sus procesos de desarrollo de aplicaciones.

4: Estado / Registro de cambios y documentación

La gestión adecuada de los estados de los puntos finales de la API es clave para mantener felices a los usuarios. Algo como la solución de MailChimp (http://status.mailchimp.com) es una buena manera de mantener a las personas informadas y establecer credibilidad con excelentes tasas de tiempo de actividad:http : // estado mailchimp com ) es una buena manera de mantener a las personas informadas y establecer credibilidad con excelentes tasas de tiempo de actividad:

Ejemplo de estado de la API de Mailchimp nordic apis

En la remota posibilidad de que algo salga mal, una buena forma de notificar a los consumidores de API (que no sea una página de estado, como usa MailChimp) es enviar alertas por correo electrónico o compartir una actualización de estado en Twitter.

MailChimp también mantiene un registro de cambios completo, ofrece un patio de juegos API, un glosario de errores, una lista de mejores prácticas, junto con muchas otras guías. El resultado es que su área de Desarrolladores se siente tan acogedora para los novatos como para aquellos que han estado trabajando con API durante años.

La descripción adecuada de las respuestas de la API con códigos de error completos es fundamental para crear API web utilizables A veces, las cosas salen mal y está bien, siempre que los mensajes que surjan de los errores (del lado en el que estén) expliquen cómo solucionarlos.



	
		400
		Dial: Invalid phone number format 
13223
		http://www.twilio.com/docs/errors/13223 
	

No hay nada menos útil que un error poco claro y no estructurado que te deja rascándote la cabeza. La respuesta de error de la API de Twilio que se muestra arriba es un gran ejemplo de cómo NO dejar a uno confundido: tiene un mensaje de error sencillo con un enlace para obtener más información sobre qué lo causó y cómo remediarlo.

Leer más: Beneficios del uso adecuado del código de estado HTTP

5: tono

No tenga miedo de divertirse un poco con sus API. Dejar en claro lo que hace la API es probablemente la tarea más importante en el libro de reglas del creador de la API, pero hacerlo usando un lenguaje seco es la forma más fácil de hacer que la gente se desconecte. Invertir un poco de tiempo en documentar la API de una manera que sea concisa, legible y tal vez incluso (horror) haga sonreír a la gente, es una forma segura de hacer que las personas se involucren con la API en sí.

Twitter hace un buen trabajo en esto, con una copia dirigida por el desarrollador en páginas como esta . A veces se muestran un poco pseudo-aspiracionales a veces, pero su contenido es generalmente conciso y fácil de entender.

Hay un viejo adagio que es popular entre los redactores publicitarios, y es que es "divertido, no divertido". Tratar demasiado de ser gracioso nunca es algo bueno, pero ir con un tono alegre y desenfadado animará a las personas a ceñirse a tu documentación en lugar de tratar de abordar todo por su cuenta.

6: velocidad / escalabilidad

Siempre que se habla de usabilidad, el tema de la velocidad inevitablemente asoma su cabeza. Mire, por ejemplo, las formas en que REST ha mejorado en SOAP . Algunas de las ventajas de REST, de las cuales hay muchas, incluyen:

  • Soluciones más sencillas e intuitivas
  • Salida más rápida
  • Más fácil de escalar
  • Permite que los posibles consumidores de API se conecten a un servicio de forma más eficaz

Hay una razón por la que la comunidad ha adoptado los principios RESTful de la forma en que lo ha hecho: a menudo es la herramienta adecuada para el trabajo. Cuando los diseños hipermedia y RESTful prometen cambiar la forma en que funcionan las API, hacer que las API sean más rápidas y fáciles de implementar, y fomentar que las API se mantengan lo más actualizadas posible, parece una tontería no adoptarlas.

Eso no significa que debas subirte a la parte posterior de cada una de las modas que surgen, solo que mantenerte al día con las mejores prácticas podría ayudarte a descubrir ese problema que está impidiendo que tu API se convierta en una parte más valiosa del ecosistema en el que estás funcionando.

Más: Vea nuestra infografía para obtener más comparación entre REST y SOAP

7: eficiencia

Cuando se trata de construir una API, la eficiencia es, con demasiada frecuencia, una idea tardía. A veces, el enfoque está fuera de lugar; para el proveedor, se trata más de lo que se logra que de cómo se logra.

Cuando hablamos de eficiencia, hablamos tanto de eficiencia técnica (por ejemplo, paginación, número de llamadas, estructura utilizada, tamaño de la pila, etc.) como del impacto que tiene sobre cómo funciona realmente la API; cosas como la velocidad de las llamadas, la disponibilidad, los formatos de salida, etc.

Una API es tan buena como la experiencia que alguien tuvo la última vez que la usó; Las API que son consistentemente lentas o poco confiables provocarán una hemorragia en los usuarios que no tienen que usarlas e invitarán a críticas aparentemente interminables de aquellos que sí lo hagan. Todo lo cual te dará un terrible dolor de cabeza ...

7.5: Bibliotecas de código

Este punto no tiene un número propio, ya que es más una rama de la eficiencia, pero las bibliotecas auxiliares que se adaptan a diferentes lenguajes hacen que lidiar con una API sea más atractivo para una audiencia de desarrolladores más amplia.

Twilio es uno de los mejores en esto con más de 15 idiomas diferentes en su sección de Bibliotecas, aunque la mayoría de esta documentación ha sido recopilada por su comunidad de desarrolladores.

Obtenga más información sobre qué idiomas admitir en sus bibliotecas auxiliares

8: Mantenimiento continuo

Ya hemos mencionado la documentación y los mensajes de error anteriormente, pero hay más que mantener que solo estas cosas. Para evitar que su API se convierta en un relámpago y garantizar que su usabilidad mejore (o al menos permanezca constante), es posible que desee pensar en:

  • Crear una comunidad de desarrolladores eficaz: listas de correo, grupos de Google, chats de Slack, como quiera que lo haga.
  • Crear bibliotecas reutilizables / mejores prácticas para nuevos usuarios, lo que también debería reducir la cantidad de errores con los que tiene que lidiar.
  • Control de versiones adecuado que no interrumpe a quienes aún usan la versión anterior hasta que se produzca una desactivación final programada.

Lo anterior es un buen comienzo, pero para agregar sus propios puntos a esa lista, solo piense en las API que no puede usar y reemplace sus puntos débiles con métodos utilizables.

Pensamientos finales

La respuesta a la pregunta "¿qué hace que una API sea utilizable?" es, como tantas otras cosas, "depende". ¿Pero depende de qué?

  • Cómo se ven sus usuarios potenciales y su nivel de experiencia.
  • El propósito designado de la propia API y la frecuencia con la que necesita enviar / extraer datos.
  • La estrategia de aprovisionamiento central Las API privadas, públicas o asociadas tendrán inherentemente una exposición diferente de la documentación y el acceso.

Sí, hay factores que siempre deben ser constantes (velocidad, seguir buenos principios de nomenclatura, etc.), pero hay muchos otros que variarán considerablemente. Cuando comienza a considerar problemas como los enumerados anteriormente, comienza a tener una idea de cómo debería verse su API, promoviendo un mayor énfasis en todo el ciclo de vida del producto API .

Y si todo lo demás falla y queda totalmente en blanco, pregúntele a alguien que lo usará qué quiere que haga. Eso debería ayudarte a empezar con buen pie.

Publicar un comentario

0 Comentarios