Convenciones de diseño de API RESTful

El propósito de escribir este artículo es acordar tanto como sea posible el estilo de diseño de API RESTful de los productos, componentes y desarrollo de proyectos de una empresa, de modo que los estilos de API diseñados por diferentes equipos sean lo más consistentes posible. posible, y para reducir el riesgo de problemas de especificación o problemas en las últimas etapas del proyecto, desarrollo y pruebas de retrabajo causados ​​por la reconstrucción de la interfaz causada por un diseño insuficiente. En última instancia, los usuarios finales de la interfaz pueden tener una buena experiencia durante el proceso de desarrollo.

Esta convención se puede utilizar como referencia para que los desarrolladores diseñen interfaces RESTful o revisen las versiones de interfaces de proyectos.

Opinión personal: Usar JSON-RPC no significa que sea una API RESTful. La API RESTful generalmente se implementa en base a HTTP/JSON. Ambos métodos de diseño de API son buenos. proyecto. Una comparación simple es la siguiente:

Este artículo es solo una convención de diseño de API RESTful recopilada y resumida por el autor en función de sus preferencias subjetivas y experiencia en diseño de interfaces. Solo se utiliza como un requisito básico para el diseño de interfaces. , y todos son bienvenidos a discutirlo. Este acuerdo no cubre contenido de hipertexto relacionado con HATEOAS, ni incluye el alcance de las interfaces de mapeo de clases RPC para métodos de servicio back-end.

La API es la cara (UI) de la aplicación back-end y la experiencia del usuario es muy importante. Especialmente cuando está desarrollando un componente o producto reutilizable, si hay fallas leves en el diseño de la API, afectará directamente la experiencia del desarrollador y el diseñador será regañado... Una vez que se abre la API problemática, incluso si es Simple Los errores ortográficos, que no se pueden eliminar para mantener la compatibilidad, se convertirán en una deuda técnica que se cargará durante mucho tiempo.

Los puntos clave anteriores no solo son aplicables a las API RESTful, sino también a otros tipos de API.

Como API RESTful lanzada al público, la URL raíz generalmente requiere el nombre de dominio y la información de la versión. Por lo general, un sitio WEB proporcionará tanto servicios de sitio web como servicios API. Necesitamos poder distinguir según la URL si el acceso es la interfaz del servicio o las páginas web, archivos y otros recursos del sitio web. Por lo tanto, la URL raíz de una API RESTful generalmente contiene la palabra clave api en el nombre de dominio de primer nivel o en el nombre de subdominio según diferentes escenarios.

Los dos usos comunes de la URL raíz son los siguientes:

La solución recomendada es utilizar nombres de subdominio en la URL raíz para distinguir las API, es decir: /api/v1/*

El final de la ruta está en negrita: https:// example.org/api/v1/ menus

Los métodos HTTP comúnmente utilizados al diseñar API RESTful incluyen: GET, POST, PUT, PATCH, DELETE Una breve explicación es la siguiente:

Cuando un recurso se puede ubicar de forma única según el identificador del recurso, se recomienda utilizar parámetros de ruta URL para pasarlo. Corresponde a @PathVariable de Springboot. Los ejemplos de ruta API son los siguientes:

Al consultar y filtrar uno o más recursos en función de los atributos del recurso, se recomienda utilizar parámetros de consulta URL para pasar. Corresponde a @RequestParam de Springboot. Los ejemplos de ruta API son los siguientes:

Para interfaces de consulta simples, puede usar parámetros de ruta y parámetros de consulta. Si se trata de una interfaz de consulta funcional compleja que requiere condiciones de filtrado complejas, como: > < en el medio. etc., etc. Los parámetros de consulta son muy difíciles de usar y el método GET no admite el envío de parámetros del cuerpo de la solicitud. Por lo tanto, recomiendo que esta consulta compleja se envíe a una ruta específica utilizando el método POST. Consulte el siguiente escenario:

Cuando la interfaz de consulta devuelve varios datos, debe admitir la paginación (excepto datos enumerados o una pequeña cantidad de datos) y clasificación.

Si necesita utilizar consultas y clasificación de paginación, se recomienda unificar la estructura del mensaje de solicitud y respuesta. El formato es el siguiente:

Ejemplo de parámetros de solicitud:

GET /users?page =1&size=5&sort=nombre de usuario

Ejemplo de resultado de respuesta de datos de una sola página:

La clasificación de paginación y el formato del mensaje de respuesta anteriores son del modelo definido por Spring Data Para mantener los hábitos de uso relevantes de la interfaz de clasificación de paginación, si no se usa JPA para la persistencia, aún se recomienda usar la interfaz de encapsulación de definición de mensajes estándar mencionada anteriormente. Proporcionar a los usuarios una experiencia consistente.

Si el recurso necesita realizar algunas operaciones además de agregar, eliminar y modificar (como cambios de estado), puede usar /acciones como ruta

Por ejemplo: procesar instancias en la plataforma del proceso tendrá cambios de estado como inicio, suspensión, recuperación, terminación, etc., se recomienda que esta interfaz esté diseñada así:

Recursos combinados, es decir, existe una relación de combinación entre ellos. dos recursos La combinación se refiere a la fuerte relación de inclusión entre el todo y la parte, pero El todo y las partes son inseparables El final del ciclo de vida del todo significa el final del ciclo de vida de las partes. Las operaciones en "partes" siempre utilizarán el todo como punto de entrada y no omitirán directamente el "todo" para agregar, eliminar, modificar o verificar las "partes". En este escenario combinado, los ejemplos de métodos de diseño de API recomendados son los siguientes:

Recursos agregados, es decir, existe una relación de agregación entre dos recursos. La agregación también es una relación de inclusión débil entre el todo y la parte, pero el todo y la parte son separables. Pueden tener sus propios ciclos de vida. Las partes pueden pertenecer a múltiples objetos sujetos diferentes y también pueden ser compartidas por múltiples objetos completos. .

Por ejemplo, si una organización o rol contiene personas y es necesario obtener el personal bajo esa organización o rol, evite realizar interfaces repetidas con funciones similares, como buscar personas a través de la entrada de la organización o del rol. :

p>

En el diseño de API RESTful, se recomienda distinguir situaciones normales y anormales a través del estado acordado por HTTP. No se recomienda utilizar la llamada al método POST para todas las interfaces y siempre regresar. 200.

La descripción del estado Http recomendada comúnmente utilizada es la siguiente:

Referencia de descripción detallada del estado HTTP 1.0

Después de que la llamada API sea exitosa, el código de estado HTTP 2xx se devuelve y el cuerpo de la respuesta se devuelve directamente solo datos comerciales. Se recomienda que los mensajes de solicitud y respuesta estén en formato JSON.

La API RESTful necesita estandarizar y unificar los mensajes de excepción. Cuando ocurre una excepción en el servidor, debe interceptarse globalmente y luego la información de la excepción se encapsula en un formato estandarizado y se devuelve al final de la llamada.

Para obtener información sobre excepciones de back-end, se recomienda incluir codificación y mensajes.

Este artículo se basa en el estudio de artículos relacionados con el diseño RESTful de varios expertos, combinados con mis propias soluciones para Confusiones encontradas al diseñar interfaces Plan, recopilación y resumen de convenciones de diseño de API REST. Parte del contenido está mezclado con preferencias personales y opiniones subjetivas, y espero que pueda ayudar a todos a diseñar API. Si encuentra escenarios más complejos más adelante, no dude en comunicarse juntos.