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 :

  1. API endpoint descriptions and examples ;
  2. Interacting as an OAuth client with Doorkeeper.

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.