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 qu'une seule méthode qui permet de s'authentifier sur un site externe avec son compte LinuxFr.org. 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 App_id et un App_secret qui vous serviront lors des échanges OAuth. Le App_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.

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/auth/oauth/authorize

Paramètres

client_id: Chaîne de caractères obligatoire - L'identifiant de l'application lors de l'inscription sur LinuxFr.org (App_id).
redirect_uri: Chaîne de caractères obligatoire - L'URL vers laquelle sera redirigé l'utilisateur après l'autorisation.

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 site peut alors échanger ce code contre le jeton d'autorisation.

GET https://linuxfr.org/auth/oauth/access_token

Paramètres

client_id: Chaîne de caractères obligatoire - L'identifiant de l'application lors de l'inscription sur LinuxFr.org (App_id).
client_secret: Chaîne de caractères obligatoire - Le secret de l'application lors de l'inscription sur LinuxFr.org (App_secret).
code: Chaîne de caractères obligatoire - Le code reçu à l'étape 1.

Réponse

access_token: Chaîne de caractères - Le jeton d'autorisation, également appelé bearer_token.

Méthodes d'API

Authentification

Une fois le bearer_token obtenu, il est possible d'accéder aux informations suivantes de l'utilisateur :

son identifiant de compte (pseudo)
son adresse de courriel
la date de création de son compte.

GET https://linuxfr.org/auth/oauth/user

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"}

Bibliothèques

Omniauth est un 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.