Header Ads Widget

Ticker

6/recent/ticker-posts

La evolución de la especificación OpenAPI: ¿OpenAPI significa mundo abierto?

 

Tras la fanfarria de su introducción a finales de 2015, la Iniciativa OpenAPI ya existe desde hace seis meses. Como se discutió en su blog, se ha logrado un gran progreso hacia la creación de la estructura de gobernanza que ayudará a que la Especificación OpenAPI (OEA) avance, incluido un hogar en GitHub que ha estado recopilando constantemente nuevos problemas para su consideración y posible inclusión en el próximo versión.

Uno de estos temas (ahora cerrados) , planteado por Darrel Miller, analiza si la OEA representa un contrato de mundo abierto . La escuela de pensamiento del Mundo Abierto permite a las personas hacer suposiciones con seguridad en el conocimiento de que no hay garantía de certeza: esto permite que las declaraciones se hagan sin que esas declaraciones impliquen una verdad absoluta. Esto se opone a los supuestos del mundo cerrado , que afirma que se ha demostrado que cualquier declaración es cierta antes de hacerse.

En el contexto de OAS, una especificación de API que se adhiera a un supuesto de mundo abierto, por lo tanto, solo describirá la API en sí y no necesariamente describirá todos los códigos de estado o comportamientos que el servidor HTTP que aloja la API podría mostrar o mostrar. En su conjunto, la descripción describe solo lo que se conoce y no todo lo que devolverá una API. Esencialmente (como lo sugiere Zdenek Nemec ), esto significa que una descripción de la API de OAS es una declaración de lo que un cliente debe obtener cuando llama a una API y, si la obtiene, lo que significa. La suposición inversa de mundo cerrado significaría que las descripciones de API son una declaración absoluta de API, con todos los comportamientos descritos y conocidos.

La principal ventaja del enfoque de mundo abierto es bastante obvia: evita caer en los agujeros de conejo restrictivos a los que condujeron protocolos como SOAP , en su lugar, utiliza un espíritu que implica extensibilidad desde el principio y permite diferencias en la implementación entre tecnologías y transportes. Los protagonistas que discuten el problema de GitHub claramente lo favorecen, pero mantener este enfoque en todos los problemas de la acumulación será más fácil de decir que de hacer. Los hemos examinado en un esfuerzo por juzgar si la próxima versión realmente promete ser un formato de mundo abierto.

Si desea leer esta publicación en línea con el backlog, use este enlace .

Soporte formal de HATEOAS

Uno de los aspectos más destacados del backlog es casi con certeza el número 577 , que analiza la posibilidad de incluir soporte formal para hipermedia como motor del estado (HATEOAS). HATEOAS es uno de los principios originales de REST definido por Fielding y describe un mecanismo para pasar el estado al cliente a través de hipermedia. HATEOAS podría describirse como el antipatrón de descripción de API: como el servidor proporciona el estado al cliente, por lo tanto, se describe a sí mismo sobre la marcha, con menos ímpetu para documentar los recursos por adelantado. Los problemas de GitHub en sí mismos describen esto en términos de una construcción "sin ruta", eliminando la tautología del uso de enlaces en las respuestas, pero también definiendo esos enlaces en la descripción de la API.

Si bien el soporte de HATEOAS indudablemente complacerá a muchas personas en la comunidad de API, no está claro si la introducción de esta función respaldará un contrato de mundo abierto. En un nivel práctico, y aunque los RESTafarians pueden argumentar lo contrario, implementar HATEOAS en una API tiende a ser en gran medida una cuestión de gusto y resonancia con la comunidad de desarrolladores para un tema determinado en lugar de "corrección técnica". Sin embargo, y lo que es más importante desde la perspectiva del mundo abierto, la necesidad de transmitir explícitamente el estado al cliente significa que la API está obligada en gran medida a transmitir una versión exacta y prescriptiva de la verdad, ya que sin este enfoque se corre el riesgo de quebrar al cliente. Al describir una API de HATEOAS, la descripción debe, por lo tanto, respaldar una versión prescriptiva y única de la verdad a la manera de un contrato de mundo cerrado.

Sin sumergirse en el diseño de un candidato en un esfuerzo por iterar a través del tema, a primera vista parece que la OEA debe, por lo tanto, respaldar un contrato de Mundo Cerrado hasta cierto punto para respaldar correctamente a HATEOAS. Si esto se puede hacer y seguir siendo coherente con un enfoque de mundo abierto dependerá en gran medida de qué tan inteligente se implemente. Sin embargo, dado que HATEOAS es una característica de la definición original de REST de Fielding que no es implementada de manera rutinaria por los desarrolladores de API, es probable que OAS pueda soportar los supuestos de Mundo Abierto y Cerrado simultáneamente.

Lea también: Qué significa la iniciativa API abierta para el espacio API

Respuestas de error estandarizadas

