Header Ads Widget

Ticker

6/recent/ticker-posts

Cómo hacer una API empresarial autodescriptiva


 Una de las cosas más difíciles de hacer como proveedor de API es trabajar dentro del entorno empresarial . Esto se debe, en gran parte, a la naturaleza misma de las estructuras empresariales: a menudo lentas para adoptar nuevas tecnologías, desconfía fundamentalmente de las soluciones externas y mucho más insular de lo que la mayoría de las corporaciones modernas quisieran admitir. Esto es una lástima, ya que muchos desarrolladores de API encuentran que sus herramientas son ignorados en favor de la costumbre-construido soluciones que son casi nunca como auto-descriptivo o eficiente en la ejecución.

Entonces, ¿qué debe hacer el desarrollador de API promedio? Uno de los principales pasos que los proveedores pueden tomar para conectarse dentro del espacio empresarial es en realidad una solución que sea universalmente positiva y relativamente simple de implementar. El concepto de hacer que su API sea autodescriptiva tiene algunos beneficios importantes cuando se trata de la integración y el establecimiento de confianza con las soluciones empresariales, pero los beneficios de dicho sistema se extienden mucho más allá de este alcance.

Hoy, veremos el espacio empresarial y veremos algunos problemas comunes con los que se encuentran los desarrolladores y proveedores de API cuando intentan integrarse. Discutiremos el concepto de tener una API autodescriptiva y estableceremos el valor transferido de los desarrolladores a sus clientes empresariales. Comprenderemos el concepto de ética de API autodescriptiva de Shelby Switzer, extrayendo joyas de sabiduría de su charla dada en la Cumbre de la Plataforma de APIs nórdicas de 2017.

Mire la presentación complementaria a esta publicación de blog dada por Shelby Switzer de Healthify en nuestra Cumbre de Plataforma 2017

API frente a integraciones: convencer a la empresa

En un nivel fundamental, la empresa no funciona bien y no se integra con otros sistemas. El hecho es que muchas soluciones empresariales son a largo plazo y personalizadas . Se han repetido y destruido a lo largo de los años, a menudo para actualizar sistemas que existían mucho antes de que se construyeran las computadoras que ahora contienen los datos.

Desafortunadamente, esto dificulta un mayor desarrollo fuera de la implementación de nicho específico de la empresa. Tiene como resultado que se ignoren las nuevas innovaciones en favor de sistemas confiables que pueden hacer el trabajo, pero a menudo de manera ineficiente . Para rectificar esto, la empresa a menudo ignora el concepto de utilizar una API externa por completo y, en su lugar, se basa en integraciones o versiones personalizadas de clientes que utilizan sus sistemas como base.

El problema con tal integración, sin embargo, es que no son impulsados ​​por la tecnología o por la implementación, sino más bien por las intenciones de quienes la han desarrollado desde adentro.

“La gente hace las cosas realmente difíciles. Tienen sus propias ideas, tienen su forma de hacer las cosas. Y a veces, hemos descubierto que en la empresa, su mentalidad es que lo haremos a su manera, o que ellos no lo harán en absoluto ”.

Esta mentalidad hacia las tecnologías modernas no solo dificulta un mayor desarrollo externo, sino que casi resulta en una especie de guerra: un conflicto constante entre la integración empresarial y la naturaleza del microservicio moderno y el espíritu de diseño centrado en API. Esto es lamentable, ya que las API web estandarizadas son casi siempre más eficientes y escalables que las integraciones personalizadas.

4 razones por las que las API son superiores a la integración empresarial

¿No convencido? Aquí hay más razones por las que la estandarización con API gana frente a las integraciones empresariales.

  1. Las API son reutilizables . Las API se pueden aprovechar para más de una aplicación de un solo uso, incluso cuando son un microservicio diseñado para dicha aplicación. Se puede usar una API de enrutamiento de datos o una aplicación de conversión una y otra vez, incluso en diferentes partes de la empresa, lo que reduce la complejidad y el exceso de código.
  2. Las API se pueden mantener . Se pueden mantener mucho mejor que una serie de integraciones en la solución empresarial clásica porque hay una única fuente de manejo de datos, una única base de código (o un grupo de microservicios basados ​​en un lenguaje y esquema comunes) y, por lo tanto, una entidad conocida que puede ser manipulado para mantenimiento.
  3. Las API son escalables . Mientras que las API son extensibles por diseño, las integraciones están fundamentalmente limitadas en cuanto a lo que pueden hacer. Esto limita lo que el código realmente puede hacer a un ámbito limitado.
  4. Finalmente, las API encienden la innovación . Las API permiten la iteración sobre la base de código establecida, realizada en cooperación con la empresa. Por otro lado, una integración no es realmente una cooperación; puede haber casos en los que los equipos trabajen juntos, pero en esencia, este sigue siendo un proyecto definido y limitado por la propia empresa dentro de un conjunto de circunstancias extremadamente limitado. Esto no es una negociación, es un dictado.
