API pour le développement
Principes généraux
LinuxFr.org expose une API REST au format JSON dont l’authentification repose sur OAuth2. Celle‑ci est en cours de développement et ne propose pour le moment que peu de méthodes. Si vous avez des besoins particuliers pour cette API qui ne sont pas encore implémentés, n’hésitez pas à créer une entrée dans le suivi.
OAuth2
OAuth2 est un protocole qui permet à des applications externes de demander l’autorisation d’accéder à des informations privées d’une personne ayant un compte LinuxFr.org et de faire des actions en son nom. La personne n’a pas besoin de fournir son mot de passe au site externe et reste maître des autorisations qu’il a fournies.
Si vous développez des applications web et que vous souhaitez utiliser l’API de LinuxFr.org, la première chose à faire est d’enregistrer votre application. Vous obtiendrez ainsi un identifiant et un secret qui vous serviront lors des échanges OAuth. Le secret doit, comme son nom l’indique, rester secret.
OAuth fonctionne avec un principe de jetons. Quand une application web souhaite accéder aux données confidentielles d’une personne, il va demander à la personne un jeton d’autorisation qui sera délivré par LinuxFr.org, puis il pourra utiliser ce jeton pour accéder aux informations.
LinuxFr.org utilise la bibliothèque Ruby Doorkeeper pour gérer la partie OAuth2. Aussi, nous vous conseillons ces deux liens si vous souhaitez utiliser l’API de LinuxFr.org :
Obtention d’un jeton d’autorisation
Redirection de la personne vers LinuxFr.org
La première étape consiste à envoyer la personne sur LinuxFr.org pour qu’elle puisse accepter ou refuser de donner l’autorisation.
GET https://linuxfr.org/api/oauth/authorize
Paramètres
- client_id
- Chaîne de caractères obligatoire — l’identifiant de l’application lors de l’inscription sur LinuxFr.org.
- redirect_uri
- Chaîne de caractères obligatoire — l’adresse URL vers laquelle sera redirigée la personne après l’autorisation.
- response_type
- Chaîne de caractères obligatoire — code dans le flux d’OAuth2 le plus courant.
- scope
- Chaîne de caractères facultative — la liste des portées ou scope demandées, séparés par des espaces (URL encodés en +). Cela indique les actions que l’application pourra faire au nom de la personne. Exemple : scope=account+board. Par défaut, seule la portée account sera fournie.
La personne revient sur le site
Si la personne accepte l’autorisation, elle est renvoyée sur le site d’origine avec un code temporaire. Le code sera passé dans la query string sur l’URL de redirection. Le site peut alors échanger ce code contre le jeton d’autorisation.
POST https://linuxfr.org/api/oauth/token
Paramètres
- client_id
- Chaîne de caractères obligatoire — l’identifiant de l’application lors de l’inscription sur LinuxFr.org.
- client_secret
- Chaîne de caractères obligatoire — le secret de l’application lors de l’inscription sur LinuxFr.org.
- code
- Chaîne de caractères obligatoire — le code reçu à l’étape 1.
- grant_type
- Chaîne de caractères obligatoire — le format d’authentification utilisé, "authorization_code" pour une application web.
- redirect_uri
- Chaîne de caractères obligatoire — l’adresse URI vers laquelle la personne sera redirigée après obtention du jeton (doit être la même que celle indiquée lors de l’enregistrement de l’application).
Réponse
- access_token
- Chaîne de caractères — le jeton d’autorisation, également appelé bearer_token.
- refresh_token
- Chaîne de caractères.
- expires_in
- Entier — Nombre de secondes avant expiration du jeton d’accès access_token.
Méthodes d’API
Lors de l’appel des méthodes d’API, le bearer_token peut être envoyé soit en paramètre GET ou POST (suivant la méthode requise pour la requête) soit dans les en‑têtes HTTP :
Authorization: Bearer cf075a5c84bbb9489bdca8d18c51937cc69af6b23e06cfc5f0a52e2eef3f6339
Authentification
Portée ou scope nécessaire : account
GET https://linuxfr.org/api/v1/me
Paramètres
- bearer_token
- Chaîne de caractères obligatoire — le jeton d’autorisation.
Réponse
- login
- Chaîne de caractères — l’identifiant du compte sur LinuxFr.org.
- Chaîne de caractères — l’adresse de courriel du compte (note : elle a déjà été validée à l’inscription sur LinuxFr.org et il n’est donc pas souhaitable de revalider cette adresse de courriel).
- created_at
- Chaîne de caractères — la date de création du compte au format ISO.
Exemple de réponse
{"created_at":"2004-07-21T20:23:47+02:00","email":"nono@linuxfr.org","login":"NoNo"}
Proposer une dépêche
Portée ou scope nécessaire : news
POST https://linuxfr.org/api/v1/news
Paramètres
- bearer_token
- Chaîne de caractères obligatoire — le jeton d’autorisation.
- title
- Chaîne de caractères obligatoire — le titre de la dépêche
- section_id
- Entier — l’identifiant de la section (le code source de la page de soumission d’une dépêche permet de trouver la liste des sections).
- wiki_body
- Chaîne de caractères obligatoire — le contenu en Markdown de la première partie de la dépêche
- wiki_second_part
- Chaîne de caractères obligatoire — le contenu en Markdown de la seconde partie de la dépêche
Réponse
- id
- Entier — identifiant de la dépêche qui vient d’être créée.
- section_id
- Entier — identifiant de la section.
- cached_slug
- Chaîne de caractères — le « slug » de la dépeche.
- title
- Chaîne de caractères — le titre de la dépêche.
- body
- Chaîne de caractères — le contenu de la première partie de la dépêche en HTML.
- body
- Chaîne de caractères — le contenu de la seconde partie de la dépêche en HTML.
- created_at
- Chaîne de caractères — les date et heure de création.
- updated_at
- Chaîne de caractères — les date et heure de dernière modification.
- submitted_at
- Chaîne de caractères — les date et heure de soumission en modération.
Publier un journal
Portée ou scope nécessaire : diary
POST https://linuxfr.org/api/v1/journaux
Paramètres
- bearer_token
- Chaîne de caractères obligatoire — le jeton d’autorisation.
- title
- Chaîne de caractères obligatoire — le titre du journal
- wiki_body
- Chaîne de caractères obligatoire — le contenu en Markdown du journal
Réponse
- id
- Entier - identifiant du journal qui vient d’être créé.
- owner_id
- Entier - identifiant de la personne qui vient de créer le journal.
- cached_slug
- Chaîne de caractères — le « slug » du journal.
- title
- Chaîne de caractères — le titre du journal.
- body
- Chaîne de caractères — le contenu du journal en HTML.
- wiki_body
- Chaîne de caractères — le contenu du journal en Markdown.
- truncated_body
- Chaîne de caractères — la version courte du contenu du journal en HTML.
- created_at
- Chaîne de caractères — les date et heure de création.
- updated_at
- Chaîne de caractères — les date et heure de dernière modification.
Publier sur la tribune
Portée ou scope nécessaire : board
POST https://linuxfr.org/api/v1/board
Paramètres
- bearer_token
- Chaîne de caractères obligatoire — le jeton d’autorisation.
- message
- Chaîne de caractères obligatoire — message à poster sur la tribune
- object_type
- Chaîne de caractères facultative — par défaut, le message est posté sur la tribune de test, mais en passant writing, il sera posté sur la tribune de rédaction.
Réponse
- id
- Entier — identifiant du message qui vient d’être créé, le cas échéant.
Exemple de réponse
{"id": 42}
Bibliothèques
OmniAuth est une gem Ruby qui permet d’authentifier des personnes à partir d’applications web distantes. Il possède une stratégie d’authentification pour LinuxFr.org : omniauth-linuxfr.org.