RESTful (estilo REST) es un modelo de arquitectura de software de Internet popular en la actualidad. Utiliza completa y correctamente las características del protocolo HTTP y nos proporciona un conjunto de métodos de adquisición de recursos unificados, para realizar la conexión entre diferentes terminales (cliente y servidor) acceso e interacción de datos.

¿Qué es REST?

Cuando se trata de REST, podemos pensar en la palabra inglesa rest (que significa: descansar, relajarse, etc.), pero REST aquí es en realidad la abreviatura de Transferencia de estado de representación de recursos, traducida al chino como "transferencia de estado de representación de recursos de capa de representación". .

REST fue propuesto por el Dr. Roy Thomas Fielding en un documento sobre el estilo de la arquitectura de software escrito en el año 2000. ¡Tan pronto como salió este documento, fue impactante! Cada vez más empresas de Internet en el país y en el extranjero están adoptando el estilo REST para desarrollar servicios web Estamos acostumbrados a llamar a los servicios web desarrollados utilizando el estilo REST RESTful Web Services, o servicios REST para abreviar.

Fielding es una persona muy importante, es el diseñador principal del protocolo HTTP (versión 1.0 y 1.1), uno de los autores del software del servidor Apache y el primer presidente de la Fundación Apache. Por lo tanto, una vez que se publicó su artículo, atrajo la atención e inmediatamente tuvo un profundo impacto en el desarrollo de Internet.
Presentó el propósito de escribir el artículo de la siguiente manera:
"Este artículo estudia la intersección de las dos fronteras de la informática: el software y la red. Durante mucho tiempo, la investigación del software se ha centrado principalmente en la clasificación del diseño del software y la evolución del diseño. métodos. Evaluar objetivamente el impacto de diferentes opciones de diseño en el comportamiento del sistema. En contraste, la investigación de redes se centra en los detalles del comportamiento de comunicación entre sistemas y cómo mejorar el rendimiento de mecanismos de comunicación específicos, a menudo ignorando el hecho de que cambiar la interacción de las aplicaciones El estilo tiene un mayor impacto en el rendimiento general que cambiar el protocolo de interacción. El propósito de escribir este artículo es comprender y evaluar el diseño arquitectónico del software de aplicación basado en la web con la premisa de cumplir con los principios arquitectónicos y obtener una funcional Una arquitectura sólida, de alto rendimiento y fácil de comunicar".
Mi trabajo está motivado por el deseo de comprender y evaluar el diseño arquitectónico del software de aplicación basado en la red mediante el uso de principios de las restricciones arquitectónicas, obteniendo así las propiedades funcionales, sociales y de rendimiento deseadas de una arquitectura. )

Podemos entender REST desde las siguientes tres perspectivas.

1. Recurso

Cuando implementamos un proyecto web en un servidor (como Tomcat), todo el contenido de este proyecto se puede llamar recursos en este servidor. Puede ser una clase, un archivo HTML, un archivo CSS, un archivo JS, una tabla en una base de datos, un fragmento de texto, una imagen, un fragmento de audio, etc. Todos pueden llamarse recursos. Se puede considerar que el servidor está compuesto por muchos recursos discretos.

Estos recursos tienen una característica común, es decir, pueden ser identificados por un URI (Uniform Resource Identifier), y cualquier operación sobre el recurso no puede cambiar su URI. Para obtener este recurso, simplemente visite su URI.

2. Representación (expresión de recursos)

La expresión de un recurso se refiere a la descripción del estado del recurso en un momento específico, es decir, la manifestación específica del recurso, que puede tener múltiples formatos, como HTML, XML, JSON, texto plano, imágenes, videos. , audios, etc. Por lo general, los recursos del lado del servidor y del lado del cliente suelen expresarse en diferentes formatos. Por ejemplo, el recurso del lado del servidor puede ser un fragmento de texto sin formato en la base de datos, un archivo XML o una tabla en la base de datos, mientras que el El cliente final puede representarse como páginas HTML, JSON o incluso audio y video.

3. Transferencia estatal (transferencia estatal)

La llamada transferencia de estado de recursos, en pocas palabras, es el proceso de convertir recursos de una forma de representación a otra cuando el cliente interactúa con el servidor. Sin embargo, el protocolo HTTP es un protocolo sin estado y no puede guardar ningún estado. Por lo tanto, si el cliente desea obtener un recurso en el servidor, debe usar algún medio para hacer que el recurso "transición de estado" en el servidor. la transición se basa en la capa de presentación (UI) de la aplicación. Esto es lo que significa "transferencia de estado de recursos de la capa de representación".

