AdA Risques – Spécifications de l'API

L’API de l’AdA Risques a vocation à remplacer l’application e-net historique à travers une interface utilisateur modernisée.

L’API permettra de centraliser les flux de données pour les différentes pages (site vitrine, e-net…) et services consommateurs.

Principes

Pas d'état

L’API doit être sans état, l’autorisation est assurée par un jeton (JWT) obtenu après authentification sur une extrémité spécifique de l’API.
Pas d’information sensible dans les URL

Dans les cas où une analyse des flux HTTPS est mise en place, les URL sont généralement journalisée par l’entité.

Des UUID (version 4) seront donc utilisés pour identifier toutes les ressources exposées.

Alumni

Retourne les enregistrements relatifs aux alumni (anciens et plus généralement membres).

/v2/alumni (alias : /v2/anciens)

L'accès à la collection alumni nécessite d'être authentifié.

Lister les alumni (annuaire)

[
	{
		"id": "100cf457-b78e-4c57-bdf0-62bf16370700",
		"nom": "Doe",
		"prenom": "John",
		"filiere": "MRI",
		"promotion": 2011,
		"avatar": true
	},
	{
		"id": "e7b3ebfb-a6f9-41e9-b141-a78d8e2fbe03",
		"nom": "Nymous",
		"prenom": "Ano",
		"filiere": "STI",
		"promotion": 2014,
		"avatar": false
	}
]

Liste la fiche sommaire de tous les alumni.

Requête HTTP

GET /v2/alumni

La liste peut être filtrée à l’aide d’une combinaison des arguments GET suivants :

filiere (chaîne) : "MRI", "STI", "ERE" ou "null"
promotion (entier) : année de promotion

En étant authentifié avec des privilèges administrateur, les filtres suivants sont également disponibles :

exercice (chaîne) : identifiant d’un exercice
valide (booléen) : compte validé

Créer un alumni

{
	"id": "100cf457-b78e-4c57-bdf0-62bf16370700",
	"nom": "Doe",
	"prenom": "John",
	"filiere": "MRI",
	"promotion": 2011,
	"avatar": false,
	"contacts": [],
	"active": true,
}

Retourne les données de la fiche contact de l’alumni.

Requête HTTP

PUT /v2/alumni

Corps JSON de requête

nom (chaîne) : nom
prenom (chaîne) : prénom
filiere (chaîne ou null) : MRI, STI, ERE
promotion (entier) : année de promotion
email (chaîne) : adresse de courriel privée de l’alumni

Voir un alumni (fiche contact)

{
	"id": "100cf457-b78e-4c57-bdf0-62bf16370700",
	"nom": "Doe",
	"prenom": "John",
	"filiere": "MRI",
	"promotion": 2011,
	"avatar": true,
	"contacts": [
		{ "id": "32e050f2-b664-465f-8330-244e49752446", "type": "email", "value": "adresse@mail.com" },
		{ "id": "9c25e5e0-a7c7-424a-b86f-9d99c0321d35", "type": "adresse", "value": "1 rue d'Ici, 99000 Ville, France" },
		{ "id": "d2fe987b-a280-4469-b96f-fb4ffda2e232", "type": "telephone", "value": "06 78 91 23 45" },
		{ "id": "4e13f43f-6033-4c64-ac73-99cd4a59c312", "type": "twitter", "value": "@user" },
		{ "id": "d5a4f70e-d48a-4e23-81df-4a4b094d9999", "type": "linkedin", "value": "in/user" }
	],
	"active": true,
	"adherent": false,
	"adhesions": [
		{ "id": "9c25e5e0-a7c7-424a-b86f-9d99c0321d35", "libelle": "2013-2014" },
		{ "id": "d2fe987b-a280-4469-b96f-fb4ffda2e232", "libelle": "2014-2015" },
		{ "id": "4e13f43f-6033-4c64-ac73-99cd4a59c312", "libelle": "2017-2018" },
		{ "id": "d5a4f70e-d48a-4e23-81df-4a4b094d9999", "libelle": "2019" },
	]
}

Retourne les données de base d’un alumni.

Requête HTTP

GET /v2/alumni/id

id (chaîne, UUID) : identifiant de l’alumni

Les attributs active, adherent et adhesions ne sont visibles qu'en étant authentifié avec des privilèges administrateur.

Modifier un alumni

