Header Ads Widget

Ticker

6/recent/ticker-posts

7 ingredientes que conforman un excelente centro para desarrolladores

 

Centro de desarrolladores

¿Qué es un atributo consistente en los programas API exitosos? Todos tienen portales para desarrolladores increíbles. La buena documentación de la API es fácil de navegar y comprender, pero el mejor y brillante centro de desarrolladores impulsa la incorporación y la implementación real a nuevos niveles de usabilidad, hasta el punto en que la integración de la API se vuelve tan simple como un pastel, bueno, al menos tan simple como técnicamente posible. .

En el pasado, describimos cómo se ve un buen diseño de interfaz de usuario para un centro de desarrolladores , pero ¿qué información y guías debería priorizar para sus desarrolladores? Varía de una API a otra ya que los requisitos funcionales difieren, pero algunos inquilinos se mantienen en toda la industria.

Los buenos centros de desarrollo le permiten a uno verificar la documentación, obtener claves API, ver aplicaciones de muestra, verificar el tiempo de actividad, jugar con llamadas de muestra y administrar su cuenta a través de algún tipo de tablero. Muchas soluciones de administración en el espacio de API tienen portales de desarrollador incorporados con este tipo de funciones, pero si usted mismo estuviera construyendo una presencia de calidad, ¿qué factores clave se aseguraría de no omitir?

Entonces, para este artículo comparamos 10 programas API públicos exitosos para ver qué atributos tienen en común sus centros de desarrollo, y destiló esta investigación en siete ingredientes principales que los proveedores deben priorizar al crear un centro de desarrollo. Ya sea que su API sea gratuita, monetizada o estrictamente B2B, todos estos elementos serán válidos para cualquier kit utilizable.

1: Guía de inicio

El objetivo de una guía de introducción es hacer que el proceso de incorporación ' Hello World' sea lo más rápido y fácil posible. Los mejores centros de desarrollo describen un proceso paso a paso , guiando al usuario a registrar su aplicación, adquirir un token de acceso y usar estas credenciales para iniciar su primera llamada API . Twilio es el rey del departamento de incorporación: sus guías de API de SMS de inicio rápido supuestamente ponen a los desarrolladores en funcionamiento en cuestión de minutos.

En esta etapa, también revise qué otras integraciones ofrece su plataforma. Una API traerá las capacidades de integración más profundas, pero quizás los SDK, webhooks, complementos o widgets sean más accesibles para algunos usuarios. Si ofrece un conjunto de API, considere formas útiles de organizarlas: el selector de API de Google Map lo hace bien.

2: Guía de autenticación

Diagrama de flujo de código de autorización

Un flujo de trabajo de autorización para aplicaciones de larga duración diseñadas para ser autorizadas por el usuario una vez

Todas las plataformas de calidad dedican tiempo a explicar los mecanismos de autenticación necesarios para acceder a la API. Con demasiada frecuencia, la autorización se basa únicamente en las claves de API , pero como hemos explicado antes, las claves de API no deberían ser una dependencia exclusiva cuando se trata de la seguridad de la plataforma .

Probablemente, su API utilizará OAuth o una combinación de OAuth y tokens de identificación. Una vez que el cliente ha registrado su aplicación, este proceso permite que una aplicación autentique a un usuario en su nombre. La mayoría de las plataformas crean una guía única de OAuth 2.0 para desarrolladores que no están familiarizados con el flujo de trabajo. Obtenga una descripción general del proceso de intercambio de tokens en sus propias palabras o refiéralos a otros recursos de OAuth para obtener más información.

Por ejemplo, Spotify tiene una guía de autorización muy detallada que actúa en conjunto con su proceso de incorporación. Algunos desarrolladores que interactúan con los usuarios finales requerirán que se les otorguen distintos alcances de autorización, todos los flujos deben documentarse de manera digerible.

3: Documentación de API

La referencia es, con mucho, el punto focal para todos los centros de desarrollo de API. La documentación de endpoints es la principal herramienta que tendrán los desarrolladores para comprender con precisión cómo se comporta su API. Un enfoque común para estructurar documentación legible es una disposición de 3 columnas: punto final a la izquierda, llamada de ejemplo en el medio y código de muestra en varios idiomas en el lado derecho.

Estas especificaciones describen cada recurso accesible con un HTTPverbo ( GETPOSTPATCH, o DELETE) en términos técnicos, pero también ofrecen Descripción legible. Esto significa resumir lo siguiente:

  • Nombre del punto final (… /v1/user/data)
  • Describa el propósito del endpoint: ¿cuáles son los datos o la funcionalidad?
  • Describe los parámetros usados ​​en la solicitud HTTP para consultar la API.
  • Muestra un ejemplo de respuesta con formato JSON
  • Identifique el tipo de respuesta (String, Boolean, Int, etc.).
  • Tipo de autorización requerida

Aparte de algunas excepciones para SOAP / XML , la mayoría de las plataformas utilizan API web diseñadas por RESTful y respuestas con formato JSON. Para renderizar documentación legible, puede tener sentido utilizar un modo de especificación de API específico . Para ello, tiene opciones: Swagger / OpenAPI spec, API Blueprint o RAML son los tres formatos de especificación más utilizados.

