¿Qué idiomas deberían admitir sus bibliotecas auxiliares de API?

 

Enviar una gran API no se trata solo de exponer un punto final de una manera RESTful. Sí, muchos usuarios desarrolladores estarán bien haciendo solicitudes HTTP, pero para algunos, eso no es suficiente. Ya sean seleccionadas por la comunidad o proporcionadas por el proveedor, las bibliotecas de código a menudo se crean para ayudar a extender una interfaz de programación de aplicaciones (API) a idiomas específicos . Estas bibliotecas ayudan a incorporar a los usuarios de terceros y demuestran que está dispuesto a trabajar en su propio terreno.

En este primer artículo de una serie sobre el soporte de su API con bibliotecas de código , examinamos la importancia de las bibliotecas auxiliares y cómo afectan a su audiencia. Con el respaldo de la investigación sobre las tendencias de los lenguajes de las bibliotecas de API en varias industrias, determinamos qué lenguajes debe intentar admitir. También nos sintonizaremos con lo que jugadores como Twilio y Stripe están haciendo bien para obtener las mejores prácticas útiles.

¿Qué son las bibliotecas auxiliares?

Las bibliotecas auxiliares son recursos para desarrolladores que permiten a un desarrollador llamar a una API dentro del lenguaje con el que están más familiarizados, ya sea C #, Ruby, Node.js, Scala, Go, Clojure, Objective-C o muchos otros. Las bibliotecas auxiliares, las bibliotecas de código, los contenedores, las gemas Ruby, los enlaces de Python, los módulos Node.js y los kits de desarrollo de software (SDK) ayudan en este sentido.

Vea a Michael Wawra , evangelista de Twilio , discutir este tema en un evento de API nórdicas

¿Por qué no dejarlos DESCANSAR?

Por lo general, el localizador uniforme de recursos ( URL ) es un amigo, que permite el acceso a un recurso específico y permite que el software salga de entornos aislados. La existencia de URL ha permitido que Internet, junto con una increíble variedad de productos, prospere. Sin embargo, acceder a los recursos desde algo que no sea un navegador web puede ser un dolor total. Una solicitud cURL POST a la API de Twilio solicitando enviar un mensaje de texto, por ejemplo, puede verse así:

$ curl -XPOST https://api.twilio.com/2015-11-09/Accounts/AC5ef823a324940582addg5728ec484/SMS/Messages.json \
	-d “Body=Jenny%20please%3F%21%20I%20love%20you%20<3” \
	-d “To=%2B1415924372” \
	-d “From=%2B424572869” \
	-u ‘AC5ef823a324940582addg5728ec484:{AuthToken}’

Este tipo de solicitud es legible por máquina, pero implica una gran cantidad de codificación y símbolos raros para imprimir una frase relativamente simple. Ingrese REST : una forma de crear servicios web siguiendo un conjunto de restricciones específicas entre consumidores y proveedores. La especificación describe formas de interactuar con las URL en un método práctico y comprensible.

Sin embargo, incluso si una API es RESTful, el código Ruby requerido para una solicitud POST para inicializar un URI sigue siendo torpe. Aquí hay una solicitud POST escrita en Ruby para acceder a la API de Rackspace:

