Fork me on GitHub
Phraseanet Documentation

Aperçu de l’API v1

L’API Phraseanet tend à utiliser un maximum de standards courants. Les requêtes sont en HTTP POST ou GET et retournent des réponses au format Json, JSonP, YAML.

Les paramètres doivent êtres envoyés en tant que clefs/valeurs HTTP.

Etant donné que Phraseanet utilise oAuth2 comme protocole d’authentification, il est important que votre serveur soit configuré pour supporter les requêtes authentifiées (https ou HTTPS)

Quotas

Il n’y a pas de quotas en v1, Le nombre de requêtes n’est pas limité.

Accès anonyme

Il n’y a pas d’accès anonyme ou public dans l’API Phraseanet V1.

Réponses

Toutes les réponses sont encapsulées dans un objet contenant deux champs : response et meta.

Les réponses sont renvoyés par défaut dans un format Json.

Note

Un champ optionnel timers, fournissant un tableau de timers, peut être obtenu en activant cette fonctionalité. Consulter le chapitre configuration pour activer ce service.

Exemple de timer :

{
    "meta": {
        ....
    },
    "response": {
        ....
    },
    "timers": [
        {
          "name": "api.load.end",
          "memory": 1908328,
          "time": 0.0025968551635742
        },
        {
          "name": "api.result",
          "memory": 3885680,
          "time": 0.033026933670044
        }
    ]
}

YAML

Comme le précise les spécifications HTTP, Pour obtenir une réponse au format YAML Il faut définir un paramétre ‘Accept’ dans l’en-tête de la requête HTTP.

Requête :

curl -H 'Accept: application/yaml' ...

Réponse :

meta:
  api_version: '1.2'
  request: 'GET /api/v1/feeds/288/content/'
  response_time: '2011-07-27T16:36:33+02:00'
  http_code: 200
  error_type: null,
  error_message: null
  error_details: null
  charset: UTF-8
response:
  ....

Json

Requête :

curl -H 'Accept: application/json' ...

Réponse :

{
    "meta": {
        "api_version": "1.3",
        "request": "GET /api/v1/feeds/288/content/",
        "response_time": "2011-07-27T15:52:04+02:00",
        "http_code": 200,
        "error_type": null,
        "error_message": null,
        "error_details": null,
        "charset": "UTF-8"
    },
    "response": {
        ....
    }
}

JsonP

Pour obtenir une réponse au format JSONP, ajouter un paramètre HTTP ‘callback’ à la requête.

Requête :

curl -H 'Accept: application/json' /api/v1/my/request/?callback=foobar

Note

Dans le cas d’une réponse au format JsonP, l’Api retourne toujours un code de réponse HTTP 200 (à l’exception du code 500) dans le champ Response. Cela a pour conséquence de permettre l’exécution du code exploitant la requête. Le code de réponse HTTP le plus significatif se trouve dans le champ Meta.

Réponse :

foobar({
    "meta": {
        "api_version": "1.3",
        "request": "GET /api/v1/feeds/288/content/",
        "response_time": "2011-07-27T15:52:04+02:00",
        "http_code": 200,
        "error_message": null,
        "error_details": null,
        "charset": "UTF-8"
    },
    "response": {
        ....
    }
})

Erreurs

Le champ Meta contient des données comme les “http_code”, “error_message” et “error_details”.

L’API Phraseanet utilise les codes de réponse HTTP. Ces codes sont présents dans le champ Meta des réponses auxquels s’ajoutent les messages d’erreur.

Le tableau suivant liste et décrit les principaux codes d’erreurs :

Code HTTP Signification
400 Un paramètre de la requête est manquant ou invalide
401 Le token d’authentification fournit n’est pas valide
403 L’accés aux ressources demandées n’est pas autorisé
404 La ressource demandée n’a pas été trouvé
405 Utilisation d’une requête POST au lieu d’une requête GET, ou inversement
500 Erreur interne du serveur