También se pueden utilizar API de calidad 4 API que hacen que la experiencia del desarrollador sea realmente buena

Adaptarse al entorno empresarial: la mala solución

En muchos casos, resolver la desconfianza entre desarrolladores y administradores de empresas es solo la mitad de la respuesta. En otras palabras, la empresa no solo no confía en la API, a menudo considera que la implementación de la API es demasiado compleja , que pone demasiado en manos de un desarrollador externo y, lo que es más importante, un sistema que debe ser aprendido y entendido.

A menudo se considera que la documentación es la solución a este problema, pero en realidad es un síntoma. La única razón por la que se requeriría documentación (no se proporcionaría, pero sí) es si la API en sí es tan compleja o masiva que confirma los aspectos negativos percibidos por la empresa y, por lo tanto, es necesaria para su utilización. La documentación tiene un valor limitado para los equipos técnicos externos a los que intentamos convencer con la simplicidad de nuestras API e implementaciones. Como lo ve Switzer:

“Las personas con las que trabajamos [en el espacio empresarial] no se preocupan por la documentación. […] A los clientes simplemente les importa un bledo, y sus equipos de tecnología nunca lo usarán ".

Hacer una API autodescriptiva

Con todo esto en mente, podemos comenzar a ver el valor de la API autodescriptiva . Dicha API se hace entender a través de su uso . Cuando se aprovecha con materiales complementarios y se integra con estándares abiertos y comunes, la API casi se vende sola.

Entonces, ¿qué hace que una API sea autodescriptiva? ¿Cómo se puede moldear la API en una forma que no solo sea atractiva para la empresa, sino también preferible ?

Sea autodescriptivo en su respuesta de datos

Nuestro primer paso para hacer que una API sea autodescriptiva es permitir que se entienda dentro del contexto de sí misma. Es mucho lo que puede hacer para mejorar la respuesta de datos de una API para que los desarrolladores externos comprendan sus operaciones sin la necesidad de documentación y material educativo extensos. A continuación se muestra un ejemplo de la API Healthify , una API que maneja principalmente datos de salud.

"Item" :
	{
		"Href" : "https//api.healthify.us/patients/2324532",
		"Data" : [
		    {"name" : "id", "value" : 2324532, "type": "integer"},
		    {"name" : "name", "value" : "Kate McCallister", "type": "string"},
		    {"name" : "income", "value" :null, "type": "integer"},
		    {"name" : "address_street", "value" : "1 Lonely Way", "type": "string"},
		    {"name" : "address_city", "value" : "Chicago", "type": "string"},
			]
	}

En el ejemplo anterior, puede ver exactamente cuáles son los tipos de datos y cómo funcionan. La campos cada enlace a donde vive el recurso. Si bien no es detallado, no utilizamos comentarios ni notación, el contexto de la API se entiende en relación a sí mismo.

"La documentación de la API que más importa es la respuesta".

Nuestro objetivo final es simple: fomentar la confianza en nuestra API. La forma más eficaz de hacer esto con los desarrolladores empresariales es utilizar datos evidentes . Los desarrolladores externos deben comprender de inmediato lo que envía la API, dónde está el recurso y qué tipo de datos es el recurso.

Dicho esto, todavía hay un caso de uso para la documentación , especialmente cuando nuestra API se vincula con otras API y, en consecuencia, no necesariamente tenemos un control total sobre la forma en que describimos nuestros enlaces externos . Sin embargo, esta documentación no necesita estar seca y, en muchos casos, siempre que los datos estén bien definidos , será una nota a pie de página en la solución general en lugar de un factor que obstaculice la implementación.

Aproveche los estándares abiertos