REST en realidad describe una forma de interacción entre el servidor y el cliente. REST en sí mismo no es un concepto práctico. Lo realmente práctico es cómo diseñar una interfaz RESTFul (estilo REST), es decir, qué medios usamos para hacer que los recursos estén disponibles. en el servidor? Al final se produce una transición de estado.

Sosegado

En el desarrollo de proyectos tradicionales, generalmente escribimos los verbos para los recursos operativos en la URL, y estos verbos generalmente los definimos nosotros mismos, y no existe una especificación unificada. Shakespeare dijo: Hay mil Hamlets a los ojos de mil personas.Esta frase no puede ser más apropiada aquí. Incluso para la misma operación en el mismo recurso, las URL definidas por diferentes personas son diferentes.

Por ejemplo, la misma solicitud para obtener información del usuario a través de la identificación del usuario, la URL puede estar en los siguientes formularios.

http://localhost:8080/biancheng/getUserById?id=1
http://localhost:8080/biancheng/user/getById?id=1
http://localhost:8080/biancheng/getUserInfo?id=1
http://localhost:8080/biancheng/a/b?id=1

RESTFul aboga por que usemos un estilo unificado para diseñar URL, y sus reglas son las siguientes.

Las URL se usan solo para identificar y ubicar recursos y no deben contener verbos relacionados con acciones. Por ejemplo, al acceder a recursos relacionados con un usuario (usuario), se puede definir su URL en el siguiente formulario.

http://localhost:8080/biancheng/user

Cuando es necesario incluir parámetros en la solicitud, RESTFul nos permite unir los parámetros en la URL a través de una barra inclinada (/) y enviarlos al servidor como parte de la URL, en lugar de usar signos de interrogación (?) para unir la clave. -pares de valores como antes La forma de llevar parámetros, el ejemplo es el siguiente.

http://localhost:8080/biancheng/user/1

Nota: Pasamos un parámetro con un valor de 1 en forma de "/1" al final de la URL.

Hay cuatro verbos en el protocolo HTTP: GET, POST, PUT y DELETE, que corresponden a cuatro operaciones básicas relacionadas con los recursos: GET se usa para obtener recursos, POST se usa para crear nuevos recursos y PUT se usa para actualizar recursos. DELETE se utiliza para eliminar recursos. A través de estos cuatro verbos, el cliente puede realizar la descripción de la transferencia de estado de recursos del lado del servidor.

operación de recursos	URL tradicional	URL RESTANTE	Método de solicitud HTTP
Obtener recurso (SELECCIONAR)	http://localhost:8080/biancheng/getUserById?id=1	http://localhost:8080/biancheng/usuario/1	CONSEGUIR
Guardar o agregar recursos (INSERTAR)	http://localhost:8080/biancheng/saveUser	http://localhost:8080/biancheng/usuario	CORREO
modificar o actualizar un recurso (ACTUALIZAR)	http://localhost:8080/biancheng/updateUser	http://localhost:8080/biancheng/usuario	PONER
eliminar recurso (DELETE)	http://localhost:8080/biancheng/deleteUser?id=1	http://localhost:8080/biancheng/usuario/1	BORRAR

Mejores prácticas RESTful y detalles de diseño

Sus grandes principios son fáciles de entender, pero los detalles no son fáciles de acertar. Este artículo resume los detalles de diseño de RESTful y presenta cómo diseñar una API que sea fácil de entender y usar.

1. Solicitar Diseño

1.1 Verbo + objeto

La idea central de RESTful es que las instrucciones de operación de datos emitidas por el cliente estén todas en la estructura de "verbo + objeto". Por ejemplo, GET /articleseste comando GETes un verbo y /articlesun objeto.

Los verbos suelen ser cinco métodos HTTP, correspondientes a las operaciones CRUD.

OBTENER: leer (Leer)

POST: Crear

PONER: Actualizar

PARCHE: Actualizar (Update), generalmente una actualización parcial

ELIMINAR: borrar (Borrar)

De acuerdo con la especificación HTTP, los verbos siempre se escriben con mayúscula.

1.2 Cobertura verbal

Algunos clientes solo pueden usar GETy POSTestos dos métodos. El servidor debe aceptar POSTla burla de los otros tres métodos ( PUT, PATCH, DELETE).

En este momento, la solicitud HTTP enviada por el cliente debe agregar X-HTTP-Method-Overrideatributos para decirle al servidor qué verbo usar y anular POSTel método.