uri = URI.parse(‘https://auth.api.rackspacecloud.com”)
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.verifiy_mode = OpenSSL::SSL::VERIFY_NONE
request = NET::HTTP::Post.new(‘/v1.1/auth”)
request.add_field(‘Content-Type’,’application/json’)
request.body = {‘credentials’ => {‘username’ => ‘username’, ‘key’ => ‘key’}}
response = http.request(request)

Todo lo que está haciendo es establecer una conexión y verificar las credenciales. Sin embargo, si algo sale mal con esta solicitud, los resultados pueden complicarse fácilmente. La mayoría de las personas conocen el código de error HTTP 404 (No encontrado), pero hay más de 80 otros códigos de error HTTP totales especificados , y el comportamiento de respuesta de cada API es diferente según la extensión que el proveedor haya elegido. Lidiar con los códigos de error es complicado, por lo que los ingenieros de software a menudo han optado por abstraer y envolver un método, otra razón para adoptar bibliotecas auxiliares, según Wawra.

Éxito vs fracaso: descubra la importancia del análisis de métricas de API

Problema de datos

Los proveedores de API también deben adoptar las convenciones y considerar qué formatos de datos se están utilizando. Por ejemplo, cuando tienes que enviar fechas, ¿qué estándar de fechas estás usando? Quizás su servicio utilice un registro diferente al de base 10. Cuando los usuarios navegan por su documentación, necesitan comprenderla en el ámbito de sus propios idiomas.

Aquí es donde entran en juego las bibliotecas auxiliares. Simplemente exponer un recurso HTTP está bien, pero necesitamos brindar un poco más de ayuda a los desarrolladores. Por ejemplo, usando una gema Ruby para la API de Twitter:

client = Twitter::REST::Client.new do |config|
  config.consumer_key        = "YOUR_CONSUMER_KEY"
  config.consumer_secret     = "YOUR_CONSUMER_SECRET"
  config.access_token        = "YOUR_ACCESS_TOKEN"
  config.access_token_secret = "YOUR_ACCESS_SECRET"
end

client.update(“I’m tweeting with @gem!”)

Este código simple que se encuentra en Github inicializa el objeto auxiliar y lo usa para enviar un tweet "Estoy twitteando con @gem" a la biblioteca de Twitter. Maneja todo lo que no queremos preocuparnos.

Tendencias del lenguaje de programación

Así que está convencido de que necesita construir bibliotecas auxiliares para sus consumidores desarrolladores, pero ahora llega el momento de la verdad. ¿Cómo decidimos qué idiomas admitir? ¿Abordamos más de 30 idiomas?

Para reducir las cosas, echemos un vistazo a un par de fuentes. VentureBeat cita los 10 idiomas principales utilizados en GitHub como:

Adam Duvander , utilizando datos ProgrammableWeb, ha citado los principales lenguajes utilizados para las bibliotecas auxiliares de API como:

1. PHP
2. Pitón
3. Rubí
4. .NET / C #
5. Java
6. Perl
7. Fusión fría
8. Node.js
9. ActionScript

Descubra qué idiomas utilizan sus consumidores

Independientemente de la tendencia de la industria, el paso más importante es escuchar a sus consumidores desarrolladores ; es probable que ya le hayan dicho qué idiomas agregar. Descubrir esto es relativamente simple: realice el monitoreo de las solicitudes HTTP a su servidor . Si está registrando esas solicitudes (con suerte, este ya es el caso), entonces puede averiguar fácilmente el agente de usuario para esas solicitudes para determinar qué lenguaje de programación están usando. Debería verse así:

curl/7.31.0
PHP_Request/curl-7.15.5
Java/1.6.0_31

Los usuarios desarrolladores son sus clientes. Siempre respete el hecho de que sus usuarios codifiquen, lo que significa que siempre pueden hacer su trabajo y escribir su propia API si es necesario. Especialmente en el caso de Twilio, sus desarrolladores están consumiendo su API como un mecanismo de ahorro de tiempo, por lo que la experiencia del desarrollador debe ser lo más fácil posible. Registre la actividad, determine qué están usando sus consumidores y cree recursos para desarrolladores en consecuencia.

Descargue nuestra Guía de desarrollo: API de programación con Spark Web Framework

¿A quién debemos modelar?

A continuación, se muestran algunos datos recopilados por ellos mismos sobre los idiomas compatibles con los principales proveedores de API para bibliotecas / SDK en diversas industrias. Twilio tiene un gran programa de biblioteca de divulgación, al igual que Stripe . Es importante tener en cuenta que muchas bibliotecas auxiliares viven en el dominio de código abierto y Github , lo que significa que muchas bibliotecas son mantenidas por la comunidad circundante, tal vez ni siquiera las toque el proveedor.

PROVEEDOR	OFICIAL	COMUNIDAD	PÁGINA DE INICIO DE LA BIBLIOTECA AUXILIAR
Twilio	PHP, Ruby, Python, C # /. NET, Java, Node.js	Go, JavaScript, C ++, Scala, Perl, Erlang, Adobe ColdFusion, Adobe, LiveCycle, Mule ESB	Bibliotecas
Gorjeo	Java, Android	ASP, C ++, Clojure, ColdFusion, Go, Java, Node.js, Lua / Corona, Objective-C, Perl, PHP, Python, Ruby, C, .NET, Erlang, Java, muchos más.	Bibliotecas de Twitter
Caja	Java, Python, .NET, Ruby, Móvil (iOS, Android, Windows)	APÉNDICE	SDK
eBay	.NET, Java, Python		( SDK de eBay
FitBit	Java, PHP, .Net		Centro de desarrollo
Cuadrado		Java, Objective-C, JavaScript, Ruby	Bibliotecas de código abierto
Raya	Python, Ruby, PHP, Java, Node.js, Go,	Ruby, PHP, C #, ColdFusion, Perl, Clojure, Scala y más.	Bibliotecas API internas

HTTP es independiente del lenguaje

Con HTTP puede navegar por la web, realizar una solicitud REST, piratear Snapchat o realizar solicitudes SOAP. Pero las bibliotecas auxiliares deben ser Language Idiomatic . A un desarrollador de Python no le importa si sus bibliotecas se comportan de la misma manera; deben comportarse de una manera que tenga sentido para ese lenguaje específico.

Ejemplo de Python usando el cliente REST de Twilio:

client = TwilioRestClient(“accountSid”, “authToken”)

message = client.messages.create(to=”+12316851234”,
					from_=”_15555555555”,
					body=”Hello there!”)

Por otro lado, C # debe verse y comportarse como C #:

var twilio = new TwilioRestClient(“accountSid”, “authToken”);

var msg = twilio.SendMessage(“+15554446666”,  
                “+15557778888”,  
                “that was easy!”);  

5 consejos para el diseño de bibliotecas auxiliares

• Mantenga el vocabulario coherente con la documentación : aunque las bibliotecas cliente deben adaptarse a la doctrina del lenguaje específico en mente, deben ser coherentes con la documentación de la API REST y el vocabulario de parámetros. Estos términos deben ser coherentes en todos los recursos que se integran con su plataforma. Ser idiomático con los idiomas es importante, pero los términos y las características deben ser coherentes.
• Superficie : ¿Cuánto de su API debería cubrir su biblioteca auxiliar? La respuesta es todo . Wawra recomienda casar la API con la representación web. Esto significa que todas las funciones que puede hacer su sitio web, su API también debe manejarlas y, a su vez, también su biblioteca auxiliar. Si está utilizando una estrategia de creación de API primero , esto se vuelve mucho más intuitivo.
• Publicaciones y actualizaciones simultáneas en toda la plataforma : no tiene sentido crear versiones de su API o agregar nuevas funciones si sus bibliotecas auxiliares no están sincronizadas con las actualizaciones. La regla general es, para sus bibliotecas mantenidas oficialmente, publicar cambios en la funcionalidad de la API en toda la documentación y todas las bibliotecas simultáneamente .
• PRUEBA : Trate su biblioteca auxiliar como un producto y pruebe con la misma rigurosidad que lo haría con su API.
• Código abierto : no es una estrategia para todas las empresas, pero a los desarrolladores de API les encanta Github , y los proveedores pueden beneficiarse del aspecto comunitario de la fuente abierta de su biblioteca. La creación de una comunidad en torno a sus API y bibliotecas fomenta la mejora del código.

Última línea de código API: su API nunca está realmente terminada

Al final del día, la biblioteca de ayuda que envíe vivirá en la aplicación del usuario. Dado que está en la aplicación del usuario, tiene un control limitado. Sin embargo, los desarrolladores siempre están creando nuevas aplicaciones, lo que significa que su API nunca está realmente terminada. Tener una mentalidad ágil con iteración constante es crucial. Esté atento a las publicaciones futuras, en las que exploraremos el control de versiones simultáneo en toda la plataforma, cómo automatizar la generación de SDK utilizando herramientas como  APImatic y RESTUnited , y profundizar en la decisión de cuál es mejor: ¿abrir su biblioteca auxiliar o mantenerla internamente?