Una gran parte de la ecuación empresarial también proporciona una solución que existe en su forma actual y es relativamente invariable . Esto no significa que no podamos agregar nuevas funciones, pero nuestra API debe ser confiable. Una de las mejores formas de garantizar la confiabilidad mientras se mantiene una plataforma abierta a la innovación es construir sobre estándares abiertos .

Los estándares abiertos son aquellos estándares comúnmente aceptados, valores conocidos que están probados y seguros. Los estándares abiertos comunes en el espacio de la API incluyen Open API , OAuth , JSON , Open ID Connect , SCIM y muchos otros.

Los estándares abiertos son similares a ver una película de una serie de películas históricas muy conocidas en lugar de ver una película desconocida de un director desconocido: sabes aproximadamente lo que obtendrás, y por eso, es más o menos un factor conocido.

Además, los estándares abiertos pueden resultar en un mayor nivel de seguridad , ya que estas soluciones están probadas y son verdaderas. A través de esta seguridad adicional y una adopción más amplia, los estándares abiertos también dan como resultado una mayor coherencia en toda la industria y, por lo tanto, elevan la oferta disponible a los ojos de la empresa.

Los estándares abiertos a menudo están en marcado contraste con la empresa, en la que las soluciones a menudo son autodefinidas y patentadas . Aprovechar los estándares autodefinidos e ignorar los estándares de la industria da como resultado un ecosistema lento e inoperable: la solución exacta que pretendemos solucionar con API autodescriptivas.

Lectura relacionada: Construir con estándares abiertos dará como resultado la longevidad de TI

Siga las mejores prácticas

Como una extensión del uso de estándares de la industria, también debemos impulsar las mejores prácticas y adherirnos a ellas religiosamente. Al hacerlo, se pueden evitar fallas y problemas comunes, asegurando así la extensibilidad y escalabilidad en la implementación a largo plazo de nuestra API. Todos los argumentos que se pueden hacer para adoptar los estándares de la industria son exactamente los mismos argumentos a favor de las mejores prácticas, así que para ahorrarnos una lección repetida, simplemente deberíamos decir esto: si no sigue las mejores prácticas, está creando un problema, y ​​aunque un problema puede ser manejable, a medida que se expanden, lo son menos.

Aprender las mejores prácticas para la manipulación de error API , API de versiones , y la documentación de la API

Beneficios de hacer que las API sean autodescriptivas

Nuestra razón principal para crear una API empresarial autodescriptiva es, como era de esperar, interactuar con la empresa. Dicho esto, hay numerosos beneficios de adoptar el proceso que deben mencionarse.

La adopción de una API autodescriptiva reduce el costo del soporte 1 a 1 . Al hacer que la API se describa a sí misma, no es necesario proporcionar soporte adicional porque la API se admite a sí misma. La necesidad de proporcionar un soporte extenso y gratuito disminuye a medida que la plataforma se vuelve más descriptiva. Si bien se puede proporcionar dicho soporte, a menudo se puede proporcionar mediante suscripción.

Adoptar esta filosofía de desarrollo de API significa que la experiencia del desarrollador es mucho mejor que la alternativa. Los usuarios desarrolladores no necesitan leer un compendio de documentación para intentar descifrar la intrincada red de llamadas, funciones y puntos finales. En una API autodescriptiva, es fácil descifrar cosas como la funcionalidad del método o el origen del error, ya que los datos están disponibles.

Finalmente, una API autodescriptiva crea un sistema flexible que se puede iterar sin introducir una complejidad increíble. Debido a que los datos se entienden en el contexto de sí mismos, agregar nuevas funciones y tipos de datos es bastante simple y puede entenderse como parte de un contexto mayor en lugar de entenderse de forma aislada y acompañada de documentación.

En pocas palabras, adoptar una API autodescriptiva tiene sentido en el espacio empresarial y crea un producto que se comprende, contextualiza e implementa fácilmente en el entorno empresarial relativamente estricto. Además de esto, se pueden obtener grandes beneficios que, en última instancia, dan como resultado una mejor experiencia para el desarrollador y, por lo tanto, una mejor API.

¿Qué opinas de este espíritu? ¿Existe una mejor manera de hacer que su API se entienda más fácilmente? Háganos saber a continuación en los comentarios.

Publicar un comentario

0 Comentarios