[Élaboration] Conception d'une API

[sur_uix]

Bonjour,

Je suis en train de concevoir une application qui devra être piloté par d'autre applications qui serons développés par d'autres développeurs.
Je suis un peu vague, je sais...

Jusque là rien de particulier.
Sauf que je n'ai pas d'expérience dans la conception d'une API pour mes futures clients !

J'ai donc commencé à me documenter sur les BestPractice concernant la conception d'une API et j'ai aussi regardé comment font les autres.

J'ai étudier les API de Google ainsi que leur clients C# !

Exemple avec l'API Task
http://code.google.com/apis/explorer/#_s=tasks&_v=v1

Les namespace en C# de cette API sont :
namespace Google.Apis.Tasks.v1.Data
namespace Google.Apis.Tasks.v1

Je note que le namespace contient la version de l'API.

L'API est décomposé en trois groupes

• Resource
• Request
• Response

Les objets Response se trouvent dans le namespace Google.Apis.Tasks.v1.Data et les deux autres dans Google.Apis.Tasks.v1

Google a fait une forte séparation entre les données et les méthodes.
P.ex. pour créer une tâche dans une liste.

Il faut, 1 - créer la liste

Code :

1
2
3
            var list = new TaskList();
            list.Title = SampleListName;
            list = service.Tasklists.Insert(list);

Et l'insérer dans les tasklist.

puis on crée la tâche et on l'ajoute à la liste.

Code :

1
2
            var mytask = new Task { Title = "Test the Tasklist API" };
            service.Tasks.Insert(mytask, list.Id).Fetch();

Et la aussi la tâche et la liste sont en paramètres.
Je suis surpris que la méthode insert(...)n'est pas membre de la classe TaskList.

On a donc des données et un service avec des méthodes qui permet de manipuler ces dites données. Pourquoi cette séparations ?
Est-ce-que c'est la règle lorsque l'on conçoit une API ?

Merci d'avance pour vos feedback.
Au plaisir de vous lire.

[Luckyluke34]

Envoyé par sur_uix

On a donc des données et un service avec des méthodes qui permet de manipuler ces dites données. Pourquoi cette séparations ?

J'imagine qu'on essaie de canaliser sur le service les points d'accès à tout ce qui concerne les tâches. Moins il y a de points d'accès différents, moins les effets de bord consécutifs à une mauvaise utilisation seront possibles. Dans cette logique, TaskList.Tasks ne devrait pas être accessible non plus. Mais je suis d'accord que ce n'est pas très intuitif.

Envoyé par sur_uix

Est-ce-que c'est la règle lorsque l'on conçoit une API ?

Absolument pas.

Une présentation sympa sur la création d'API :

How To Design A Good API and Why it Matters - YouTube

How To Design A Good API and Why it Matters - YouTube

les slides : http://www.scribd.com/doc/33655/How-to-Design-a-Good-API-and-Why-it-Matters

[sur_uix]

Merci pour la présentation...je vais la regarder tranquillement.

J'ai eu un autre feedback, en dehors de ce forum, concernant cette séparations, et on m'a répondu :
"Que cela permet d'être indépendant du langage qui va utiliser l'API"

[Luckyluke34]

Envoyé par sur_uix

J'ai eu un autre feedback, en dehors de ce forum, concernant cette séparations, et on m'a répondu :
"Que cela permet d'être indépendant du langage qui va utiliser l'API"

Tu as une explication plus précise ? Je vois mal pourquoi utiliser service.Tasks.Insert plutôt que TaskList.InsertTask() changerait quoi que ce soit en termes d'indépendance par rapport au langage consommateur de l'API

[sur_uix]

Non pas plus, mais j'en ai déduis que c'est pour les langages non-objets !

[wiztricks]

Envoyé par Luckyluke34

Tu as une explication plus précise ? Je vois mal pourquoi utiliser service.Tasks.Insert plutôt que TaskList.InsertTask() changerait quoi que ce soit en termes d'indépendance par rapport au langage consommateur de l'API

a mon sens c'est parce que l'API (Google) étant d'abord ReST, les bibliothèques langages sont des proxy: ils n'ont pas de bonnes raisons d'en cacher la structure. Surtout que ces proxy risquent d'être générés plus ou moins automatiquement.

On peut très bien imaginer écrire "TaskList.InsertTask()" "par dessus" mais dans ce cas on déborde de la simple proxy/façade de l'API ReST.

- W