Un breve análisis de las especificaciones de diseño de Open API

Recientemente, debido a las necesidades comerciales, el producto en la nube CSB Participé en las necesidades de investigación y desarrollo para abrir la API abierta al mundo exterior, lo cual no es algo difícil, porque el mecanismo abierto de API abierta dentro de Alibaba Cloud es muy maduro, y no No necesita diseñarlo en absoluto, pero esta vez la demanda es principalmente para algunos escenarios de implementación independientes, y necesita diseñar un conjunto de especificaciones, lo que significa que necesita hacer algunas especificaciones y restricciones en la API abierta, por lo que hay es este artículo.

La API abierta, como la página de inicio, siempre ha sido la cara del producto, y la API abierta no está estandarizada, lo que reducirá la profesionalidad del producto. En el escenario de la nube, muchos usuarios optarán por construir sus propios portales para acoplar la API abierta de los productos en la nube, lo que nos invita a construir un mecanismo de API abierta maduro.

Desde una perspectiva comercial, existen algunos principios rectores que nos guían para mejorar el mecanismo de API abierta:

  • La interfaz utilizada por la página de inicio y la interfaz proporcionada por la API abierta son el mismo conjunto de interfaces
  • Cualquier interfaz de página frontal debe tener una API abierta correspondiente

Desde un punto de vista técnico, existen muchos estándares de API ABIERTA para nuestra referencia, y la documentación de API abierta para algunos productos de código abierto también es muy completa. Por un lado, tomaré su esencia, por otro lado, debo considerar la particularidad de la forma de salida de mi propio producto. Este artículo se centrará en una serie de factores para tratar de explorar una especificación de API abierta adecuada.

 

Consideraciones de diseño de API abiertas

¿Qué debería regular exactamente una especificación de API abierta bien establecida?

Desde el punto de vista del diseño, es necesario considerar: especificación de nombres, especificación de composición, especificación de ruta, especificación de parámetros de acceso, especificación de tipo de datos, especificación de valor de retorno unificado, especificación de código de error, especificación de paginación.

Desde la perspectiva del equipo, si el desarrollo primario e intermedio de back-end y la investigación y desarrollo de front-end en el equipo tienen suficiente experiencia para comprender e implementar las especificaciones de API formuladas. Al mismo tiempo, con el flujo de personas, esta especificación de API abierta se puede transmitir bien.

Desde la perspectiva de la industria, es necesario considerar si el mercado donde el producto que proporciona Open API está maduro y si el estilo de API ya puede tener las especificaciones correspondientes.

Desde la perspectiva del producto, cada producto se ajusta a un estilo de API diferente, y esta perspectiva se destacará a continuación.

En resumen, el diseño de las API abiertas es algo difícil de aceptar, y antes de presentar las especificaciones de las API abiertas que finalmente adoptarán mis productos, primero hablaré sobre algunos conceptos familiares, como el descanso.

 

Batalla de normas tranquilas

Donde haya gente, habrá ríos y lagos.

Lo mismo es cierto donde hay código.

Si está en el ciclo de la codificación, ha oído hablar de la especificación tranquila:

  • Las adiciones, eliminaciones y correcciones deben declararse como: POST, DELETE, PUT, PATCH, GET

  • Los verbos no deberían aparecer y los verbos se representan uniformemente mediante métodos http.

  • Encarna la abstracción de “recursos”

  • Use pathVariable, queryParam, header, statusCode para expresar una gran cantidad de semántica comercial

La especificación relajante puede parecer hermosa, pero si realmente ha intentado aterrizar, seguramente encontrará algunos problemas similares:

  • Tomando como ejemplo la interfaz de inicio de sesión del usuario, dicha interfaz es difícil de asignar a la adición, eliminación, modificación y modificación de recursos.
  • Tomando como ejemplo la tasa de error de solicitud de interfaz en las últimas 7 horas de consulta, derivada de escenarios de consulta complejos como graphQL, a menudo requiere una estructura json, GET no puede lograr esto, solo se puede pasar POST

En base a esto, la especificación de descanso gradualmente tiene una objeción:

  • Obligar a que todo tenga "recursos" es contrario al sentido común del desarrollo, y es posible que la interfaz no se pueda mapear mediante simples adiciones, eliminaciones y correcciones.
  • Es posible que la semántica de consulta compleja no se exprese en GET

