1.Définition d'un API
API : Une interface de programmation (Application Programming Interface ou API) permet de définir la manière dont un composant informatique peut communiquer avec un autre.
C'est donc une interface de code source fournie par un système informatique ou une bibliothèque logicielle, en vue de répondre à des requêtes pour des services qu'un programme informatique pourrait lui faire.
La connaissance des API est indispensable à l'interopérabilité entre les composants logiciels.
Source : Wikipédia
2.Règles à respecter pour accéder aux APIs
La BDFCI vous permet donc d'utiliser des outils pour intégrer dans votre site, des informations de manière dynamique.
Afin d'accéder aux informations du portail, informations fournies par les membres contributeurs, il convient :
- D'être membre du portail.
- Bien comprendre que ce service peut être suspendu à tout moment.
- Bien comprendre que le portail bdfci.info n'offre aucun support aux développements de chacun.
- Les horaires de diffusion ne sont pas disponibles dans les APIs.
- Avoir cumulé au moins 10000 points (dix mille points) avant de déposer une demande.
- Avoir généré une clé API dans votre espace membre (générateur accessible à partir de 10000 points).
- Avoir envoyé le lien du portail qui utilisera ces APIs par formulaire de contact, ou l'IP qui utilisera le service, avec la clé générée.
- Continuer à contribuer de manière régulière sur le portail.
Après avoir obtenu tous ces renseignements, l'accès aux apis sera possible selon les quotas définis au paragraphe suivant.
3.Les quotas de requêtes
- Moins de 10000 points : pas d'accès aux APIs
- A partir de 10000 points : 500 requêtes quotidiennes
- A partir de 30000 points : 2500 requêtes quotidiennes
- A partir de 100000 points : 10000 requêtes quotidiennes
- A partir de 500000 points : pas de limites
Maximum : 2 requêtes par seconde dans tous les cas.
(Code 503 serveur au delà de 1 requête par 1/2 seconde)
4.Les outils disponibles
- /find : api recherche dans la base de donnée BDFCI (films, séries ou personnalités)
- /detail : api d'affichage du détail d'une fiche
- /places : affiche la liste des salles dans une ville ou les salles à proximité
- /mymovies : api d'affichage de votre vidéothèque (hors quota)
- /genres : api d'affichage de la liste des genres disponibles sur le portail (hors quota)
- /origines : api d'affichage de tous les pays disponibles sur le portail (hors quota)
- /status : status consommation de votre compte (hors quota)
Paramètres généraux
- La clé API "mykey" est obligatoire à chaque appel d'un script.
- Méthodes d'appel autorisées : GET ou POST.
- Retours aux formats JSON ou XML (JSON par défaut), encodage : UTF8.
- URL de base : https://apis.bdfci.info.
- Pour application générale d'un paramètre : Tous les paramètres sont applicables au format paramètre=valeur.
La description est faite pour vous guider et donc améliorer la qualité de vos recherches.
/find STATUS : disponible (02/04/2022)
Recherche de base, décomptée des quotas.
Paramètres :
- mykey : votre clé API
- ask : le terme (nom, titre) recherché
- exact : si la recherche porte sur un terme exact, alors préciser y
- results : le nombre de résultats demandés. Par défaut : 5, maximum : 10
- format : JSON ou XML (JSON par défaut)
- type : le type de recherche : film, personne ou serie, par défaut film Non encore disponible
- sort : NOM ou ANNEE, tri par année ou par titre (NOM par défaut)
- order : ASC ou DESC, tri ascendant ou descendant. (ASC par défaut)
Exemple en xml
- https://apis.bdfci.info/find?ask=apocalypto&format=xml&exact=y&mykey=neze542[...]78zec168
/detail STATUS : disponible, mais toujours en développement (10/04/2022)
Retourne le détail d'un item, décompté des quotas.
Paramètres :
- mykey : votre clé API
- type : film, personne ou serie, par défaut film
- id : l'identifiant numérique de l'item à afficher
- job : afficher la liste des films concernés par le métier de la personne Non encore disponible
(métiers disponibles pour une personne donnés en retour de la requête de recherche sur une personne)
- format : JSON ou XML (JSON par défaut)
Exemple en json
- https://apis.bdfci.info/detail?type=film&id=30879&format=json&mykey=neze542[...]78zec168
/places STATUS : disponible, mais toujours en développement (08/04/2022)
Retourne la liste des salles de projection connues dans une ville (pas de limite, ville exacte, exemple : Marseille, Bordeaux, Paris,...), sinon les salles les plus proches de cette ville (distance inférieure ou égale à 20 kilomètres).
Si un nom de ville trouve plusieurs correspondances sur différents départements, les correspondances seront affichées (exemple : la ville de Charly : 1 résultat dans le Rhône, 1 résultat dans le Cher).
Décompté des quotas.
Réflexion en cours sur la possibilité d'ajouter le code postal pour les recherches.
Attention il y a encore des bugs, la gestion des villes et des distances est très complexe, non pas en code, mais de par les noms !
Paramètres :
- mykey : votre clé API
- city : nom de la ville recherchée
- format : JSON ou XML (JSON par défaut)
Exemple en json
- https://apis.bdfci.info/places?city=brignais&format=json&mykey=neze542[...]78zec168
/mymovies STATUS : disponible (06/04/2022)
Retourne la liste des films disponibles dans votre vidéothèque, non décompté des quotas.
Paramètres :
- mykey : votre clé API
- format : JSON ou XML (JSON par défaut)
- sort : NOM ou ANNEE, tri par année ou par titre (NOM par défaut)
- order : ASC ou DESC, tri ascendant ou descendant. (ASC par défaut)
Exemple en xml
- https://apis.bdfci.info/mymovies?format=xml&mykey=neze542[...]78zec168
/genres STATUS : disponible (06/04/2022)
Retourne la liste des genres disponibles sur le portail, non décompté des quotas.
Paramètres :
- mykey : votre clé API
- format : JSON ou XML (JSON par défaut)
Exemple en xml
- https://apis.bdfci.info/genres?format=xml&mykey=neze542[...]78zec168
/origines STATUS : disponible (06/04/2022)
Retourne la liste des origines disponibles sur le portail, non décompté des quotas.
Paramètres :
- mykey : votre clé API
- format : JSON ou XML (JSON par défaut)
Exemple en xml
- https://apis.bdfci.info/origines?format=xml&mykey=neze542[...]78zec168
/status STATUS : disponible (02/04/2022)
Retourne l'état de vos consommations des APIs.
Paramètres :
- mykey : votre clé API
- format : JSON ou XML (JSON par défaut)
Exemple en xml
- https://apis.bdfci.info/status?format=xml&mykey=neze542[...]78zec168
5.Les codes retours
Les codes retours sont donnés à chaque retour pour aider à définir les cas d'erreur.
{
"code": 4,
"message": "Cl\u00e9 API invalide. Vous devez fournir une cl\u00e9 API valide."
}
| Code |
HTTP Status |
Message |
| 1 |
200 |
Success |
| 2 |
500 |
Service indisponible. |
| 3 |
401 |
Clé API absente. Vous devez fournir une clé API valide. |
| 4 |
401 |
Clé API invalide. Vous devez fournir une clé API valide. |
| 5 |
401 |
Clé API non encore validée par administrateur. |
| 6 |
404 |
Requête inconnue. |
| 7 |
401 |
Quota dépassé. |
| 8 |
405 |
Méthode non autorisée. |
| 9 |
400 |
La syntaxe de la requête est erronée. Des paramètres sont absents. |