×
Loading in progress

Développement de l'API 2.0

[ Pages : 1 2 ]

← Page précédente | Page suivante →

Maxime
Le Créateur

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


Cette mise à jour de l'API s'accompagne d'une réécriture presque complète de la gestion des données sur BetaSeries et permettra de meilleures mises à jour par la suite.

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

Créateur de BetaSeries.
Membre depuis le 17 January 2008 — 548 messages

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 :)

Ce message a été rédigé par une personne ayant supprimé son compte.

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.

Membre depuis le 2 May 2010 — 1 message

Maxime
Le Créateur

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é.

Créateur de BetaSeries.
Membre depuis le 17 January 2008 — 548 messages

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

Membre depuis le 10 July 2009 — 3 messages

Maxime
Le Créateur

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.

Créateur de BetaSeries.
Membre depuis le 17 January 2008 — 548 messages

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.

Membre depuis le 10 July 2009 — 3 messages

Maxime
Le Créateur

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.

Créateur de BetaSeries.
Membre depuis le 17 January 2008 — 548 messages

Juste pour info.

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

En tout cas, un grand merci pour ce travail !

Développeur de l'app SeriesManiac
Membre depuis le 7 October 2011 — 6 messages

Maxime
Le Créateur

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 :)

Créateur de BetaSeries.
Membre depuis le 17 January 2008 — 548 messages

Cool :)

Merci pour les infos !

Développeur de l'app SeriesManiac
Membre depuis le 7 October 2011 — 6 messages

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

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

Membre depuis le 25 September 2012 — 10 messages

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...


Or, j'ai vu que :
  • tu utilises aussi le verbe DELETE...
  • la documentation automatiquement générée affiche tantôt des GET, tantôt des POST


Peux-tu confirmer que si c'est un GET ou un POST, on peut quand même utiliser l'autre et que par conséquent, seul le DELETE est différent ?

Par ailleurs, on peut commencer à basculer les appels V1 vers V2 d'une appli en prod ou tu conseilles d'attendre car des changements (signature, données retournées, ...) peuvent encore régulièrement survenir ?

Merci,

W.

Membre depuis le 25 September 2012 — 10 messages

Maxime
Le Créateur

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.

Créateur de BetaSeries.
Membre depuis le 17 January 2008 — 548 messages

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


Quand je lis ça, je comprends que je peux utiliser au choix, le GET ou le POST...
Or sur la doc de la méthode elle-même on peut lire :
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.

Membre depuis le 25 September 2012 — 10 messages

[ Pages : 1 2 ]

← Page précédente | Page suivante →