{
	"id": "100cf457-b78e-4c57-bdf0-62bf16370700",
	"nom": "Doe",
	"prenom": "John",
	"filiere": "MRI",
	"promotion": 2011,
	"avatar": true,
	"contacts": [
		{ "id": "32e050f2-b664-465f-8330-244e49752446", "type": "email", "value": "adresse@mail.com" },
		{ "id": "9c25e5e0-a7c7-424a-b86f-9d99c0321d35", "type": "adresse", "value": "1 rue d'Ici, 99000 Ville, France" },
		{ "id": "d2fe987b-a280-4469-b96f-fb4ffda2e232", "type": "telephone", "value": "06 78 91 23 45" },
		{ "id": "4e13f43f-6033-4c64-ac73-99cd4a59c312", "type": "twitter", "value": "@user" },
		{ "id": "d5a4f70e-d48a-4e23-81df-4a4b094d9999", "type": "linkedin", "value": "in/user" }
	]
	"active": true
}

Requête HTTP

PUT /v2/alumni/id

PATCH /v2/alumni/id

id (chaîne, UUID) : identifiant de l’alumni

Corps JSON de requête

nom (chaîne) : nom
prenom (chaîne) : prénom
filiere (chaîne ou null) : MRI, STI, ERE
promotion (entier) : année de promotion
email (chaîne) : adresse de courriel privée de l’alumni
active (booléen) : compte activé

Supprimer un alumni

Supprime toutes les données relatives à un alumni.

Requête HTTP

DELETE /v2/alumni/id

id (chaîne, UUID) : identifiant de l’alumni

Voir les adhésions

[
    { "id": "9c25e5e0-a7c7-424a-b86f-9d99c0321d35", "libelle": "2013-2014" },
    { "id": "d2fe987b-a280-4469-b96f-fb4ffda2e232", "libelle": "2014-2015" },
    { "id": "4e13f43f-6033-4c64-ac73-99cd4a59c312", "libelle": "2017-2018" },
    { "id": "d5a4f70e-d48a-4e23-81df-4a4b094d9999", "libelle": "2019" },
]

Retourne les exercices d’adhésion d’un alumni.

Requête HTTP

GET /v2/alumni/id/adhesions

id (chaîne, UUID) : identifiant de l’alumni

Enregistrer une adhésion

[
    { "id": "9c25e5e0-a7c7-424a-b86f-9d99c0321d35", "libelle": "2013-2014" },
    { "id": "d2fe987b-a280-4469-b96f-fb4ffda2e232", "libelle": "2014-2015" },
    { "id": "4e13f43f-6033-4c64-ac73-99cd4a59c312", "libelle": "2017-2018" },
    { "id": "d5a4f70e-d48a-4e23-81df-4a4b094d9999", "libelle": "2019" },
]

Requêtes HTTP

POST /v2/alumni/id/adhesions

PUT /v2/alumni/id/adhesions/exercice

id (chaîne, UUID) : identifiant de l’alumni
exercice (chaîne, UUID) : identifiant de l’exercice d’adhésion

Sans l’identifiant de l’exercice d’adhésion, l’adhésion sera enregistrée pour l’exercice courant.

Supprimer une adhésion

Requête HTTP

DELETE /v2/alumni/id/adhesions/exercice

id (chaîne, UUID) : identifiant de l’alumni
exercice (chaîne, UUID) : identifiant de l’exercice d’adhésion

Profil

Retourne les enregistrements relatifs à son propre profil.

/v2/profil

L'accès à la collection profil nécessite d'être authentifié.

Voir sa fiche contact

{
	"id": "100cf457-b78e-4c57-bdf0-62bf16370700",
    "email": "john.doe@example.com",
	"nom": "Doe",
	"prenom": "John",
	"filiere": "MRI",
	"promotion": 2011,
	"avatar": true,
	"contacts": [
		{ "id": "32e050f2-b664-465f-8330-244e49752446", "type": "email", "value": "adresse@example.com" },
		{ "id": "9c25e5e0-a7c7-424a-b86f-9d99c0321d35", "type": "adresse", "value": "1 rue d'Ici, 99000 Ville, France" },
		{ "id": "d2fe987b-a280-4469-b96f-fb4ffda2e232", "type": "telephone", "value": "06 78 91 23 45" },
		{ "id": "4e13f43f-6033-4c64-ac73-99cd4a59c312", "type": "twitter", "value": "@user" },
		{ "id": "d5a4f70e-d48a-4e23-81df-4a4b094d9999", "type": "linkedin", "value": "in/user" }
	],
    "adherent": false,
	"adhesions": [
		{ "id": "9c25e5e0-a7c7-424a-b86f-9d99c0321d35", "libelle": "2013-2014" },
		{ "id": "d2fe987b-a280-4469-b96f-fb4ffda2e232", "libelle": "2014-2015" },
		{ "id": "4e13f43f-6033-4c64-ac73-99cd4a59c312", "libelle": "2017-2018" },
		{ "id": "d5a4f70e-d48a-4e23-81df-4a4b094d9999", "libelle": "2019" },
	]
}

