Développement de l'API 2.0

Bonjour à tous,

Je viens de commencer le développement de la prochaine version de l'API BetaSeries.

Elle apporte son lot de nouveautés qui font qu'elle ne sera pas une évolution de l'API actuelle, mais une toute nouvelle démarrée from scratch. L'ancienne sera toujours accessible mais ne sera plus mise à jour et sera coupée à terme.

Au menu de cette mise à jour

• Toujours des retours en XML / JSON
  
• Du JSON mieux formé (notamment pour les cast integer et bool)
  
• Des messages d'erreur en français
  
• Des retours plus consistants en fonction des objets retournés
  
• Une utilisation des ID pour toutes les méthodes (utilisateurs, séries, épisodes, films...)
  
• Le format de retour doit être demandé dans l'entête Accept
  
• Le token et la clé API sont retournés dans les entêtes HTTP
  
• Les verbes HTTP sont spécifiques aux méthodes (GET / POST / PUT / DELETE)
  
• Le retour "code" n'existe plus, il faut se fier aux statuts HTTP
  

Dernière édition le 16 septembre 2013 à 16:18

Hello Maxime!

Tu n'as pas l'air d'avoir du succès ici alors je commence, ça va peut être donner des idées à d'autres

1) Comme je te l'avais déjà dis, se serai bien d'unifier les différents retours lorsqu'il s'agit des utilisateurs. Par exemple pour la listes des amis, on a que le login mais pour la recherche, on a le login + un boolean pour savoir si c'est déjà un ami ou non. Dans l'idéal, je verrai bien un noeud / objet comme ceci:
user:
- id
- login
- is_in_account
- is_requested
- is_request
- is_blocked
2) Pour la liste des séries d'un utilisateur connecté par son token, est-ce que l'on pourrai avoir le dernier épisode vu en paramètre? Cela permettrai d'afficher visuellement l'avancement de l'utilisateur pour cette série comme c'est le cas sur le site.
3) Toujours pour la liste des séries, est-ce que l'on pourrai avoir le statut? (finie, en cours, etc...)
4) Pour les notifications, est-ce qu'il serait possible de ne pas supprimer les liens afin de rediriger les utilisateurs correctement?

C'est tout ce que je vois pour l'instant

Salut,

Comme dit sur irc, personnellement j'aimerais bien un API RestFull/HATEOAS, cad basé sur les verbes HTTP (GET, POST, PUT, DELETE), des urls bien définies, etc...
Le choix du format de retour serait fait par le header Accept, les données envoyées pourraient elles aussi être en json/xml. Les informations de type token/api key pourraient elles aussi être mises dans les headers http pour les isoler des vraies données des requêtes/réponses.

My 2 cents.

Merci pour vos réponses

@Tomtom33 : Comme j'ai précisé, la discussion doit tourner autour de l'API en elle-même plutôt que de ses méthodes. Pour tes demandes spécifiques tu peux ouvrir des tickets à part pour la constance de retour des objets (ton 1), ça je l'ai bien pris en compte.

@JEDI_BC : J'ai fait une mise à jour pour la gestion des entêtes HTTP, tu as raison c'est plus propre comme ça, pareil pour les verbes. En revanche je ne pense pas rendre l'API compatible HATEOAS, ça me demanderait pas mal de travail pour quelque chose qui serait très peu utile / utilisé.

Salut,

