tutorial oas form example collectionformat body api rest mime-types

api - oas - swagger parameters in body



Tipos MIME del proveedor(para versiones de API) (1)

Como he decidido seguir el estándar jsonapi.org , decidí hacer exactamente lo que muestra su ejemplo.

En cuanto a tus preguntas:

  1. Su tipo MIME debe estar registrado
  2. Creo que cada versión y tipo debe estar registrado, ya que son tipos únicos
  3. x- prefijo x- ha quedado en desuso como se indica en un comentario
  4. application/json-v2 no sería válido
  5. Podría devolver 415 Unsupported Media Type o simplemente 400 Bad Request

He leído muchas de las publicaciones de Desbordamiento de pila (y otras) sobre el control de versiones de los servicios RESTful. Es un poco abrumador, para ser honesto.

Decidí usar un encabezado Aceptar: para nuestro servicio RESTful (marginalmente) para que los clientes puedan solicitar versiones específicas de un recurso. Lo que no tengo claro es qué especificar en el encabezado Aceptar.

El ejemplo que he visto a menudo es este:

Accept: application/vnd.mycompany.myapp.customer-v2+json

Mis preguntas son:

  1. ¿Estoy en lo correcto al indicar que todos los tipos vnd deben estar registrados? ( http://www.iana.org/cgi-bin/mediatypes.pl )

  2. ¿Es la versión y el tipo (es decir, -v2 + json) parte del tipo y, por lo tanto, cada versión y tipo debería estar registrado?

  3. ¿Hay alguna razón para usar vnd en lugar de un subtipo "x-" que no necesita ser registrado? Por ejemplo:

    Accept: application/x-mycompany.myapp-v2+json

    La API existente es solo interna, pero en el futuro estará expuesta a los clientes.

  4. No estoy seguro de que esto tenga sentido, pero ¿es posible usar un tipo existente pero agregar una versión? (La API actual devuelve "application / json")

    Accept: application/json-v2

  5. ¿Cuáles son los formatos aceptables para agregar una versión y tipo (por ejemplo, -v2 + json).

  6. ¿Qué ocurre si un cliente solicita una versión no compatible? ¿La respuesta correcta es 406? ¿Puede el cliente solicitar alguna versión? O, en términos más generales, ¿qué sucede si el cliente no proporciona un encabezado Aceptar o Aceptar: * / *?

Cualquier sugerencia adicional bienvenida. El objetivo, por supuesto, es permitir cambios en lo que devuelve el servicio para un recurso determinado, pero no romper los clientes existentes.

Aquí hay una breve lista de recursos que he visto recientemente: