conception API REST - gestion des dépendances inter-terrain

Question

J'ai une ressource appelée User qui a les champs suivants: id, last_name, date_of_birth, organization_id et employee_number.

Je souhaite définir un point de terminaison de recherche permettant aux utilisateurs d'extraire des utilisateurs répondant à certaines conditions. Par exemple les personnes dont last_name est "John", et qui sont nés après une certaine date. Pour cela, je peux avoir un point d'extrémité générique /user/search qui prend ces conditions comme GET paramètres.

Cependant, il existe certaines règles métier pour certaines requêtes. Par exemple employee_number ne peut pas être interrogé à moins d'être accompagné du champ organization_id. Je trouve mentionner cela dans la documentation moche. Comment devrais-je imposer cela d'une manière plus élégante?

Une idée que j'ai est d'avoir un point final /user/employee_number/:number qui prend organization_id comme paramètre obligatoire GET. Mais cela ne semble pas "REPOS" ful. D'autres suggestions?

Answer 1

D'abord, notez que les URI ne déterminent pas "RESTfulness". Ce sont des identifiants arbitraires. Cela dit, nous voulons généralement de bonnes adresses URI.

Voici une liste non exhaustive d'options à prendre en compte.

Option 1. Hiérarchique. Une option: si chaque employé dépend d'une org, alors vous pourriez avoir

/organization/:org/employee/:number 

Assez propre, mais les employés/utilisateurs sont des ressources importantes, de sorte que vous ne voulez pas les ressources existantes comme deuxième niveau. C'est suffisant.

Une objection plus sérieuse est que cela lie l'utilisateur à une organisation particulière. Dans la vie réelle, les gens passent d'une organisation à une autre, et nous ne pensons généralement pas à un changement d'identité. En effet, avec cette approche, la ressource est l'emploi de l'utilisateur dans une organisation donnée, et non l'utilisateur lui-même.

Option 2. Paramètres de matrice. Si vous voulez/employé ou/utilisateur à haut niveau, puis une autre option est soi-disant matrix params:

/user;org=:org;number=:number 

Ce ne sont pas officiels, mais comme Tim Berners-Lee est venu avec l'idée, les gens Traitez-le comme une déclaration semi-officielle. (Je pense qu'ils ont l'air moche mais c'est un jugement purement esthétique, cela n'a rien à voir avec RESTfulness.)

Cela pose le même problème que l'option 1 concernant les employés qui se déplacent.

Option 3. ID de base de données. Troisième option:

/user/:id 

où :id est juste un certain identifiant de base de données. Documentez la recherche comme nécessitant un numéro d'organisation + employé tel que requis pour garantir l'unicité. Il n'a pas besoin d'être "moche" - par exemple le HAL spec a un joli schéma de documentation basé sur CURIE.

Encore une fois, l'URI est juste un identificateur arbitraire, donc l'utilisation de l'ID DB est correcte. Fondamentalement, les gens devraient interroger l'employé par org, numéro d'employé, etc., mais le lien self de l'employé renverrait un URI contenant un ID de base de données. Nice et propre, mais les clients ne peuvent pas directement construire les URI, ce qui correspond à la philosophie HATEOAS/hypermedia sous-jacente REST: petit nombre de points d'entrée dans l'API, et le client navigue (c'est-à-dire l'état de l'application) transitions) en utilisant des liens intégrés dans les ressources.

De plus, cela permet à l'utilisateur de passer de l'org à l'org sans avoir à assumer une nouvelle identité.