Merci pour le travail effectué. Du coup je vais attendre un peu pour commencer le développement de mon appli
Pour ma part, j'aimerai qu'il soit possible de récupérer les images des séries en plusieurs formats (au moins 2). C'est pas forcément évident de faire un design avec seulement le format bannière. L'idéal serait :
- la bannière
- un format un peu plus "4/3" (http://cdn.betaseries.com/betaseries/images/fonds/show/481_1362239732.jpg par exemple)
- un portrait ou carré (mais là je ne crois pas que vous ayez les images)

Je ne sais pas trop si ça necessite l'ouverture d'un ticket ou non.

Merci

Hello,

Sur la nouvelle API il y aura une méthode où tu pourras spécifier les dimensions minimales que tu veux pour ton image et je te retournerai ce qui correspond le mieux.

Super, c'est parfait pour les images.
Autre remarque, sur la méthode members/episodes/all, qui retourne forcément la liste des sous-titres pour chaque épisode, ce qui la rend un peu longue à charger si on ne précise pas de limite.
Le but étant de pouvoir récupérer le nombre d'épisodes restant à voir pour chaque série.
Du coup, un paramètre pour ne pas récupérer les sous-titres serait l'idéal.
J'avais ouvert le ticket #112 pour poser la question sur la V1 de l'API mais si ça peut être implémenté sur la V2 c'est le top.

Yop,

Du coup je re-précise le topic, le but de cette discussion n'est pas de parler des features que vous voulez voir sur l'API, pour ça les tickets fonctionnent bien.

Le but de cette discussion porte autour de l'API en elle-même et de ce que vous aimeriez avoir en termes techniques.

Juste pour info.

Avez-vous une date de disponibilité de cette version 2.0 ?

En tout cas, un grand merci pour ce travail !

Hello,

J'ai mis en place la documentation hier, pour montrer en détails l'avancement : http://www.betaseries.com/api/docs

Le développement est bien en place maintenant au niveau technique, en allant je fais des optimisations dans la base donc parfois ça met un peu plus de temps que prévu mais globalement j'espère avoir fini d'ici mi-mai

Cool

Merci pour les infos !

Mais c'est demain mi-mai... si on parle bien de 2013 !

Une idée de combien de temps tu comptes laisser la v1 en prod une fois la v2 en ligne ?

Concernant la documentation actuelle, on peut lire :

Les appels à l'API doivent être faits sous la forme de requêtes HTTP en GET ou POST sur le domaine api.betaseries.com, par exemple...

• tu utilises aussi le verbe DELETE...
  
• la documentation automatiquement générée affiche tantôt des GET, tantôt des POST
  

Oh le vilain double post

Oui je parle bien de 2013 — J'ai fini une bonne moitié là et c'était la plus complexe.

Whiler a écrit :
Une idée de combien de temps tu comptes laisser la v1 en prod une fois la v2 en ligne ?

Gros minimum 6 mois. La version actuelle n'a pas de problèmes particuliers de performances ou autres, cependant elle est dure à maintenir donc elle ne sera plus maintenue à part pour les bugfixes, donc j'espère que ça motivera pour passer à la 2.0

Whiler a écrit :
tu utilises aussi le verbe DELETE...

C'est ajouté dans la doc, merci ç

Whiler a écrit :
la documentation automatiquement générée affiche tantôt des GET, tantôt des POST

Et tantôt des DELETE. Le principe des verbes c'est qu'ils ont une signification, le GET récupère des informations, POST les crée et DELETE les supprime. Donc il y a une importance, ta requête ne fonctionnera pas si tu utilises le mauvais verbe.

Whiler a écrit :
on peut commencer à basculer les appels V1 vers V2 d'une appli en prod ou tu conseilles d'attendre

Tu peux commencer à faire des tests, la documentation est là pour ça. Cependant je conseille pas de mettre en production tant que toutes les méthodes sont pas finies, il peut encore y avoir des changements.

Maxime a écrit :
Oh le vilain double post

oups

Maxime a écrit :
Gros minimum 6 mois.

ok, c'est confortable.

Maxime a écrit :
Et tantôt des DELETE. Le principe des verbes c'est qu'ils ont une signification, le GET récupère des informations, POST les crée et DELETE les supprime. Donc il y a une importance, ta requête ne fonctionnera pas si tu utilises le mauvais verbe.

Argh, donc, ça casse tout l'existant où l'on pouvait utiliser soit l'un soit l'autre (GET|POST).
j'ai vu la modif de la doc, mais là, pour le coup, en lisant ta phrase ci-dessus, c'est cette ligne là qui peut porter à confusion :

• GET/POST http:/ /api.betaseries.com/shows/display?id=1
  

GET http://api.betaseries.com/shows/display
Le GET est cohérent puisque c'est de la récupération d'infos... donc, je pense que c'est la doc de présentation qui peut toujours porter à confusion.. en affichant le POST...
(Je ne cherche pas à jouer sur les détails, mais j'veux être sûr d'avoir parfaitement compris )

Maxime a écrit :
Tu peux commencer à faire des tests, la documentation est là pour ça. Cependant je conseille pas de mettre en production tant que toutes les méthodes sont pas finies, il peut encore y avoir des changements.
Concernant la documentation, tu parles de génération automatique... je suppose que c'est pour cela que l'on ne peut pas la modifier comme celle de la V1 ?
Ce qui manque cruellement, ce sont les structures des retours de ces méthodes... et comme je n'ai pas envie de me créer une doc perso locale, j'vais pour le moment temporiser un peu...

Sinon, une autre question qui me vient à l'esprit : le Token généré est-il commun ou deux versions de l'API ? (si je le récupère en V1, puis-je attaquer des méthodes de la V2 ; si je le récupère en V2, puis-je attaquer des méthodes de la V1)

Merci,

  W.