A los fanáticos del estilo tranquilo no les faltan críticas a estas objeciones, e inevitablemente hay declaraciones en la comunidad de que “las principales personas que rechazan el estilo tranquilo son arquitectos y programadores front-end de bajo nivel y poco emprendedores, que no diseñarán como un problema humano, no un problema normativo” y así sucesivamente. Al mismo tiempo, se sublima lo descansado: el problema de recuperación de parámetros complejos debe clasificarse como post en la semántica descansada, porque el comportamiento no es el posicionamiento del recurso (GET), sino la recuperación del recurso (POST)

Aparentemente, esto irritó los nervios de los opositores al estilo tranquilo, desdeñosamente: Oh, estúpidos fundamentalistas tranquilos.

¿No sabes si eres un partidario o un oponente de descanso? O, neutral.

La disputa sobre el descanso termina aquí por el momento, y esta controversia es puramente ficticia, y los funcionarios no deben preocuparse por ella. Independientemente de lo que pienses sobre el descanso, como analizo a continuación, puedes ser neutral, de lo contrario, el efecto se reduce a la mitad.

 

ROA frente a RPC

El diseño de API no es solo una especificación tranquila, en una perspectiva más amplia, el estilo de diseño de API principal en realidad se puede dividir en

  • Diseño orientado a los recursos, conocido como ROA (Arquitectura orientada a los recursos)
  • Diseño orientado a procesos, es decir, RPC (llamada a procedimiento remoto)

Restful es un ejemplo típico del estilo roA, y el estilo RPC es relativamente menos conocido, pero de hecho la mayor parte de la interfaz del sistema es estilo RPC, pero el concepto de estilo RPC es menos conocido.

Tome el CRUD del módulo de usuario como ejemplo, compare los siguientes dos estilos:

 

estilo ROA

Crear usuario (POST)

Request:
POST /users{"name": "kirito", "age": 18}
Response:
HTTP 201 Created
{"id": 1, "name": "kirito", "age": 18}

 

Usuario de consulta (GET)

Request:
GET /users/1
Response:
HTTP 200 OK
{"id": 1, "name": "kirito", "age": 18}

 

Consultar lista de usuarios (GET)

Request:
GET /usersResponse:HTTP 200 OK{[{"id": 1, "name": "kirito", "age": 18}], "next": "/users?offset=1"}

 

Crear/Modificar Usuario (PUT)

Request:
PUT /users/1
{"name": "kirito", "age": 19}
Response:
HTTP 200 OK
{"id": 1, "name": "kirito", "age": 19}

 

Modificar Usuario (PATCH)

Request:
PATCH /users/1
{"age": 20}
Response:
HTTP 200 OK
{"id": 1, "name": "kirito", "age": 20}

 

Borrar usuario

Request:
DELETE /users/1
Response:HTTP 204 No Content

El estilo ROA y las especificaciones de descanso ilustran lo mismo, y para facilitar su comparación con la interfaz de estilo RPC, estos son algunos de los puntos destacados del ejemplo anterior:

  • Usando los códigos de respuesta HTTP (200, 201, 204), se completa el mapeo de la semántica HTTP y la semántica comercial, y también aparece el flujo de excepción 404, 401, etc. (por razones de espacio, este artículo no presenta el flujo de excepción)
  • La sección PATCH modifica el recurso y el cuerpo de la solicitud es el contenido de la sección modificada; PUT crea/modifica un recurso, y el cuerpo de la solicitud es todo el contenido del nuevo recurso
  • id es el localizador de recursos, mientras que la edad, el nombre son atributos

 

estilo RPC

Crear usuario (POST)

Request:
POST /user/createUser{"name": "kirito", "age": 18}
Response:
HTTP 200 OK
{"code": 0, "message": "", "data": {"id": 1, "name": "kirito", "age": 18}}

 

Usuario de consulta (POST)

Request:
POST /user/getUser{"id": 1}
Response:
HTTP 200 OK
{"code": 0, "message": "", "data": {"id": 1, "name": "kirito", "age": 18}}

 

Consultar lista de usuarios (POST)