POST /api/Person/4 HTTP/1.1  
X-HTTP-Method-Override: PUT

En el código anterior, X-HTTP-Method-Overrideel método para especificar esta solicitud PUTno es POST.

1.3 El objeto debe ser un sustantivo

El objeto es la URL de la API, sobre la que actúa el verbo HTTP. Debe ser un sustantivo, no un verbo. Por ejemplo, /articlesesta URL es correcta, pero las siguientes URL no son sustantivos, por lo que todas son incorrectas.

/getAllCars

/crearNuevoCoche

/eliminarTodosLosCochesRojos

1.4 URL en plural

Dado que las URL son sustantivos, ¿deberían ser plurales o singulares?

No existe una regla uniforme para esto, pero una operación común es leer una colección, como GET /articles(leer todos los artículos), donde obviamente debería estar en plural.

En aras de la uniformidad, se recomienda utilizar URL en plural, como GET /articles/2mejor que GET /article/2.

1.5 Evite las URL de varios niveles

Una situación común es que los recursos requieren una clasificación de varios niveles, por lo que es fácil escribir direcciones URL de varios niveles, como obtener una determinada categoría de artículos de un determinado autor.

GET /authors/12/categories/2

Este tipo de URL no es propicio para la expansión y la semántica no es clara. Toma un tiempo entender el significado.

Mejor aún, todos menos el primer nivel se expresan en cadenas de consulta.

GET /authors/12?categories=2

Aquí hay otro ejemplo, consultando artículos publicados. Puede diseñar en la URL a continuación.

GET /articles/published

La cadena de consulta está significativamente mejor escrita.

GET /articles?published=true

2. Código de estado de respuesta

2.1 El código de estado debe ser exacto

Para cada solicitud del cliente, el servidor debe responder. La respuesta incluye dos partes: código de estado HTTP y datos.

Un código de estado HTTP es solo un número de tres dígitos dividido en cinco categorías.

1xx:Información relacionada

2xx:Operación exitosa

3xx: redirigir

4xx: error del cliente

5xx:Error del Servidor

Estas cinco categorías contienen un total de más de 100 códigos de estado, que cubren la mayoría de las situaciones que se pueden encontrar. Cada código de estado tiene una interpretación estándar (o acordada), y el cliente puede determinar qué sucedió con solo mirar el código de estado, por lo que el servidor debe devolver el código de estado lo más preciso posible.

La API no requiere 1xxcódigos de estado. A continuación se describen los significados precisos de los otros cuatro tipos de códigos de estado.

2.2 Código de estado 2xx

200El código de estado indica que la operación fue exitosa, pero diferentes métodos pueden devolver códigos de estado más precisos.

OBTENER: 200 OK

POST: 201 Creado

PONER: 200 OK

PARCHE: 200 OK

ELIMINAR: 204 Sin contenido

En el código anterior, POSTel 201código de estado de retorno indica que se ha generado un nuevo recurso; DELETEel 204código de estado de retorno indica que el recurso ya no existe.

Además, 202 Acceptedel código de estado indica que el servidor recibió la solicitud, pero aún no la procesó y la procesará en el futuro, lo que generalmente se usa para operaciones asíncronas. A continuación se muestra un ejemplo.

HTTP/1.1 202 Accepted

{
  "task": {
    "href": "/api/company/job-management/jobs/2130040",
    "id": "2130040"
  }
}

2.3 Código de estado 3xx

La API no utiliza 301códigos de estado (redireccionamiento permanente) ni 302códigos de estado (redireccionamiento temporal, 307que también significa esto), porque pueden ser devueltos por el nivel de la aplicación, y el navegador saltará directamente, y el nivel de la API puede ignorar estas dos situaciones. .

Los códigos de estado utilizados por la API 3xx, principalmente 303 See Other, se refieren a otra URL. Tiene el mismo significado que 302y 307, y también es una "redirección temporal", la diferencia es que 302y 307se usan para solicitudes , GETy 303se usan para solicitudes y . Después de recibirlo , el navegador no saltará automáticamente, sino que dejará que el usuario decida qué hacer a continuación. A continuación se muestra un ejemplo.POSTPUTDELETE303

HTTP/1.1 303 See Other
Location: /api/orders/12345

2.4 Código de estado 4xx

4xxEl código de estado indica un error del cliente, que incluye principalmente los siguientes tipos.

400 Bad Request: El servidor no entendió la solicitud del cliente y no la procesó.

