tutorial - ¿Debería una API RESTful tener un esquema?

qué es una api rest y para qué sirve (3)

Debe definir y comunicar las interfaces de solicitud y respuesta a su API RESTful de alguna manera para que las personas que llaman puedan saber qué espera de la solicitud y qué pueden esperar en una respuesta.

API RESTful: esquema versus otra definición de interfaz

Ya sea que usted use un esquema (XSD, esquema JSON, etc.), o alguna otra forma (lenguaje natural, ejemplos, etc.), o alguna combinación para definir sus interfaces, depende de usted decidir. Aquí hay algunos factores para informar su decisión:

Qué tan conocido de una convención usará.
Esquema: XSD es un estándar W3C utilizado en muchas industrias; JSON Schema es la alternativa conocida a XSD para JSON.
Otro: el lenguaje natural y los ejemplos son viables y muy útiles, aunque a menudo ambiguos o incompletos.
Qué convención apreciará más tu comunidad.
Esquema: XSD especialmente tiende a ser apreciado más por las comunidades que ya han invertido en el desarrollo de XSD estándar para su industria.
Otro: el lenguaje natural y los ejemplos tienden a ser apreciados por los recién llegados.
¿Qué tan automatizable de un proceso de validación usará?
Esquema: tanto XSD como JSON Schema ofrecen una validación automatizada y lista para usar.
Otro: el lenguaje natural y los ejemplos requieren un esfuerzo especial para la validación.
Qué tan apretado o poco tipeado de una interfaz usarás.
Esquema: XSD y JSON pueden expresar un rango de especificidad de tipo pero brillar cuando se desea una especificidad de tipo detallada.
Otro: el lenguaje natural y los ejemplos pueden transmitir requisitos de tipo, aunque a menudo de forma imprecisa.

Consideraciones REST adicionales de la API

Finalmente, tenga en cuenta que tendrá más decisiones para hacer más allá del esquema versus el no esquema :

Cómo va a versionar las interfaces a lo largo del tiempo.
Qué estructura de URL HTTP, métodos, códigos de respuestas, etc. usarás.
Ya sea para administrar todas estas consideraciones al usar Swagger , RAML , Apiario , Apigee u otro marco de API.

Todos estos son partes importantes de la comunicación de su API REST para los llamantes de su servicio además del esquema frente a otra decisión de definición de interfaz.

Hace poco me dijeron que una API RESTful adecuada debería definir un esquema para las representaciones de recursos que acepta y devuelve. Por ejemplo, XSD para XML y JSON Schema para JSON.

Sin embargo, en todos los libros y artículos sobre REST que pasé por esto nunca me ha parecido prominente, sino incluso mencionado.

¿Podría alguien proporcionar algunos recursos autorizados para aclarar si deberíamos proporcionar un esquema al desarrollar API RESTful?

Debe documentar su API RESTful para quienes la usan. El esquema es más específico para cada formato de datos que se devuelve, lo que puede ser útil. Aquí hay ejemplos de referencias API que definen los métodos y formatos de respuesta muy bien:

La API de geocodificación de Google Maps (JSON y XML)

Referencia de la API HTTP de SoundCloud

Documentación de la API CloudFlare v4

API de búsqueda de Twitter

En su mayoría, lo que veo son métodos de solicitud documentados con ejemplos de respuesta mostrados y un cuadro que explica qué esperar (no tan a menudo un esquema formal por sí mismo). Haz que tenga sentido para los humanos.

Ellos son opcionales Si necesita un filtrado detallado de las solicitudes de los usuarios teniendo en cuenta tanto la sintaxis como la semántica de los contenidos, la utiliza.

Aquí hay una guía de RFC que menciona el esquema XML.

https://tools.ietf.org/html/rfc3470

"Esquema XML (definido en [41] y [42]) proporciona características adicionales para permitir una especificación más estricta y más precisa de la sintaxis del protocolo permitido y las especificaciones del tipo de datos".

Aquí está el borrador de IETF para el esquema JSON: https://tools.ietf.org/html/draft-zyp-json-schema-04

"JSON Schema proporciona un contrato para qué datos JSON se requieren para una aplicación determinada y cómo interactuar con él. El objetivo del esquema JSON es definir la validación, la documentación, la navegación de hipervínculos y el control de interacción de los datos JSON".

Como puede ver, IETF no aceptó esto como un RFC (todavía es un borrador). Pensaron que esto es demasiado para un protocolo simple como JSON. Sin embargo, muchos proyectos de código abierto se basan en este borrador.