Además de especificar la funcionalidad del punto final, el comportamiento de la API específico del diseño, como la paginación , la limitación de velocidad y los códigos de error, se documentan y se pueden acceder desde el menú del portal del desarrollador en estos centros para desarrolladores.

Para obtener más información, lea Principales formatos de especificación para API REST

4: entorno de prueba

El siguiente píxel en nuestra imagen del portal de desarrollo perfecto implica tener una demostración de la funcionalidad de la API para que los posibles usuarios puedan comprender instantáneamente cómo se comporta la API. Suele ser una consola interactiva donde se realizan solicitudes HTTP de muestra para simular puntos finales. Spotify, junto con muchas API existentes, ofrece una consola API interactiva  incluso antes del registro.

Como ocurre con la mayoría de los proyectos de software, la depuración es un proceso que requiere mucho tiempo. Por lo tanto, muchos también ofrecen una caja de arena que simula un entorno de producto utilizando puntos finales simulados para que los desarrolladores puedan probar sus integraciones. La PayPal Sandbox por ejemplo, es un entorno de prueba virtual independiente que permite a los desarrolladores crear cuentas de prueba para las entidades de usuario y realizar transacciones simuladas entre cliente y aplicación. El panel de la cuenta de un usuario se puede utilizar para rastrear aplicaciones integradas, cuentas de espacio aislado y transacciones en vivo.

Para ver otro ejemplo de una demostración de API, tome lo que ha hecho Postmates, el servicio de mensajería programable. Ofrecen una demostración interactiva de API a través de Postman , una herramienta para desarrollar, probar y compartir API. Puede utilizar la aplicación web Postman Chrome para iniciar llamadas a un punto final de API.

demo de postmates api usando cartero

Demostración de la API de Postmate con la herramienta Postman

Twitter también usa una consola de prueba de Apigee para demostrar el comportamiento de la API. MailChimp toma una ruta separada - la zona de juegos de la API no es una caja de arena, en el que las llamadas hechas utilizando la clave de la API del titular de la cuenta hacer la cuenta en su informe de uso de la cuenta. Si elige este método, comunique esta estipulación abiertamente a los consumidores.

Relacionado: 5 beneficios de usar la virtualización para probar su API

5: Recursos para desarrolladores

devkit-SDK-graphic-nordic-apis

'SDK' = Kit de desarrollo de software

Los recursos para desarrolladores son herramientas adicionales que ayudan a la experiencia de integración de API. Esto incluye tutoriales de código , código de ejemplo , o SDK  para integrar una API en el lenguaje de programación o sistema operativo de elección.

Alchemy API, por ejemplo, tiene guías específicas para consumir su API REST en Python , PHP , rubí , y Node.js . A menudo, las bibliotecas mantenidas por la comunidad surgen para consultar a los programadores en el idioma de su elección, pero hacerse cargo de los casos únicos en los que los usuarios interactúan con su API REST desde el inicio establece confianza: mantener sus propias bibliotecas de código y flujos de trabajo ayuda a garantizar la coherencia en toda la plataforma .

Relacionado: ¿Cuál es la diferencia entre una API y un SDK?

6: Canales de soporte

Un gran soporte es un inquilino crucial y completo para muchos programas API exitosos. A continuación, clasificamos el tipo de soporte ofrecido por los centros de desarrollo starling en dos grupos: canales de estado y soporte humano .

Canales de estado de API

El mantenimiento activo de la siguiente información es necesario para el soporte de cualquier plataforma, ya que ayuda a un posible usuario a medir el estado actual y a uno activo a responder a las actualizaciones. Estos ingredientes se muestran de manera destacada en los programas API populares y de alto uso:

  • Tiempo de actividad : detalles como porcentaje de tiempo de actividad, tiempo de respuesta e historial de incidentes pasados.
  • Registro de cambios : cronología de los cambios realizados en la API.
  • Rastreador de problemas : mecanismo de retroalimentación para rastrear problemas y sugerir cambios.
  • Control de versiones : si planea actualizar su API (v1, v2, v3….), Incluya la documentación histórica de la API y planes para futuras actualizaciones. Comunique una política de obsolescencia desde el inicio e indique claramente cuándo entrarán en vigencia los nuevos cambios.
Captura de pantalla del encabezado de mailchimp

Mailchimp actualiza su base de usuarios de desarrolladores con un anuncio audaz de la comunidad.

Apoyo humano

Las páginas estáticas pueden ser útiles, pero ¿cuándo fue la última vez que las preguntas frecuentes respondieron a su dilema técnico único? Los mejores portales para desarrolladores ofrecen ayuda instantánea con métodos de soporte de persona a persona.

Escribimos mucho sobre las relaciones con los desarrolladores y por una buena razón; aumentar la experiencia positiva que tiene un desarrollador con su API es absolutamente primordial. No es de extrañar que la participación activa en Stack Overflow , un grupo de Google , un administrador de Twitter para desarrolladores y un  correo electrónico para desarrolladores sean herramientas utilizadas por la mayoría de nuestra lista de los 10 principales. Aún así, sorprendentemente, muchas API de renombre podrían mejorar mucho sus relaciones con los desarrolladores si adoptaran ventanas de chat instantáneo con representantes de soporte.

