Settings

Introduction

L'api settings permet d'enregistrer des données directement dans votre application ou dans le compte d'un utilisateur.

Cette api ne sert pas à stocker des données sensibles sur l'utilisateur.

Fonctionnement

Les donnée sont enregistré via la méthode clé valeur, la clé est toujours une chaine de caractère, la valeur quand à elle peut être de multiples type. Les données peuvent être stockés de trois manières différentes:

  • Sur votre application: les donnés stockés sur votre applications sont accessibles via vos identifiants. Ce type de stockage peut vous servir pour enregistré la configuration de l'application.

  • Sur l'utilisateur, de manière "locale": les données stockés sur l'utilisateur "localement" sont des donnés liés a un utilisateur et accessibles seulement par votre application. Ce type de stockage peut servir pour enregistrer des préférences de l'utilisateur.

  • Sur l'utilisateur, de manière "globale": les données stockés sur l'utilisateur "globalement" sont des donnés enregistré dans le compte de l'utilisateur et accessibles par toutes les applications ayant été autorisés par l'utilisateur avec le scope settings

Pour pouvoir stocker localement sur l'utilisateur, il est requis que l'utilisateur ai déjà autorisé votre application et qu'il n'ai pas révoqué cette autorisation.

Structure

Objet setting

Champ

Type

Description

key

string

Clé sous laquelle la configuration est enregistré, limité à 128 caractères. Ne peut contenir que des caractères alphanumériques, des tirets (-), des points (.) et des tirets du bas (_).

?type

string

Type de valeur stocké, voir types de valeurs

value

-

Valeur de la configuration

C'est dangereux d'y aller seul, prenez ceci !

La propriété key de l'objet settings doit obéir à l'expression régulière suivante: ^[\w-.]{1,128}$

Types de valeurs

String
Bool
Null
Int
Float
Object
String

String

Les strings sont des chaines de caractères, elles sont limités à 2048 caractères de long.

Exemple

"J'aime les Fraisiers"
Bool

Bool

Les booléens représentent un état logique: vrai ou faux.

Exemple

true
Null

Null

Null représente une valeur nulle, c'est la valeur par défaut pour les clés qui n'ont pas été définies.

Exemple

null
Int

Int

Les integers représentent un nombre entier

Exemple

184
Float

Float

Les floats représentent des nombres à virgules

Exemple

12.54
Object

Object

Les objet sont des objets JSON [EN], ils sont limités à env. 65500 caractères et à 16 de profondeur.

Les tableaux sont considérés comme des objets au niveau de l'api.

Exemples

{
"Paris Brest": {
"quantité": 12,
"qualité": "bonne",
"fait maison": true
},
"Forêt Noire": {
"quantité": 4,
"qualité": "excellente",
"fait maison": false
},
}

put
Créer un paramètre d'application

https://api.edu-focus.org/applications/@current/settings/{setting.key}
Permet de modifier/créer une configuration d'application (global à votre application)
Request
Response
Request
Path Parameters
settings.key
required
string
La clé sous laquelle la valeur doit être stocké, doit obéir à l'expression régulière ^[\w\-\.]{1,128}$
Headers
Authorization
required
string
Entête d'autorisation de type Basic
Body Parameters
value
required
object
La valeur à stocker, peut être de n'importe quel type
Response
201: Created
Configuration crée avec succès
Pas de contenu
204: No Content
Configuration modifiée avec succès
Pas de contenu

get
Obtenir un paramètre d'application

https://api.edu-focus.org/applications/@current/settings/{setting.key}
Permet de récupérer un paramètre enregistré dans votre application, renvoie un l'erreur not_found si la clé n'existe pas.
Request
Response
Request
Path Parameters
setting.key
required
string
Clé sous laquelle la configuration à été enregistré, doit obéir à l'expression régulière ^[\w\-\.]{1,128}$
Headers
Authorization
required
string
Entête d'autorisation de type Basic
Response
200: OK
Lorsque la clé existe, renvoie un objet setting sans clé .
String
Bool
Null
Int
Float
Object
String
{
"key": "key.string",
"value": "J'aime les Fraisiers"
}
Bool
{
"key": "key.bool",
"value": true
}
Null
{
"key": "key.null",
"value": null
}
Int
{
"key": "key.int",
"value": 114
}
Float
{
"key": "key.float",
"value": 12.54
}
Object
{
"key": "key.object",
"value": {
"Paris Brest": {
"quantité": 12,
"qualité": "bonne",
"fait maison": true
},
"Forêt Noire": {
"quantité": 4,
"qualité": "excellente",
"fait maison": false
},
}
}
404: Not Found
La clé n'existe pas
{
"message": "Unkown key",
"code": 0
}

