API RESTful et gestion des clés étrangères pour les POST et PUT

Question

Je participe au développement d'une nouvelle API pour une base de données existante.

J'utilise Python 2.7.3, Django 1.5 et le django-repos-cadre 2.2.4 avec PostgreSQL 9.1

J'ai besoin/veulent une bonne documentation de l'API, mais je suis en désavantage numérique et je déteste écrire/maintenir la documentation (un de mes nombreux défauts).

Je dois permettre aux consommateurs de l'API d'ajouter de nouveaux emplacements «POS» (points de vente). Dans la base de données Postgres, il existe une clé étrangère de pos à pos_location_type. Donc, voici une structure de table simplifiée.

pos_location_type(
    id serial, 
    description text not null 
); 

pos(
    id serial, 
    pos_name text not null, 
    pos_location_type_id int not null references pos_location_type(id) 
); 

Ainsi, pour leur permettre de poster un nouveau pos, ils devront me donner un « pos_name » un un pos_location_type valide. Donc, j'ai lu à propos de ce genre de choses tout le week-end. Beaucoup de débats là-bas.

Comment mes clients API vont-ils savoir ce qu'est un pos_location_type? Ou quelle valeur passer ici?

Il semble que je doive leur dire où obtenir une liste valide de pos_locations. Quelque chose comme:

GET /pos_location/ 

Comme une note rapide, des exemples de descriptions de pos_location_type pourrait être: ('école', 'parc', 'bureau'). J'aime vraiment le "Browseability" de Django REST Framework, mais, il ne semble pas aborder ce genre de chose, et j'ai eu une très bonne discussion sur IRC avec Tom Christie plus tôt aujourd'hui, et il Je n'ai pas vraiment de réponse sur ce qu'il faut faire ici (ou peut-être n'ai-je jamais clarifié ma question). J'ai regardé Swagger, et c'est un projet très cool/intéressant, mais jetez un oeil à leur ressource "animal de compagnie" sur leur demo here. Remarquez que c'est assez similaire à ce que j'ai besoin de faire. Pour ajouter un nouvel animal de compagnie, vous devez passer une catégorie, qu'ils définissent comme class Category (id: long, name: string). Comment le consommateur suppose-t-il savoir ce qu'il faut passer ici? Qu'est-ce qu'un identifiant valide? ou nom?

Dans le cadre de repos Django, je peux définir/redéfinir ce qui est retourné dans l'appel OPTION. Je suppose que je pourrais venir avec mon propre petit « système » ici et retourner quelques informations comme:

pos-location-url: '/pos_location/' 

sous forme générique, ce serait: {} ressources -url: «/path/to/resource_list »

et cela fonctionnerait en quelque sorte pour la documentation, mais je ne suis pas sûr que ce soit vraiment une bonne solution par programmation. Que faire si je change l'emplacement des ressources. Cela signifierait que mes consommateurs auraient besoin de faire des programmes et OPTIONS demander à la ressource de comprendre toutes les relations. Peut-être pas une mauvaise chose, mais se sent comme un peu étrange.

Alors, comment les gens gèrent-ils ce genre de chose?

Notes finales: Je comprends le fait que je ne veux pas vraiment une « fuite » Abstaction ici et avoir ma base de données avec un pic à travers la couche API, mais le fait demeure qu'il ya une contrainte foreign_key sur cette base de données existante et tout insert qui n'a pas de pos_location_type_id valide déclenche une erreur.

En outre, je n'essaie pas d'ouvrir le débat URI vs ID. Si l'utilisateur doit utiliser la valeur int pos_location_type_id ou un URI n'a pas d'importance pour cette discussion. Dans les deux cas, ils n'ont aucune idée de ce qu'il faut m'envoyer.

Answer 1

J'ai travaillé avec ce genre de choses dans le passé. Je pense qu'il existe deux façons d'aborder ce problème, la première que vous avez déjà dit, permettre un point de terminaison pour les utilisateurs de l'API pour savoir quelle est la valeur de pos_location_type comme un ID. De nombreuses API le font parce qu'une personne qui développe à partir de votre API va devoir lire votre documentation et saura où trouver les valeurs pos_location_type. Les utilisateurs finaux ne devraient pas s'inquiéter à ce sujet, car ils auront une interface montrant probablement une liste déroulante des valeurs de texte. D'autre part, la façon dont j'ai également travaillé cela, pas très RESTful-like. Supposons que vous avez un endroit à New York, et le poste pourrait être quelque chose comme:

POST /pos/new_york/ 

Vous pouvez gérer/pos/(location_name)/en normalisant le texte, puis effectuez une recherche uniquement sur la base de données de la valeur ou une certaine similitude, si le lieu n'existe pas alors vous en créez un nouveau. Que dans le cas où les utilisateurs peuvent ajouter de nouveaux endroits, sinon, l'utilisateur devrait savoir ce que les lieux fixes existent, ce qui est la première situation dans laquelle nous sommes.

de cette façon, vous pouvez éviter pos_location_type dans les données de la demande, vous pourrait par programme le mapper à un ID valide.