🔗 Introduction

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

🔗 Inscription

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.

🔗 Documentation

🔗 Clients

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.

🔗 Client JS


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];

🔗 Client Elixir


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

🔗 API REST

🔗 Requêtes

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

🔗 Chargement de relations

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

🔗 Filtrage des résultats

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

🔗 Liste des routes

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

🔗 Réponses

📃 Réponses paginées

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

📦 Réponses simples

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"
}

Réponses références

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"
}

🔗 Modèles

🔗 Saison(s)

🔗 champs

{
  concerts_url: "saisons/public/concerts?id_saison={number}",
  id_saison: {number},
  representations_url: "saisons/public/representations?id_saison={number}",
  titre: {string}
}
🔗 relations

🔗 Concert(s)

🔗 champs

{
  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}
}
🔗 relations

🔗 Genre(s)

🔗 champs

{
  id_genre: {number},
  nom: {string}
  nom_en: {string}
}
🔗 relations

🔗 Distribution(s)

🔗 champs

{
  fonction: {string},
  fonction_en: {string},
  id_artiste: {number},
  id_concert: {number},
  id_distribution: {number},
  noms: {string}
}
🔗 relations

🔗 Artiste(s)

🔗 champs

{
  fonctiontexte: {string},
  id_artiste: {number},
  id_artistetype: {number},
  image: {path},
  nom: {string},
  prenom: {string},
  texte: {text}
}
🔗 relations

🔗 Types d'Artiste

🔗 champs

{
  id_artistetype: {number},
  type: {string}
}
🔗 relations

🔗 Oeuvre(s)

🔗 champs

{
  complement: {string},
  distribution: {string},
  id_concert: {number},
  id_oeuvre: {number},
  titre: {string}
}
🔗 relations

🔗 Compositeur(s)

🔗 champs

{
  id_compositeur: {number},
  nom: {string},
  prenom: {string}
}
🔗 relations

🔗 Representation(s)

🔗 champs

{
  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}
}
🔗 relations

🔗 Lieu(s)

🔗 champs

{
  adresse: {string},
  departement: {string},
  id_lieu: {number},
  latitude: {string},
  longitude: {string},
  nom: {string},
  ville: {string}
}
🔗 relations

🔗 Exemples

🔗 F.A.Q