put
Créer un paramètre local sur un utilisateur

https://api.edu-focus.org/users/{user.id}/settings/{setting.key}
Permet de modifier/créer un paramètre local (seul votre application y à accès) sur un utilisateur particulier.
Request
Response
Request
Path Parameters
setting.key
required
string
La clé sous laquelle la valeur doit être stocké, doit obéir à l'expression régulière ^[\w\-\.]{1,128}$
user.id
required
string
Identifiant unique de l'utilisateur sur lequel vous souhaitez enregistrer la cofiguration
Headers
Authorization
required
string
Entête d'autorisation de type Basic
Body Parameters
value
required
object
La valeur à stocker, peut être de n'importe quel type
Response
200: OK

get
Paramètre local d'utilisateur

https://api.edu-focus.org/users/{user.id}/settings/{setting.key}
Permet de récupérer une configuration locale propre à l'utilisateur.
Request
Response
Request
Path Parameters
user.id
required
string
Identifiant unique de l'utilisateur sur lequel vous avez enregistré la configuration
setting.key
required
string
Clée sous laquelle la configuration à été enregistré, doit obéir à l'expression régulière ^[\w\-\.]{1,128}$
Headers
Authorization
required
string
Entête d'autorisation de type Basic
Response
200: OK
Lorsque la clé existe, renvoie la valeur de la configuration directement dans la clé payload
String
Bool
Null
Int
Float
Object
String
{
"code": 200,
"status": "success",
"payload": "J'aime les Fraisiers"
}
Bool
{
"code": 200,
"status": "success",
"payload": true
}
Null
{
"code": 200,
"status": "success",
"payload": null
}
Int
{
"code": 200,
"status": "success",
"payload": 184
}
Float
{
"code": 200,
"status": "success",
"payload": 12.54
}
Object
{
"code": 200,
"status": "success",
"payload": {
"Paris Brest": {
"quantité": 12,
"qualité": "bonne",
"fait maison": true
},
"Forêt Noire": {
"quantité": 4,
"qualité": "excellente",
"fait maison": false
},
}
}
400: Bad Request
ID d'utilisateur invalide/inconnu
L'utilisateur n'a pas autorisé l'applicaion
ID d'utilisateur invalide/inconnu
{
"status": "failure",
"message": "unknown_user",
"code": 400
}
L'utilisateur n'a pas autorisé l'applicaion
{
"status": "failure",
"message": "never_authorized",
"code": 400
}

put
Créer un paramètre global sur un utilisateur

https://api.edu-focus.org/users/@current/settings/{setting.key}
Permet de modifier/créer une configuration globale sur un utilisateur (accessible par toutes les applications ayant été autorisés par l'utilisateur). Vous devez avoir obtenu les scopes settings et settings.edit pour pouvoir utiliser cet endpoint.
Request
Response
Request
Path Parameters
settings.key
required
string
La clé sous laquelle la valeur doit être stocké, doit obéir à l'expression régulière ^[\w\-\.]{1,128}$
Headers
Authorization
required
string
Entête d'autorisation de type Bearer
Body Parameters
value
required
object
La valeur à stocker, peut être de n'importe quel type
Response
201: Created
Configuration crée avec succès
Pas de contenu
204: No Content
Configuration modifiée avec succès
Pas de contenu

get
Obtenir un paramètre global d'utilisateur

https://api.edu-focus.org/applications/@current/settings/{setting.key}
Permet de récupérer une configuration globale sur un utilisateur (accessible par toutes les applications ayant autorisés)
Request
Response
Request
Path Parameters
setting.key
required
string
Clé sous laquelle la configuration à été enregistré, doit obéir à l'expression régulière ^[\w\-\.]{1,128}$
Headers
Authorization
required
string
Entête d'autorisation de type Basic
Response
200: OK
Lorsque la clé existe, renvoie un objet setting sans clé .
String
Bool
Null
Int
Float
Object
String
{
"key": "key.string",
"value": "J'aime les Fraisiers"
}
Bool
{
"key": "key.bool",
"value": true
}
Null
{
"key": "key.null",
"value": null
}
Int
{
"key": "key.int",
"value": 114
}
Float
{
"key": "key.float",
"value": 12.54
}
Object
{
"key": "key.object",
"value": {
"Paris Brest": {
"quantité": 12,
"qualité": "bonne",
"fait maison": true
},
"Forêt Noire": {
"quantité": 4,
"qualité": "excellente",
"fait maison": false
},
}
}
404: Not Found
La clé n'existe pas
{
"message": "Unkown key",
"code": 0
}