L'Orchestre national d'Île-de-France propose un accès ouvert à une partie des données de son site internet.
Depuis quinze ans, une base de données structure les différentes informations relatives aux concerts, aux
saisons musicales.
L'API REST publique permet d'accéder aux données de saison, afin créer des
visualisations
de données, micro-applications, etc.
┌──────────┐ ┌──────────────┐ │ Saison ├────┤ Concerts[] │ └──────────┘ └──────┬───────┘ │ ┌──────────┐ ├───┤ Genre? │ │ └──────────┘ │ ┌───────────────────┐ ├───┤ Distributions[] │ │ └─────────┬─────────┘ │ │ ┌───────────┐ │ └───┤ Artiste │ │ └─────┬─────┘ │ │ ┌───────────────────┐ │ ├───┤ Type d'artiste │ │ │ └───────────────────┘ │ │ ┌───────────────────┐ │ ├───┤ Pupitre │ │ │ └───────────────────┘ │ │ ┌───────────────────────────┐ │ └───┤ Famille d'instruments │ │ └───────────────────────────┘ │ ┌─────────────┐ ├───┤ Oeuvres[] │ │ └──────┬──────┘ │ │ ┌──────────────────┐ │ └───┤ Compositeurs[] │ │ └──────────────────┘ │ ┌─────────────────────┐ └───┤ Représentations[] │ └──────────┬──────────┘ │ ┌────────┐ └───┤ Lieu │ └────────┘ [] indique une liste, par exemple : Saison ├────┤ Concerts[] signifie que la saison comprend plusieurs concerts. ? indique la possible absence de l'élément, par exemple : Concerts[] ├────┤ Genre? signifie que tous les concerts peuvent avoir un Genre, mais qu'il n'est pas forcément renseigné.
L'inscription se fait simplement en donnant une adresse e-mail valide à laquelle recevoir un jeton d'accès.
Nous
ne vous y écrirons pas.
Sont en cours de développement un 🔗
client
Javascript ainsi qu'un 🔗 client Elixir, respectivement
installables via npm et hex. Ces clients visent à simplifier l'usage de l'API, et
proposent tous deux une interface simple.
Leur usage n'est pas obligatoire, et cette
page détaille l'API REST pouvant s'utiliser via tout langage.
import { client, StatefulClient } from '@documents-design/ondif-js';
let nextConcert = await client.concerts.next("your-api-token-here");
// ou
const stateful = new StatefulClient("your-api-token-here");
nextConcert = await stateful.concerts.next();
let beethoven = await stateful.compositeurs.list([
["nom", "like", "Beethoven"],
["prenom", "like", "Ludwig"]
], 0).toArray()[0];
next_concert = Ondix.Entities.Concert.next("your-api-token-here");
beethoven = Ondix.Entities.Compositeur.list([
{:nom, :like, "Beethoven"},
{:prenom, :like, "Ludwig"}], 0, "your-api-token-here")
|> List.first
Ondix.StatefulClient.with_token("your-api-token")
current_saison = Ondix.Entities.Saison.current_s()
Les requêtes sont authentifiées par le header X-API-TOKEN qui doit porter le jeton obtenu à
l'inscription.
Toutes les URLs citées dans ce document ont pour racine https://api.orchestre-ile.com/api/v1.
Elles sont regroupées par ensemble cohérent d'entités, par exemple /saisons/ qui est
l'espace de noms concernant toutes les données liées aux saisons : saisons, concerts,
etc. À la suite de cet espace de noms vient le préfixe /public/, qui s'applique à toutes les
ressources présentées dans ce document. Enfin vient le nom de la ressource concernée.
Ainsi, la liste des représentations de la saison en cours aura l'URL suivante :https://api.orchestre-ile.com/api/v1/saisons/public/representations?id_saison=30
Les modèles ayant des relations peuvent demander à les charger avec le paramètre
load.
Seules les entités simples permettent cela. Par exemple, récupérer la représentation 645
accompagnée de ses oeuvres se fait de cette manière :
GET saisons/public/representations/675?load=oeuvres.
Charger plusieurs relations se fait en
les séparant par des virgules, par exemple:
GET saisons/public/representations/675?load=oeuvres,lieu
Les listes de modèles peuvent être filtrés selon certains champs avec le paramètre where.
La
syntaxe à utiliser est {champ}:{opérateur}:{valeur}, par exemple, filtrer les concerts
appartenant à une saison ultérieure à la saison #17 s'écrirait ainsi :
?where=id_saison:>:17.
En cas de filtrage, les listes paginées mettent à jour l'URL de leurs
pages précédentes et suivantes pour inclure ce paramètre where
Légende : 📃 réponse paginée, 📦 entité simple, ➡️ référence vers une entité, sans détails
| Type | Méthode | Url | Description |
| 📃 | GET | saisons/public/artistes | liste des artistes |
| 📦 | GET | saisons/public/artistes/{id_artiste} | voir un artiste en détail |
| 📃 | GET | saisons/public/artiste_types | liste des types d'artistes |
| 📦 | GET | saisons/public/artiste_types/{id_artiste_type} | voir un type d'artiste en détail |
| 📃 | GET | saisons/public/compositeurs | liste des compositeurs |
| 📦 | GET | saisons/public/compositeurs/{id_compositeur} | voir un compositeur en détail |
| 📃 | GET | saisons/public/distributions | liste des distributions |
| 📦 | GET | saisons/public/distributions/{id_distribution} | voir une distribution en détail |
| 📃 | GET | saisons/public/genres | liste des genres |
| 📦 | GET | saisons/public/genres/{id_genre} | voir un genre en détail |
| 📃 | GET | saisons/public/concerts | liste des concerts |
| ➡ | GET | saisons/public/concerts/next | voir le prochain concert |
| 📦 | GET | saisons/public/concerts/{id_concert} | voir un concert en détail |
| 📃 | GET | saisons/public/lieux | liste des lieux |
| 📦 | GET | saisons/public/lieux/{id_lieu} | voir un lieu en détail |
| 📃 | GET | saisons/public/oeuvres | liste des œuvres, paginée |
| 📦 | GET | saisons/public/oeuvres/{id_oeuvre} | voir une œuvre en détail |
| 📃 | GET | saisons/public/representations | liste des représentations, paginée |
| ➡ | GET | saisons/public/representations/next | voir la prochaine représentation |
| 📦 | GET | saisons/public/representations/{id_representation} | voir une représentation en détail |
| ➡ | GET | saisons/public/saisons/current | voir la saison courante |
| 📃 | GET | saisons/public/saisons | liste des saisons, paginée |
| 📦 | GET | saisons/public/saisons/{id_saison} | voir une saison en détail |
Les collections de modèles sont renvoyées sous la forme de réponses paginées :
Les données elles-mêmes
sont emballées dans une propriété data, et l'objet retourné comporte des informations sur la
quantité et les adresses des autres pages disponibles.
{
"current_page": {NUMBER},
"data": {LIST<MODEL>},
"first_page_url": {STRING}
"from": {NUMBER},
"last_page": {NUMBER},
"last_page_url": {STRING},
"next_page_url": {STRING} | null,
"path": {STRING},
"per_page": {NUMBER},
"prev_page_url": {STRING} | null,
"to": {NUMBER},
"total": {NUMBER}
}Les réponses simples comprennent simplement l'entité demandée, avec les relations demandées, et ses champs détaillés.
GET /api/v1/saisons/public/concerts/675?load=representations,oeuvres
{
"id_concert": 675,
"id_saison": 28,
"titre": "Festival Berlioz",
"titre_en": "",
"texte": "Lorsque le grand chef d’orchestre français François-Antoine Habeneck fait découvrir [...]",
"image": "c675.jpg",
"representations": [...],
"oeuvres": [...],
"representations_url": "saisons/public/representations?id_concert=675",
"oeuvres_url": "saisons/public/oeuvres?id_concert=675",
"distributions_url": "saisons/public/distributions?id_concert=675",
"genre_url": "saisons/public/genre?id_concert=675",
"full_url": "saisons/public/concerts/675"
}
Les réponses références proviennent d'URLs décrivant des notions (prochain concert, par exemple) et renvoient une référence à l'entité concernée, accompagnée d'URLs de ses relations.
GET /api/v1/saisons/public/concerts/next
{
"id_concert": 675,
"id_saison": 28,
"titre": "Festival Berlioz",
"representations_url": "saisons/public/representations?id_concert=675",
"oeuvres_url": "saisons/public/oeuvres?id_concert=675",
"distributions_url": "saisons/public/distributions?id_concert=675",
"genre_url": "saisons/public/genre?id_concert=675",
"full_url": "saisons/public/concerts/675"
}➡ saisons/public/saisons/current : voir la saison courante📃 saisons/public/saisons : liste des saisons, paginée📦 saisons/public/saisons/{id_saison} : voir une saison en détail
{
concerts_url: "saisons/public/concerts?id_saison={number}",
id_saison: {number},
representations_url: "saisons/public/representations?id_saison={number}",
titre: {string}
}
{
distributions_url: "saisons/public/distributions?id_concert={number}",
full_url: "saisons/public/concerts/{number}",
genre_url: "saisons/public/genres?id_concert={number}",
id_concert: {number},
id_saison: {number},
oeuvres_url: "saisons/public/oeuvres?id_concert={number}",
representations_url: "saisons/public/representations?id_concert={number}",
saison_url: "saisons/public/saisons/{number}",
titre: {string}
}
{
id_genre: {number},
nom: {string}
nom_en: {string}
}
{
fonction: {string},
fonction_en: {string},
id_artiste: {number},
id_concert: {number},
id_distribution: {number},
noms: {string}
}
{
fonctiontexte: {string},
id_artiste: {number},
id_artistetype: {number},
image: {path},
nom: {string},
prenom: {string},
texte: {text}
}
{
id_artistetype: {number},
type: {string}
}
{
complement: {string},
distribution: {string},
id_concert: {number},
id_oeuvre: {number},
titre: {string}
}
{
id_compositeur: {number},
nom: {string},
prenom: {string}
}
{
distributions_url: "saisons/public/distributions?id_concert={number}",
full_url: "saisons/public/concerts/{number}",
genre_url: "saisons/public/genres?id_concert={number}",
id_concert: {number},
id_saison: {number},
oeuvres_url: "saisons/public/oeuvres?id_concert={number}",
representations_url: "saisons/public/representations?id_concert={number}",
saison_url: "saisons/public/saisons/{number}",
titre: {string}
}
{
adresse: {string},
departement: {string},
id_lieu: {number},
latitude: {string},
longitude: {string},
nom: {string},
ville: {string}
}