Estrategia de alcance para desarrolladores de Google

Estrategia de alcance para desarrolladores de Google

Google Developers tiene este departamento bloqueado. Tienen un rastreador de problemas activo, responden en Stack Overflow, Github, usan una cuenta de Twitter de desarrollador dedicada y ejecutan un  blog de desarrollador . También es importante contar con un mecanismo de retroalimentación : saber qué preguntas hacer, cómo hacerlas e iterar sobre la información que recibe.

7: Política de plataforma

Tengo. A. Legible. Condiciones. de. Usar. Período.

Sí, legalizar en este entorno probablemente sea un proceso prolongado. Deje que los abogados hagan su oferta, pero cuando hayan terminado, resuma las restricciones principales y los casos de uso de API permitidos en una lista con viñetas que los usuarios realmente leerán.

Otra cosa que hacen bien los centros de desarrollo bien establecidos es proteger su identidad de marca; de hecho, extender la imagen de marca puede ser la única ventaja comercial de exponer una API gratuita. Las pautas de marca a menudo requieren condiciones para el nombre, la ubicación del logotipo, la paleta de colores y más. Spotify, por ejemplo, requiere un cierto relleno alrededor de su logotipo y elementos de la aplicación para garantizar que se destaque su identidad.

pautas del logotipo de diseño de spotify

Pautas de vigilancia de marca de Spotify

Para obtener más información sobre política, recomendamos leer la Guía humana para redactar la política de la plataforma API.

Dirija la presencia de su hogar a los no desarrolladores también

A medida que crece la economía de las API , también aumentará la conciencia del público en general, especialmente ahora que las OPI de CA Technologies, Apigee y Twilio están llevando la estrategia de API al dominio público. Por lo tanto, las presencias en la web deben evolucionar para encontrar nuevas audiencias. Twilio reconoce esto con una página de inicio renombrada titulada " No es un desarrollador " con recursos útiles para los no desarrolladores, así como opciones para trabajar con socios.

Los casos de uso general que muestran la experiencia del consumidor final son útiles porque inspiran a los emprendedores. En la misma línea, citar aplicaciones de muestra que ya están usando su API en vivo establece credibilidad, actuando como testimonios. Uber hace ambas cosas bien, con integraciones de ejemplo hipotéticas y aplicaciones en vivo como ejemplos:

Imprimir

Caso de uso potencial de la API de Uber

establecer credibilidad con aplicaciones de ejemplo

Socios que consumen la API de Uber

No asuma que su visitante está acostumbrado a la jerga del espacio API. Los conceptos relacionados con las API (tome HATEAOS) pueden parecer ajenos a los visitantes de su sitio (o incluso a algunos programadores experimentados). Adam Duvander recientemente fue tan lejos como para decir que las API son principalmente para "no desarrolladores con un problema comercial" .

Por lo tanto, hacer que estas entidades frontales sean accesibles es un truco importante para llevar las API a las masas. Como otro ejemplo,  Pitney Bowes muestra muy bien su conjunto de API a los no programadores, con descripciones de video digeribles para cada producto API específico.

Proceso de revisión

Para seleccionar una amplia gama de API para este estudio, tomé las principales API activas de diferentes sectores en el informe de hackers estudiantiles más reciente , que recopiló clasificaciones entre la tecnología utilizada en los hackatones y también las combiné con la última clasificación de API superior publicada por ProgrammableWeb. directorio. Terminé destacando las similitudes entre los siguientes 10 centros de desarrollo:

GORJEOPAYPALUBER (API DE VIAJES)TWILIOSPOTIFY
Postmatesmapas de GoogleYoutubeMailchimpAlquimia AP I
Vea los 30 atributos separados utilizados para evaluar estos 10 centros de desarrollo en esta hoja de cálculo .

También es importante agregar que toda esta información se adquirió públicamente con poca configuración de cuenta requerida, una indicación de que la transparencia en la esfera pública de API es primordial.

Pensamientos finales

Estos siete conceptos son posiblemente el pan y la mantequilla para sostener cualquier centro de desarrollo: los componentes básicos para crear una API consumible. Por supuesto, cada negocio de SaaS tendrá sus propios requisitos que requerirán perspectivas únicas.

¿Qué otros ingredientes debe tener su portal de desarrolladores de cara al público? Si está implementando estos siete conceptos generales, es probable que necesite algún tipo de panel de control de la cuenta para la administración de la cuenta, como la facturación y el monitoreo del uso. Para todos los ingredientes mencionados, las descripciones de página cuidadosamente redactadas utilizando palabras clave específicas pueden ayudar a optimizar su página de inicio de API , haciéndola más visible para los motores de búsqueda.

En este estudio, revisamos lo que algunos de los programas API favoritos de los desarrolladores ya han hecho para estructurar su servicio, pero su caso es único . Priorice las herramientas que  necesitan sus consumidores y cree centros de desarrollo inteligentes que informen e inspiren creatividad .

Publicar un comentario

0 Comentarios