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
Permet de modifier/créer une configuration d'application (global à votre application)
Request
Response
Request
Headers
Authorization
required
string
Entête d'autorisation de type Basic
Body Parameters
key
required
string
La clé sous laquelle la valeur doit être stocké, doit obéir à l'expression régulière ^[\w\-\.]{1,128}$
value
required
object
La valeur à stocker, peut être de n'importe quel type
Response
200: OK
Configuration modifiée avec succès
{
"status": "success",
"message": "updated",
"code": 200
}
201: Created
Configuration crée avec succès
{
"status": "success",
"message": "created",
"code": 201
}

get
Obtenir un paramètre d'application

https://api.edu-focus.org/applications/@current/settings/{config.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
config.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 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
},
}
}

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

https://api.edu-focus.org/users/{user.id}/settings
Request
Response
Request
Path Parameters
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
key
required
string
La clé sous laquelle la valeur doit être stocké, doit obéir à l'expression régulière ^[\w\-\.{1.128}]$
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
}