[AlternC-dev] Cas pratique de besoin utilisateur N°1

Retour à l'archive de la liste
Le site d'AlternC
Google Custom Search

cam.lafit at azerttyu.net cam.lafit at azerttyu.net
Mar 27 Mai 15:09:54 CEST 2014


Ciao

J'essaye de répondre au mieux mais il est certain que certaines de mes
évidences ne le sont que pour moi, j'essaye de clarifier au mieux mais
je peux rater des points :)

> On peut dissocier deux types d'API pouvant coexister:

Si 2 API c'est que c'est mal foutu :) Il n'y a aucune raison d'avoir 2
api, peut être dans le cas d'une évolution de version.
Les API s'occupent de manipuler les ressources.

> * la première : un RPC purement interne dans une topologie "serveur(s)
> AlternC" / "backoffice AlternC PHP".
> On imagine donc un "/domains/2014/list/xml" pour avoir la liste des
> domaines de l'uid 2014 en XML.

Le format de sortie n'est pas liè à l'API on peut avoir du json, du
csv, c'est une juste une representation d'un ressource.

Dans l'exemple "/list/" ne me semble pas pertinent. SI j'interprète
bien l'exemple, on souhaite lister les domaines de l'utilisateur 2014.
Pour lister ces ressources cela pourrait être : GET
/membres/2014/domains/
Pour mettre à jour  POST /membres/2014/domain/my.tld/
Pour créer PUT /membres/2014/domain/

Dans le cas du service alternc, on travaille sur la base d'un compte
alternc (membre dans la base de données)
Le pluriel/singulier dans la ressource, est à prendre avec des pincettes

> Celle-ci n'aurait (au conditionnel) effectivement pas besoin
> d'identification (tout en protégeant son utilisation).
> Cette "API" serait donc utilisée par le frontoffice AlternC pour
> communiquer avec le backoffice. On peut donc effectivement dire que
> l'identification de l'utilisateur final est secondaire dans cette
> topologie.

Ce que tu suggères c'est de fournir par défaut un accès root. Si on
protége son utilisation c'est qu'on considére un notion
d'authentification. On tombe alors dans le cas 2.


> * la seconde : une API orientée client final
>
> Dans le cas d'une API publique (ce qui est une chose différente),
> l'utilisateur doit s'authentifier pour avoir accès à des droits
> restreints (/domains/list/xml renverra mes domaines uniquement)
>
> C'est également le genre d'API qui serait utilisée par des backoffice
> HTML5/JS, entre autres exemples, ou par les utilisateurs finaux dans leurs
> scripts.

Vu qu'on gére des droits, le cas précédent n'est qu'un cas particulier
de ce second cas.
Les interfaces graphiques de manipulations, un cli, ... ne sont que
des applications manipulant une API. Ce qui est un autre point dans
les différentes interactions à mettre en place.

> Concernant oAuth, j'ai du mal à comprendre au niveau des ACL en quoi il
> pourrait faciliter les choses, mais j'avoue ma méconnaissance du sujet.

C'est une notion de jetons révocables, qui autorise l'association de
droit. Du coup c'est assez intéressant si on a une ACL.
Par exemple pour un jeton donné on peut associer uniquement le droit
de lister les domaines du membre 2014.

> |Parmi les poins à prendre en compte; il y a le suivi de version de
> |l'api, pour ceci je préconise celle exploitée par github via les
> |HEADER : https://developer.github.com/v3/#current-version . Je vois
> |cette approche arriver de plus en plus sur les api récentes
>
> Cette approche serait bonne si les utilisateurs devaient obligatoirement
> mentionner le numéro de version, et non de manière facultative. Peu le
> feront, il suffit de voir l'exemple juste en dessous, où la commande
> "curl" est passée sans le header "Accept". Bref, le jour où ils changent
> de version, des milliers d'utilisateurs seront ennuyés. On pourrait le
> rendre obligatoire, mais ajouter un header oterait de la facilité au
> processus.

De fait l'api demande déjà de définir des informations dans le header
(POST/GET/PUT/...), Cela n'alourdit pas le processus de rajouter une
entete de plus. Le processus n'est pas rendu plus compliqué.

> La bonne méthode est plutôt celle mentionnée pour les entreprises par
> Github ("yourdomain.com/api/v3/") où le numéro de version fait partie
> intégrante de l'URL appelée... enfin c'est mon avis. Mais ça garantit une
> véritable continuité de service malgré les évolutions, et les ruptures
> de compatibilité ascendante.

Là j'invite à relire les documentations liées. Mais c'est bien la
version avec Accept qui est bien préconisée par Github que ce soit
entreprise ou autre. On trouvera d'autres service qui diront le
contraire.


Je rajoute 2/3 références suite à mes diverses lectures (loin d'être finies) :
-* http://stackoverflow.com/questions/389169/best-practices-for-api-versioning
-* http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#versioning
-* http://www.lexicalscope.com/blog/2012/03/12/how-are-rest-apis-versioned/
-* https://blog.apigee.com/detail/restful_api_design_tips_for_versioning/

voili

Km


Plus d'informations sur la liste de diffusion Dev