401 Unauthorized: el usuario no proporcionó credenciales de autenticación o no fue autenticado.

403 Forbidden: el usuario está autenticado, pero no tiene los permisos necesarios para acceder al recurso.

404 Not Found: El recurso solicitado no existe o no está disponible.

405 Method Not Allowed: El usuario está autenticado, pero el método HTTP utilizado no está bajo su autoridad.

410 Gone: El recurso solicitado ha sido transferido desde esta dirección y ya no está disponible.

415 Unsupported Media Type: No se admite el formato de devolución solicitado por el cliente. Por ejemplo, la API solo puede devolver el formato JSON, pero el cliente solicita devolver el formato XML.

422 Unprocessable Entity: el archivo adjunto cargado por el cliente no se puede procesar, lo que provoca que la solicitud falle.

429 Too Many Requests: El número de solicitudes de clientes supera el límite.

2.5 Código de estado 5xx

5xxEl código de estado indica un error del servidor. En términos generales, la API no revelará los detalles del servidor al usuario, por lo que solo dos códigos de estado son suficientes.

500 Internal Server Error: La solicitud del cliente era válida, pero ocurrió una excepción mientras el servidor la procesaba.

503 Service Unavailable: El servidor no puede procesar la solicitud, generalmente utilizada para el estado de mantenimiento del sitio web.

3. Cuerpo de respuesta

3.1 No devolver texto sin formato

El formato de datos devuelto por la API no debe ser texto sin formato, sino que debe ser un objeto JSON, porque solo de esta manera se pueden devolver datos estructurados estándar. Por lo tanto, Content-Typeel atributo del encabezado HTTP de la respuesta del servidor debe establecerse en application/json.

Cuando el cliente solicita, también debe decirle claramente al servidor que puede aceptar el formato JSON, es decir, ACCEPTel atributo del encabezado HTTP de la solicitud también debe establecerse en application/json. A continuación se muestra un ejemplo.

GET /orders/2 HTTP/1.1 
Accept: application/json

3.2 Cuando ocurre un error, no devuelva un código de estado 200

Un enfoque inapropiado es devolver el 200código de estado incluso si se produce un error y colocar la información del error en el cuerpo de datos, como se muestra a continuación.

HTTP/1.1 200 OK
Content-Type: application/json{
  "status": "failure",
  "data": {
    "error": "Expected at least two items in list."
  }
}

En el código anterior, después de analizar el cuerpo de datos, podemos saber que la operación falló.

Este enfoque en realidad cancela el código de estado, lo cual es completamente indeseable. El enfoque correcto es que el código de estado refleje el error que ocurrió y la información específica del error se devuelva en el cuerpo de datos. A continuación se muestra un ejemplo.

HTTP/1.1 400 Bad Request
Content-Type: application/json{
  "error": "Invalid payoad.",
  "detail": {
     "surname": "This field is required."
  }
}

3.3 Proporcionar enlaces

Es posible que los usuarios de la API no sepan cómo está diseñada la URL. Una solución es proporcionar enlaces relevantes en la respuesta para facilitar el siguiente paso. De esta forma, los usuarios solo necesitan recordar una URL para descubrir otras URL. Este método se llama HATEOAS.

Por ejemplo, las API de GitHub están todas en el nombre de dominio api.github.com. Al visitarlo, puede obtener otras URL.

{
  ...
  "feeds_url": "https://api.github.com/feeds",
  "followers_url": "https://api.github.com/user/followers",
  "following_url": "https://api.github.com/user/following{/target}",
  "gists_url": "https://api.github.com/gists{/gist_id}",
  "hub_url": "https://api.github.com/hub",
  ...
}

En la respuesta anterior, si elige una URL para visitar, puede obtener otras URL. Para los usuarios, no necesitan recordar el diseño de la URL, solo necesitan buscar paso a paso desde api.github.com.

El formato de HATEOAS no es uniforme, en el ejemplo anterior, GitHub los junta con otros atributos. Mejor aún, separe los enlaces relacionados de otros atributos.

HTTP/1.1 200 OK
Content-Type: application/json{
  "status": "In progress",
   "links": {[
    { "rel":"cancel", "method": "delete", "href":"/api/status/12345" } ,
    { "rel":"edit", "method": "put", "href":"/api/status/12345" }
  ]}
}

Referencia:
http://c.biancheng.net/spring_mvc/9675.html
https://www.ruanyifeng.com/blog/2011/09/restful.html

[API] ¿Qué es RESTful? Solo lee un artículo