Las mejoras en el manejo de errores y las respuestas están presentes en todo el retraso de la OEA. De particular interés es el número 567 , que analiza la introducción de un diccionario de respuestas en el rango 400 y 500 de códigos de retorno HTTP que agrega información adicional en forma de un código (ya sea un número entero o una constante) y un mensaje. Si bien cualquier desarrollador agradecería esta función de estandarización como un dispositivo que ahorra trabajo, independientemente del debate sobre el mundo abierto, debe moderarse con precaución: hay muchas buenas razones para ser opaco, especialmente con los códigos de retorno no autorizados y prohibidos. Los profesionales de la seguridad cibernética argumentarían que no se debe devolver información adicional con dichos códigos, lo que introduce una interesante dicotomía entre seguridad y facilidad de uso..

En términos de OEA como un contrato de mundo abierto, este tema resalta el meollo del debate entre el deber y el deber : el manejo extendido de errores es excelente, pero para mantener la coherencia con la filosofía del mundo abierto, no debe ser prescriptivo y solo debe devolverse cuando sea práctico. y disponible. Por lo tanto, la información de error adicional debe considerarse un extra útil y sin duda será bienvenida por la mayoría de la comunidad de API. Si esta característica se puede implementar con la flexibilidad necesaria, el enfoque de mundo abierto también se puede mantener.

Estado del endpoint

Hay un par de problemas en la acumulación sobre el tema del estado del punto final que justifican una discusión en el contexto de un contrato de mundo abierto. Uno que aún no se ha marcado para la próxima versión es 608 , que describe un medio para marcar un punto final fuera de servicio: dado que una descripción de API es esencialmente un documento estático, este es un concepto interesante cuando se toma al pie de la letra. Sin embargo, si esto se considerara una característica para ser incluida en OEA, es muy probable que la implementación incorpore un punto final de estado, donde se puede obtener el estado de la API en sí.

Por supuesto, sería útil estandarizar este mecanismo dentro de la especificación de la OEA, pero probablemente sea la punta del iceberg para el tipo de datos que podría proporcionar un punto final de estado, que incluye:

  • Descubrimiento : encontrar la API y la descripción en primer lugar;
  • Capacidad : una definición del nivel de servicio ofrecido, incluidos los límites de tarifas, las horas de soporte, el costo, etc .;
  • Asunto : De qué se ocupa la API, por ejemplo, pagos, cambio de divisas, noticias, etc. Dichas clasificaciones, junto con las capacidades publicadas, permitirían que las API se busquen y utilicen de la mejor manera posible.

El espíritu de este número se presta a que la OEA sea un contrato de Mundo Abierto. Volviendo a la idea de lo que debería estar disponible, esto le da al consumidor de API una visión mucho mejor de lo que debería existir desde una perspectiva esquemática. Por el contrario, la implicación del tiempo de ejecución es que se trata de un concepto de mundo cerrado porque el punto final de estado dicta el estado de la API y el consumidor de API está obligado a obedecer el punto final de estado independientemente de si la API está realmente disponible o no. Por lo tanto, la implementación introduce muchos problemas prácticos que deberán considerarse cuidadosamente para garantizar que sigan siendo consistentes con el espíritu de un contrato de mundo abierto.

El número 433 presenta el concepto de agregar soporte para puntos finales privados y ocultos. La razón por la que se plantea este problema es que una descripción de API es una definición completa y homogénea que se puede adaptar a audiencias específicas en función de los atributos del documento. Claramente, esto se presta a un enfoque de mundo cerrado, ya que implica que todo debe definirse en la descripción de la API. Si prevalece un enfoque de mundo abierto, la implementación de esta función debe garantizar que la definición de puntos finales, ya sean públicos, privados u ocultos, no se defina como obligatoria.

Pensamientos finales

La cuestión de implementar un contrato de Mundo Abierto vs Mundo Cerrado puede parecer de naturaleza filosófica, pero tiene muchas implicaciones prácticas sobre cómo la OEA continúa evolucionando. Como mostramos en los problemas que hemos destacado, será difícil implementar funciones que respalden de manera constante un contrato de mundo abierto. Para la mayoría de los que contribuyeron al debate, parecería obvio que un contrato de mundo abierto ofrece la mayor flexibilidad y la mayor facilidad de uso, pero esto también conlleva el riesgo de no ser lo suficientemente específico. El enfoque de mundo cerrado, por otro lado, puede comenzar a reprimir la flexibilidad, pero puede ser más fácil de codificar dada su naturaleza didáctica.

En última instancia, un mínimo de sentido común del equipo que dirige la OEA aplicará las características correctas, ya sea que califiquen como Mundo Abierto o no. Si prevalece el sentido común, permitirá que la especificación continúe evolucionando y resuene en la comunidad de desarrolladores con el mismo grado de éxito que Swagger.

Publicar un comentario

0 Comentarios