Las especificaciones que nos definen

Como desarrollador, soy perezoso. Si alguien ha creado un programa que resuelve un problema que tengo, quiero utilizarlo. Debería poder ponerme manos a la obra y ponerme al día rápidamente con una nueva biblioteca sin muchas interferencias.

Como responsable de la iniciativa para el equipo de SDK de servidor de Nexmo, uno de mis objetivos ha sido asegurarme de que proporcionamos la mejor experiencia posible a los desarrolladores que utilizan nuestros SDK. ¿Cuál es el punto de un SDK si su uso es tan doloroso como excavar a través de la documentación y hacer peticiones HTTP en bruto? Nuestro equipo quiere asegurarse de que puedas hacer tu trabajo -crear software- más rápido.

Recientemente, el equipo se reunió y decidió revisar las especificaciones existentes del SDK del servidor (antes llamadas especificaciones del SDK del cliente) para ver cómo se mantenían. Las especificaciones se redactaron en 2016, cuando Nexmo empezó a pensar de forma más crítica sobre cómo escribíamos nuestro software. En 2020, ahora mantenemos seis SDK de idiomas diferentes, y cada idioma tiene sus propias peculiaridades. Qué tenemos que hacer diferente hoy que hace años?

Menos RFC, más flexible

El primer paso fue eliminar gran parte del lenguaje inspirado en las RFC. El razonamiento era muy sencillo: las RFC ofrecen una estructura y una terminología conocidas y consensuadas. Gracias al RFC 2119palabras como MUST, MUST NOT, SHOULD, SHOULD NOTy otras, todas tienen sus propias definiciones específicas y establecen expectativas sobre cómo se escribirán las RFC. Si alguien estuviera creando un nuevo documento de especificación, estas palabras tendrían todo el sentido del mundo.

Cuatro años y cinco SDK más tarde, el documento se había vuelto bastante estricto en lo que respecta no sólo a la funcionalidad, sino también a la implementación directa. No sólo detallaba el comportamiento, sino también cómo debían estructurarse los clientes de la API. Esto provocó una división natural en el diseño de algunos SDK y obligó a otros SDK a hacer las cosas de una forma poco natural para el lenguaje. ¿Debería un SDK de Ruby parecerse y actuar como una biblioteca de NodeJS?

Probablemente no.

Así que hemos eliminado gran parte del lenguaje en torno a construcciones lingüísticas específicas, pero hemos mantenido los objetivos y metas generales de varias ideas que creemos que hacen que un SDK sea fácil de usar. Errores y excepciones sigue siendo la idea de que una biblioteca debe lanzar explícitamente excepciones de servidor o respuesta, mientras que las instrucciones sobre cómo nombrar las cosas se han reducido a "aquí hay una lista de verbos que debe utilizar" La especificación ya no dicta invocaciones directas de los métodos, pero sugiere una nomenclatura coherente.

La especificación está mucho menos interesada en hacer de los SDKs una experiencia homogénea y ahora impulsa una directiva de hacer coincidir las expectativas del lenguaje y las mejores prácticas. Con el tiempo, esto significa que nuestras API de SDK públicas cambiarán, pero cambiarán hacia algo que usted, como desarrollador del lenguaje X, espera. Queremos que los SDKs proporcionen una experiencia que obtendrías con cualquier biblioteca bien construida de tu idioma.

Abstracción de HTTP

Lo impresionante de Nexmo es que cualquiera puede empezar a utilizar inmediatamente nuestra API con sólo pulsar una dirección web. Internet ha hecho posible interactuar rápidamente con máquinas de todo el mundo utilizando un protocolo estándar, HTTP, y una sencilla interfaz textual a través de JSON y XML. Podemos conectar varios servicios como nunca antes.

Pero ¿por qué, cuando necesitas reproducir texto a voz en una llamada, te hacemos hacer un $talk->put()? Semánticamente, no tiene sentido.

Sí, Nexmo proporciona una API impresionante, pero cuando estás creando tu software no debería importarte realmente lo que somos. Si quieres reproducir texto a voz en una llamada, $call->playTextToSpeech("Hello World") es mucho más claro en sus intenciones. Esto puede hacer un HTTP PUT request para hacer el trabajo, pero no hay ninguna razón por la que necesitemos nombrar nuestros métodos como métodos HTTP.

Hemos limpiado los verbos y convenciones de nomenclatura a una lista de acciones que harías para realizar un trabajo, no para escribir un cliente HTTP. Los desarrolladores utilizan SDKs para abstraer los servicios de terceros que utilizan, por lo que debemos ayudar a continuar esa abstracción con nuestras convenciones de nomenclatura. Al fin y al cabo, a nadie le importa si usamos un PUT o a POST para hacer algo, sólo quieren encontrar y realizar una acción.

La comodidad por encima de todo

Quiero asegurarme no sólo de que nuestros SDK ofrecen todas las formas posibles de interactuar con nuestra plataforma, sino también de que la interfaz es fácil de entender y de usar. Nuestros SDKs deberían ayudarte a solucionar tu problema siendo explícitos sobre el trabajo que se está haciendo, a la vez que te ayudan a ocuparte de la burocracia que puede venir con el trabajo.

Si volvemos a nuestro ejemplo de reproducir texto a voz en una llamada existente, nuestra forma actual es un poco obtusa desde el punto de vista de la claridad y la semántica. Averiguar cómo hacer algo en nuestro SDK debe ser explícito, pero también rápido de hacer. No quiero que un desarrollador vuelva a su código dentro de seis meses e intente averiguar por qué talk() devuelve un objeto en lugar de realizar una acción. Quiero que el desarrollador lea fácilmente su propio código y sepa exactamente lo que está sucediendo en todo momento.

// Current, pull a Talk object out of a specific call
$talk = $client->calls['abcd-123']->talk();
// Set the text
$talk->setText(TEXT);
// PUT the text back to the API
$talk->put();

// In the future, we will just find a specific call
$call = $client->calls()->find('abcd-123');
// And play Text to Speech into it
$call->playTextToSpeech("All your base are belong to us");

El futuro

El equipo del SDK de servidor está revisando actualmente todos nuestros SDK principales (NodeJS, Java, Python, .NET, Rubyy PHP) y compararlos con la nueva especificación. Tenemos algunos cambios interesantes por venir, ya que nos centramos en la experiencia del desarrollador con nuestros SDKs, y queremos ofrecer a todos nuestros clientes la misma facilidad de uso que siempre han esperado con nuestros SDKs de una manera más moderna y limpia.

Como siempre, nos encanta recibir comentarios de nuestros clientes. Construimos este software para hacerles la vida más fácil. Si nos ves en una conferencia o reunión, ¡dinos cómo nos va! ¿Hay algo que le gustaría ver en nuestros SDK? Póngase en contacto con nosotros en Github y dinos si hay características que echas en falta.