DISEÑO DE API REST: obtener un recurso a través de REST con diferentes parámetros pero el mismo patrón de URL

Tengo una pregunta relacionada con el diseño de URL REST. Encontré algunas publicaciones relevantes aquí: Diferentes representaciones RESTful del mismo recurso y aquí: URL RESTful para OBTENER recursos por diferentes campos, pero las respuestas no son muy claras sobre cuáles son las mejores prácticas y por qué. He aquí un ejemplo.

Tengo URL REST para representar el recurso de "usuarios". Puedo OBTENER un usuario con una identificación o con una dirección de correo electrónico, pero la representación de la URL sigue siendo la misma para ambos. Al revisar muchos blogs y libros, veo que la gente ha estado haciendo esto de muchas maneras diferentes. Por ejemplo

leer esta práctica en un libro y en algún lugar de stackoverflow (parece que no puedo encontrar el enlace de nuevo)

GET /users/id={id}
GET /users/email={email}

lee esta práctica en muchos blogs

GET /users/{id}
GET /users/email/{email}

Los parámetros de consulta se usan normalmente para filtrar los resultados de los recursos representados por la URL, pero también he visto que esta práctica se usa

GET /users?id={id}
GET /users?email={email}

Mi pregunta es, de todas estas prácticas, ¿cuál tendría más sentido para los desarrolladores que consumen las apis y por qué? Creo que no hay reglas escritas en piedra cuando se trata de diseños de URL REST y convenciones de nomenclatura, pero solo quería saber qué ruta debo tomar para ayudar a los desarrolladores a comprender mejor las apis.

¡Toda la ayuda apreciada!

En mi experiencia, GET /users/{id} GET /users/email/{email}es el enfoque más común. También esperaría que los métodos devuelvan un 404 Not Found si un usuario no existe con el ido email. Tampoco me sorprendería verlo GET /users/id/{id}(aunque en mi opinión, es redundante).

Comentarios sobre los otros enfoques

1. GET /users/id={id} GET /users/email={email}
   • No creo haber visto esto, y si lo hubiera visto, sería muy confuso. Es casi como si estuviera tratando de imitar parámetros de consulta con parámetros de ruta.
2. GET /users?id={id} GET /users?email={email}
   • Creo que dio en el clavo cuando mencionó el uso de parámetros de consulta para el filtrado.
   • ¿Sería siempre tiene sentido para llamar a este recurso con tanto una idy una email(por ejemplo GET /users?id={id}&email={email})? Si no, no usaría un método de recurso único como este.
   • Esperaría que este método para recuperar una lista de usuarios con parámetros de consulta opcionales para el filtrado, pero no esperaría id, emailni ningún identificador único entre los parámetros. Por ejemplo: GET /users?status=BANNEDpodría devolver una lista de usuarios prohibidos.

_{Consulte esta respuesta de una pregunta relacionada.}

Mirando esto pragmáticamente, tienes una colección de usuarios:

/users   # this returns many

Cada usuario tiene una ubicación de recursos dedicada:

/users/{id}    # this returns one

También tiene varias formas de buscar usuarios:

/users?email={email}
/users?name=*bob*

Dado que todos estos son parámetros de consulta para / users, todos deberían devolver listas ... incluso si es una lista de 1.

Escribí una publicación de blog sobre el diseño pragmático de API RESTful aquí que habla de esto, entre otras cosas, aquí: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api

Sobre los recursos del usuario

en la ruta /userssiempre obtendrá una colección de recursos de usuario devueltos.

en el camino /users/[user_id]puede esperar que sucedan varias cosas:

1. debe obtener un recurso singleton que represente el recurso del usuario con su identificador [user_id] o
2. una respuesta 404 no encontrada si no existe ningún usuario con id [user_id] o
3. un 401 prohibido si no se le permite acceder al recurso de usuario solicitado.

Cada singleton se identifica de forma única por su ruta e identificador y usted los usa para encontrar el recurso. No es posible utilizar varias rutas para el singleton.

Puede consultar la ruta /userscon parámetros de consulta ( GETParámetros). Esto devolverá una colección con usuarios que cumplan con los criterios solicitados. La colección que se devuelve debe contener los recursos del usuario, todos con su ruta de recursos de identificación en la respuesta.

Los parámetros pueden ser cualquier campo presente en los recursos de la colección; firstName, lastName,id

Sobre el correo electrónico

El correo electrónico puede ser un recurso o una propiedad / campo del recurso del usuario.

- Correo electrónico como propiedad del usuario:

Si el campo es una propiedad del usuario, la respuesta del usuario se vería así:

{ 
  id: 1,
  firstName: 'John'
  lastName: 'Doe'
  email: 'john.doe@example.com'
  ...
}

Esto significa que no hay punto final especial para correos electrónicos, pero ahora se puede encontrar un usuario por su correo electrónico mediante el envío de petición siguiente: /users?email=john.doe@example.com. Que (asumiendo que los correos electrónicos son exclusivos de los usuarios) devolverían una colección con un elemento de usuario que coincide con el correo electrónico.

- Correo electrónico como recurso:

Pero si los correos electrónicos de los usuarios también son recursos. Luego, podría crear una API donde /users/[user_id]/emailsdevuelva una colección de direcciones de correo electrónico para el usuario con id user_id. /users/[user_id]/emails/[email_id]devuelve el correo electrónico del usuario con user_id y ['email_id']. Lo que use como identificador depende de usted, pero yo me quedaría con un número entero. Puede eliminar un correo electrónico del usuario enviando una DELETEsolicitud a la ruta que identifica el correo electrónico que desea eliminar. Entonces, por ejemplo, DELETEon /users/[user_id]/emails/[email_id]eliminará el correo electrónico con email_id que es propiedad del usuario con user_id. Lo más probable es que solo ese usuario pueda realizar esta operación de eliminación. Otros usuarios obtendrán una respuesta 401.

Si un usuario solo puede tener una dirección de correo electrónico, puede seguir. /users/[user_id]/email Esto devuelve un recurso singleton. El usuario puede actualizar su dirección de correo electrónico PUTmarcando la dirección de correo electrónico en esa url.