API pour les développeurs

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’un utilisateur avec un compte LinuxFr.org et de faire des actions en son nom. L’utilisateur 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 êtes un développeur d’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 de l'utilisateur, il va demander à l’utilisateur 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 l’utilisateur vers LinuxFr.org

La première étape consiste à envoyer l’utilisateur sur LinuxFr.org pour qu’il 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’URL vers laquelle sera redirigé l’utilisateur ou l’utilisatrice 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 scopes demandées, séparés par des espaces (URL encodés en +). Cela indique les actions que l’application pourra faire au nom de l’utilisateur. Exemple : scope=account+board. Par défaut, seul le scope account sera fourni.

L’utilisateur revient sur le site

Si l’utilisateur accepte l’autorisation, il est renvoyé 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’URI vers laquelle l’utilisateur sera redirigé 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

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 utilisateur sur LinuxFr.org.
email: Chaîne de caractères — l’adresse de courriel de l’utilisateur ou l’utilisatrice (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

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.

Poster un journal

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 l’utilisateur 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.

Poster sur la tribune

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 utilisateurs à partir d’applications Web distantes. Il possède une stratégie d’authentification pour LinuxFr.org : omniauth-linuxfr.org.