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 :

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

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 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 token (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 de l'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 headers 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 (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, format ISO.

Exemple de réponse

{"created_at":"2004-07-21T20:23:47+02:00","email":"nono@linuxfr.org","login":"NoNo"}

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 - Id 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.