Retourne sa propre fiche contact

Requête HTTP

GET /v2/profil

Modifier ses identifiants

Requête HTTP

PATCH /v2/profil/credentials

Corps JSON de requête

email (chaîne) : adresse de courriel privée de l’alumni

old_password (chaîne) : ancien mot de passe
new_password (chaîne) : nouveau mot de passe

Ajouter un point de contact

{
	"id": "32e050f2-b664-465f-8330-244e49752446",
	"type": "email",
	"value": "adresse@mail.com"
}

Créer un point de contact

Requête HTTP

POST /v2/profil/contacts

id (chaîne, UUID) : identifiant de l’alumni

Corps JSON de la requête

type (chaîne) : type de point de contact
value (chaine) : texte du point de contact

Modifier un point de contact

{
	"id": "32e050f2-b664-465f-8330-244e49752446",
	"type": "email",
	"value": "adresse@mail.com"
}

Retourne la fiche contact d’un alumni.

Requête HTTP

PUT /v2/profil/contacts/contact

id (chaîne, UUID) : identifiant de l’alumni
contact (chaîne, UUID) : identifiant du point de contact

Corps JSON de la requête

type (chaîne) : type de point de contact
value (chaine) : texte du point de contact

Supprimer un point de contact

Supprime un point de contact.

Requête HTTP

DELETE /v2/profil/contacts/contact

id (chaîne, UUID) : identifiant de l’alumni
contact (chaîne, UUID) : identifiant du point de contact

Exercices

Permet de manipuler les exercices (libellé, dates…) et leurs statistiques

/v2/exercices

L'accès à la collection exercice et à ses statistiques nécessite d'être authentifié avec des privilèges administrateur (sauf exceptions).

Lister les exercices

[
    {
        "id": "67d0d598-0a45-4c5c-ae96-c338cf1de708",
        "libelle": "2016-2017",
        "debut": "2016-08-01",
        "fin": "2017-07-31"
    },
    {
        "id": "730ada4e-c1a7-4d88-8738-7ec6be5530b5",
        "libelle": "2017-2018",
        "debut": "2017-08-01",
        "fin": "2018-12-31",
        "actuel": true
    },
    {
        "id": "8d9ad887-b53c-4852-b778-ca5447e1e907",
        "libelle": "2019",
        "debut": "2019-01-01",
        "fin": "2019-12-31"
    }
]

Liste tous les exercices

Requête HTTP

GET /v2/exercices

Créer un exercice

{
    "id": "67d0d598-0a45-4c5c-ae96-c338cf1de708",
    "libelle": "2016-2017",
    "debut": "2016-08-01",
    "fin": "2017-07-31",
    "stats": {
        "adherents": 0,
        "eleves": 0
    }
}

Requête HTTP

POST /v2/exercices

Corps JSON de la requête

libelle (chaîne) : libellé de l’exercice (ex : 2017-2018)
debut (chaîne, date ISO 8601) : date de début de l’exercice
fin (chaîne, date ISO 8601) : date de fin de l’exercice

Si le corps de la requête est nul, un exercice d’un an est généré à partir de la date de fin la plus avancée.

Voir un exercice

{
    "id": "67d0d598-0a45-4c5c-ae96-c338cf1de708",
    "libelle": "2016-2017",
    "debut": "2016-08-01",
    "fin": "2017-07-31",
    "stats": {
        "adherents": 81,
        "eleves": 13
    }
}

Retourne les détails d’un exercice et ses statistiques

Requête HTTP

GET /v2/exercices/id

id (chaîne, UUID) : identifiant de l’exercice

Modifier un exercice

{
    "id": "67d0d598-0a45-4c5c-ae96-c338cf1de708",
    "libelle": "2016-2017",
    "debut": "2016-08-01",
    "fin": "2017-07-31",
    "stats": {
        "adherents": 81,
        "eleves": 13
    }
}

Requête HTTP

PUT /v2/exercices/id

id (chaîne, UUID) : identifiant de l’exercice

Corps JSON de la requête

libelle (chaîne) : libellé de l’exercice (ex : 2017-2018)
debut (chaîne, date ISO 8601) : date de début de l’exercice
fin (chaîne, date ISO 8601) : date de fin de l’exercice