RESTful API

OAuth : implémentation dans Bokeh

Bokeh peut agir en tant que serveur OAUTH pour une application tierce. Pour cela le client doit être configuré dans l'administration

Authentification

response_type=code

Utilisé soit par les applications web soit par des applications mobiles pour récupérer un jeton d'authentification après autorisation de l'utilisateur.

Paramètres requis :

• response_type=code
• client_id : Nom de votre application. Bokeh l'affichera sur le formulaire d'authentification.
• redirect_uri : l'URL de redirection auquel sera fourni le token. Par exemple pour https://monservice.fr, Bokeh redirigera après authentification sur https://monservice.fr?token=xxxxxx

Paramètres optionnels (non implémentés):

• scope
• state

L'endpoint pour l'autentification OAuth est /auth/oauth.

Ce qui donne comme URL pour recevoir un token :

    https://monbokeh.fr/auth/oauth/response_type/code/client_id/__CLIENTID__?redirect_uri=__REDIRECT_URI_

Ce token permettra l'accès à l'API. Il devra être fourni dans le header HTTP via l'en-tête Authorization comme ceci: Authorization : Bearer xxxxx

Réponse OK

Redirection vers bokeh://monservice.fr#token=xxxxxx ou http://monservice.fr?token=xxxxxx si protocole HTTP

Réponse KO

302 - Mauvaise authentification:

{
"error": "invalid_grant",
"error_description": "Authenticaiton failure"
}

grant_type=password

Utilisé pour échanger une authentification pour un jeton d'accès. L'application cliente doit collecter le login et le mot de passe de l'utilisateur et l'envoyer au serveur.

L'utilisation de grant password n'est plus recommandé pour des raisons de sécurité (attaque par force brute)

Paramètres requis :

• grant_type=password
• username
• password
• client_id : Nom de votre application

Paramètres optionnels:

• scope (non implémentés)
• client_secret

L'endpoint pour l'autentification OAuth est /auth/oauth.

Réponse OK

Ce qui donne comme URL pour recevoir un token :

curl -X POST https://url_de_la_bibliotheque/auth/oauth \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d
grant_type=password&client_id=__CLIENT_ID&client_secret=CLIENT_SECRET&username=LOGIN&password=PASSWORD

Réponse KO

400 - Mauvaise authentification:

{
"error": "invalid_grant",
"error_description": "Authenticaiton failure"
}

Client credentials : pas implémenté

Utilisé lorsque les applications demandant un jeton d'accès pour accéder à leurs propres ressources et non au nom d'un utilisateur.ice.

Access Token

Le jeton d'acces devra être fourni dans le header HTTP via l'en-tête Authorization comme ceci:

Authorization : Bearer xxxxx
curl -X POST https://monbokeh.fr/refresh \
-H 'Authorization: Bearer 68eb06e583514a5a9da36136ddbc522c'

Refresh Token

Le refresh_token permet de renouveller l'access token sans redemander une authentification.

L'option 'refresh_token' doit etre activée dans la configuration du client.

L'authentification /auth/oauth renverra :

{
"access_token": "68eb06e583514a5a9da36136ddbc522c",
"expires_in": "86400",
"token_type": "Bearer",
"refresh_token": "202382d6bf97413abd9e4c3788e1f0cc"
}

Exemple de requete:

End point: /auth/refresh

curl -X POST https://monbokeh.fr/refresh \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d grant_type=refresh_token&refresh_token=202382d6bf97413abd9e4c3788e1f0cc

Réponse OK:

{
"access_token": "68eb06e583514a5a9da36136ddbc522c",
"expires_in": "86400",
"token_type": "Bearer",
"refresh_token": "202382d6bf97413abd9e4c3788e1f0cc"
}

Réponse KO, token invalide:

401 - Jeton expiré:

{
"error": "invalid_request",
"error_description": "The access token has expired"
}

401 - paramètre refresh_token manquant

{
"error": "invalid_request",
"error_description": "Missing parameter"
}

401 - configuration client manquante

{
"error": "invalid_request",
"error_description": "Client configuration missing for CLIENT_ID"
}

Dans tous ces cas il faut redemander un token.

401 - configuration client qui n'autorise pas le refresh:

{
"error": "invalid_request",
"error_description": "Client configuration is not allowed refresh token"
}

API

Compte utilisateur

Bokeh offre une API pour récupérer les données utilisateurs, renvoyées au format JSON.

Authentification

Un utilisateur peut autoriser Bokeh à fournir ses informations à une application tierce via OAuth. Bokeh générera une clé unique pour chaque application de l'utilisateur.

Sécurité

Par défaut, l'API OAuth force l'utilisation de HTTPS. Vous pouvez configurer Bokeh pour désactiver cette vérification via la variable OAUTH_ACCEPT_HTTP. Toutefois, nous recommandons vivement de mettre en place un certificat HTTPS plutôt que de s'appuyer sur cette variable.

Fonctionnement

Pour des exemples de fonctionnement, voir les tests dédiés

Informations du compte

URL: http://monbokeh.fr/api/user/account

Exemple de réponse:

 {
   "account": {
      "label": "Charline Dupuis",
      "login": "puppy",
      "card": {
         "id": "E345x00",
         "expire_at": "2018-04-25"
      }
   }
 }

Liste des prêts

URL: http://monbokeh.fr/api/user/loans

Exemple de réponse:

 {  "loans":[
   {
     "id" => "345_18",
     "title":"Potter",
     "author":"J.K.R",
     "date_due":"1974-01-01",
     "loaned_by":"puppy",
     "library":"Annecy",
     "record": {
          "id" => "34",
          "thumbnail" => "http://img.com/potter.jpg" 
      }
   },
   {
     "id" => "345_22",
     "title":"Alice",
     "author":"",
     "date_due":"2017-05-06",
     "loaned_by":"puppy",
     "library":""
   }
 ] }

Prolonger un prêt

URL: http://monbokeh.fr/api/user/renew-loan/id/345_22

Exemple de réponse avec succès:

 { 
   "status":"renewed",
   "date_due":"2018-02-17"
 }

Exemple de réponse avec erreur:

 {
   "status":"error",
   "error":"Nombre maximum  de prolongations atteint"
 }

Liste des réservations

URL: http://monbokeh.fr/api/user/holds

Exemple de réponse:

 {
  "holds":[
   {
     "id" => "345_22",
     "title":"Afrodeezia",
     "author":"Marcus Miller",
     "status":"En attente",
     "held_by":"puppy",
     "library":"Annecy",
     "record": {
          "id" => "34",
          "thumbnail" => "http://img.com/afrodeezia.jpg" 
      }
  ]
 }

Annuler une réservation

URL: http://monbokeh.fr/api/user/cancel-hold/id/345_22

Exemple de réponse avec succès:

 { 
   "status":"canceled"
 }

Exemple de réponse avec erreur:

 {
   "status":"error",
   "error":"Réservation introuvable"
 }

Catalogue

Récupérer un exemplaire

URL: http://monbokeh.fr/api/catalog/item/barcode/L-234

Exemple de réponse:

 {
   "id": 2613096,
   "barcode": "L-234",
   "title": "Scribblenauts unlimited",
   "author": "5th cell",
   "record": {
     "id": 2267224,
     "thumbnail" => "http://img.com/scribblenauts.jpg" 
   }
 }

Effectuer une recherche

Voir la documentation dédiée