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.
email: 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.