api - una - verbos http rest

Forma de especificar la lista de campos de recursos en la solicitud de API RESTful

Question

Tengo una API REST en un servicio web con algún tipo de recursos como usuarios, publicaciones, etc. Cuando hago una solicitud de lista de publicaciones (GET / posts), quiero recuperar un conjunto de publicaciones solo con una parte reducida de datos para cada publicación (es decir, asunto, nombre del autor). Cuando solicito una publicación concreta (GET / posts / 42) quiero recuperar la lista completa de campos de objeto de publicación, incluido el cuerpo de la publicación grande, información adicional sobre el número de me gusta, el recuento de comentarios. Supongo que existen muchas formas de resolver este problema. En mi opinión, las 3 más obvias son:

1. Especifique explícitamente los campos en cada solicitud (/ posts? Fileds = subject, author_name y para / posts / 42? Fields = subject, body, createaAt, author_name, comments_count, likes_count, etc ...).
2. Especifique explícitamente la lista de campos solo si difiere de la lista de campos predeterminados.
3. Especifique la lista de campos que deben excluirse (o incluirse) de (a) los campos predeterminados establecidos si los campos deseados configurados difieren de los predeterminados.

Quiero construir una API clara y útil para mis clientes. ¿Qué camino debo elegir?

Answer 1

Me gustaría la opción 2 IMHO.

Entonces, si el consumidor solo solicita la url de recursos (/ posts / 42) recibe los campos predeterminados.

Luego, los consumidores pueden alterar la respuesta predeterminada definiendo valores en la cadena de consulta como: / posts / 42 / fields? Subject, author_name

Esto me ha funcionado bien en el pasado y es así como funcionan otras API muy conocidas, por ejemplo, Facebook

Edición: si miro hacia atrás, cambiaría la solicitud para que sea: / posts / 42? Fields = subject, author_name, / post / 42 es el recurso no campos.

Answer 2

También he estado investigando esto y apunté a GraphQL de Facebook como una alternativa a solicitar una api tranquila con los campos deseados. Todavía está en las primeras etapas, pero parece muy prometedor.

https://facebook.github.io/react/blog/2015/05/01/graphql-introduction.html

EDITAR: Reproducido desde la URL:

Una consulta GraphQL es una cadena interpretada por un servidor que devuelve datos en un formato específico. Aquí hay una consulta de ejemplo:

{
  user(id: 3500401) {
    id,
    name,
    isViewerFriend,
    profilePicture(size: 50)  {
      uri,
      width,
      height
    }
  }
}

(Nota: esta sintaxis es ligeramente diferente de los ejemplos anteriores de GraphQL. Recientemente hemos estado mejorando el lenguaje).

Y aquí está la respuesta a esa consulta.

{
  "user" : {
    "id": 3500401,
    "name": "Jing Chen",
    "isViewerFriend": true,
    "profilePicture": {
      "uri": "http://someurl.cdn/pic.jpg",
      "width": 50,
      "height": 50
    }
  }
}