Request:
POST /user/listUsersResponse:HTTP 200 OK{"code": 0, "message": "", "data": {"user": [{"id": 1, "name": "kirito", "age": 18}], "next": "/user/listUsers?offset=1"}}

 

Modificar usuario (POST)

Request:
POST /user/modifyUser{"id": 1, "name": "kirito", "age": 19}
Response:
HTTP 200 OK
{"code": 0, "message": "", "data": {"id": 1, "name": "kirito", "age": 19}}

 

Modificar nombre de usuario (POST)

Request:
POST /user/modifyUserAge{"id": 1, "age": 20}
Response:
HTTP 200 OK
{"code": 0, "message": "", "data": {"id": 1, "name": "kirito", "age": 20}}

 

Borrar usuario

Request:
POST /user/deleteUser{"id": 1}
Response:
{"code": 0, "message": ""}

El estilo RPC no es como el estilo RESTFUL ROA, hay algunas normas convencionales, cada sistema de negocios en el aterrizaje, hay diferencias, así que aquí está solo la experiencia personal del autor, espero que los lectores puedan buscar puntos en común mientras se reservan las diferencias:

  • usuario es el nombre del módulo y no necesita ser usado en forma plural como el estilo ROA
  • En lugar de asignar CRUD a métodos http, los métodos HTTP usan POST de manera uniforme y los escenarios de consulta también pueden usar GET
  • El valor devuelto lleva código, mensaje y datos para mapear el estado de respuesta y la información de respuesta, generalmente usted mismo puede definir el código de estado del código, este artículo usa 0 para identificar el éxito de la solicitud, el mensaje es significativo solo cuando el negocio la respuesta falla y los datos representan el resultado de la respuesta empresarial

La elección de RPC y ROA requiere decisiones basadas en la situación comercial del producto en sí. Existen las siguientes pautas:

  • Las API con lógica empresarial compleja, el estilo RPC, deben usarse cuando no puede usar adiciones, eliminaciones, cambios y descripciones simples.
  • Si su negocio es parte de un estándar de la industria que requiere una API de estilo relajante o ROA para satisfacer sus necesidades comerciales, debe usar el estilo ROA.

AWS adopta principalmente el estilo RPC, Azure y Google utilizan principalmente el estilo ROA (descanso), y Alibaba Cloud OpenAPI admite RPC y ROA, principalmente RPC.

Aunque la norma es inocente, he visto muchos “hoyos” en el estilo ROA en la práctica:

  • Requerir recursos para ir primero, es decir, diseñar recursos primero y luego diseñar interfaces, lo que requiere mayores requisitos en el proceso de desarrollo de software.
  • Caso 1 de diseño de ROA incorrecto: cuando un servidor de aplicaciones como Tomcat procesa una solicitud HTTP para un método DELETE, no se le permite llevar un cuerpo de solicitud de forma predeterminada y debe habilitarse explícitamente, lo que genera un error de eliminación. (Este caso es un problema del diseñador, la escena de eliminación compleja no debe asignarse a DELELE, sino que debe cambiarse a POST, DELETE no debe llevar un cuerpo de solicitud)
  • Caso 2 de diseño de ROA incorrecto: los parámetros transportados en la ruta tranquila pueden causar problemas de coincidencia regulares, como el uso incorrecto del buzón como parámetro de ruta o un problema de conflicto con la coincidencia de ruta de varios niveles (este caso es un problema del diseñador, un escenario de consulta complejo, no debe asignarse a GET, pero debe cambiarse a POST, la ruta solo debe aparecer en el localizador de recursos, no en el atributo)
  • Con un código de respuesta de 404, es difícil distinguir si no existe una ruta real o no existe un recurso
  • No es propicio para escenarios como puertas de enlace de acoplamiento que requieren la configuración del reenvío de rutas

La especificación API abierta de CSB quiere cumplir con los siguientes requisitos:

  • Cuando la interfaz de diseño de desarrollo de back-end, hay una idea de diseño clara, no por si una interfaz se implementa con POST o GET, y no dedica demasiado tiempo a la abstracción de recursos (esto no quiere decir que los recursos no no necesita ser diseñado)
  • Cuando el front-end desarrolla la interfaz de acoplamiento, puede cooperar con el back-end con relativa rapidez y conduce a la encapsulación de la interfaz del front-end.
  • Cuando los usuarios se conectan a la API abierta, el estilo general es consistente y los módulos son claros

En resumen, en cuanto a la selección del estilo de diseño, planeo adoptar las especificaciones de diseño de RPC. Para resumir las ventajas del estilo RPC:

  • El diseño de API es menos difícil y fácil de aterrizar
  • La mayoría de los productos de capa IAAS maduros de Alibaba Cloud utilizan la especificación RPC
  • Adecuado para escenarios de negocios complejos

 

Un ejemplo detallado de la documentación de la interfaz RPC

Crea un servicio

Parámetros de solicitud

Se requiere UpstreamType=fixed, ejemplo: [{“host”: “1.1.1.1”,”port”: “80”,”weight”: “1”}]

 

Se requiere el nombre en el registro, upstreamType=discovery

 

número de serie El nombre chino el campo. El nombre en inglés del campo. tipo de datos Requerido ilustrar
1 nombre nombre cadena be Nombre para mostrar
2 acuerdo protocolo cadena be Valor de enumeración: http/grpc/webservice
3 Balanceo de carga lb cadena be Valor de enumeración: random/roundrobin
4 tipo aguas arriba upstreamType cadena be Valor de enumeración: fijo/descubrimiento
5 Lista de nodos nodos matriz no
6 Identificación de la fuente Origen Identificación cadena no
7 el nombre del servicio Nombre del Servicio cadena no
8 Descripción del servicio descripción cadena no
9 Identificación de la puerta de enlace ID de puerta de enlace cadena be

 

Devuelve el parámetro

 

número de serie El nombre chino el campo. El nombre en inglés del campo. tipo de datos ilustrar
1 Código de respuesta código int 0 marcado como exitoso; 1 Identidad fallida
2 Información de respuesta mensaje cadena
3 Resultados de respuesta datos cadena Devuelve la identificación del servicio

 

Solicita un ejemplo

POST /service/createService
Request:{"name": "httpbin",
"protocol": "http",
"lb": "random",
"upstreamType": "fixed",
"nodes": [
{"host": "httpbin.org",
"port": "80",
"weight": "1"
}],"gatewayId": "gw-1qw2e3e4"
}Response:{"code": 0,
"message": "",
"serviceId": "s-1qw2e3e4"
}

 

Convenciones de nomenclatura de API

  • Las API deben usar inglés deletreado y cumplir con las especificaciones gramaticales, incluidas las convenciones de singular y plural, tiempo y lenguaje.

  • No puede tener varias API con significados similares pero sin diferencias prácticas en la funcionalidad, como /user/getUser y /user/describeUser

  • Hábitos lingüísticos: Prohibido el uso del pinyin

  • Las convenciones de nomenclatura para los siguientes escenarios comunes son fijas

    • Los parámetros del tipo de fecha y hora deben llamarse xxxxTime. Por ejemplo: CreateTime
  • Especificación de nombre de operación común

    • crear: crear
    • modificar: Cambiar
    • eliminar: Eliminar
    • get: Obtener los detalles de un solo recurso
    • list: Obtiene una lista de recursos
    • establecerRelación: establecer relaciones de recursos
    • destroyRelation: Destruye relaciones de recursos

 

resumen

Tome una especificación defendida en este artículo como ejemplo: "Todas las interfaces usan POST", que no es para adaptarse a arquitectos y programadores front-end poco emprendedores de bajo nivel (lo vi en el foro de la comunidad), sino para mejorar la eficiencia del desarrollo, reducir la comunicación costos, reducir los costos de operación y mantenimiento y posicionamiento incorrecto, e invertir el costo de lanzar a ciegas en otros campos, como el diseño de arquitectura empresarial, los sistemas de prueba, el monitoreo en línea, la recuperación ante desastres y la degradación.

La especificación de la interfaz no es lo que resumí, solo RPC y ROA, hay algunos comentarios que clasifican a GraphQL como un estilo de diseño de API independiente para escenarios de consulta complejos, los estudiantes interesados ​​pueden consultar la documentación de la API de es.

En resumen, planeo adoptar el estilo de diseño de API de RPC.

Se el primero en comentar

Deje un comentario

Tu dirección de correo electrónico no será publicada.


*