Getting Started

Authentication

Authentication is done using the OAuth2 protocol: an access token is passed in each request for autentication.

Obtaining an access token

Using the authorization endpoint

Redirect the user to the following URI: https://web.mention.net/authorize?client_id={your_client_id}&redirect_uri={redirect_uri}&response_type=code.

This asks the user to grant permission to the application. Once the permission is granted, the user is redirected to the specified URI with a code parameter added in the query string.

The code then must be exchanged with an access token by making a POST or GET request to https://web.mention.net/oauth/v2/token with the following parameters:

client_id

The application’s client id

Example Value: 3_QIP8WdbQkSiiCmrhLRwE7GzPKk1U7eAu

client_secret

The application’s client secret

Example value: x33qytemQZPhmhV62aaToIJIwUcqC2P1k...

redirect_uri

URI to redirect to

Example value: http://example.com

response_type

At this step the response type has to be token to get the access token

Required value: token

code

The auth code obtained at the previous step

Example value: dcf633ef1b86041e24970a06abd54ab7

grant_type

The grant type used: authorization_code

Required value: authorization_code

The request should be done using a POST method, with parameters in application/x-www-form-urlencoded format. GET is also allowed, but discouraged.

The result is a JSON document containing the access token:

{"access_token":"a1d0c6e83f027327d8461063f4ac58a6","expires_in":2592000,"token_type":"bearer","scope":null}

Passing the authorization token

The preferred way to pass the token is through the Authorization header.

In the Authorization header

Example request:

GET /api/accounts/me HTTP/1.1
Host: api.mention.net
Authorization: Bearer a1d0c6e83f027327d8461063f4ac58a6
Accept: application/json

In the query string

Example request:

GET /api/accounts/me?access_token=access_token HTTP/1.1
Host: api.mention.net
Authorization: Bearer a1d0c6e83f027327d8461063f4ac58a6
Accept: application/json

Request format

Clients must send POST data json encoded, with a Content-Type: application/json header.

Example request:

POST /api/accounts HTTP/1.1
Host: api.mention.net
Authorization: Bearer <access_token>
Accept: application/json
Content-Type: application/json
Content-Length: 123

{"name": "John Doe", "email": "test@example.com", "password": "dummy"}

Warning

While the API itself accepts only JSON data, the OAuth2 endpoints accept only application/x-www-form-urlencoded data.

Response format

The API currently sends responses in JSON only. In order to support new formats in the future, it must be requested explicitly.

It can be requested by sending an Accept: application/json header

GET /api/accounts/me HTTP/1.1
Host: api.mention.net
Authorization: Bearer <access_token>
Accept: application/json

Or by appending the .json suffix to URLs

GET /api/accounts/me.json HTTP/1.1
Host: api.mention.net
Authorization: Bearer <access_token>

Note

The prefered method is to send an Accept header.

Errors

Errors are reported by returning one of the following HTTP status codes:

  • 401, 403: The access was denied
  • 404: The resource doesn’t exist
  • 400: Invalid input (query string, post, etc)
  • 429: Rate limited

In addition, POST and PUT requests may return error details in JSON format along with the 400 status code:

{
    "form": {
        "errors": ["optional array of request-wide error messages"],
        "children": {
            "field_name_0": {
                "errors": ["optional array of field-specific error messages"],
            },
            "field_name_n": {
                "..."
            }
        }
    }
}

These error messages should be displayed directly to the user when they are the result of a form submission.

Date format

Dates are formatted using the W3C date format level 6 as defined in http://www.w3.org/TR/NOTE-datetime

This format represents fractions of seconds, in order to support date-based pagination when multiple elements have the same timestamp.

Format: YYYY-MM-DDThh:mm:ss.sTZD Example: 1997-07-16T19:20:30.12345+01:00

The fraction can be safely ignored except when paginating.

Request types

GET

GET requests return a resource or a collection of resources.

POST

POST requests create a resource. They usually return the created resource in the same format a GET request would have returned it.

PUT

PUT requests modify a resource. They usually return the updated resource in the same format a GET request would have returned it.

Any parameter may be omitted in a PUT request (omitted parameters are left unchanged).

This API is design so that a resource obtained via GET or POST can be sent back in a PUT request unchanged. So when sending a PUT request the additional parameters are ignored (e.g. created_at, updated_at, id, etc). Since these parameters could stop being ignored in the future, it is recommended to either not send them, or to take care of sending them unchanged.

DELETE

DELETE requests delete a resource.

Language

Resources may return text translated in some language. The language is taken from the Accept-Language header.

Example:

GET /api/app/data HTTP/1.1
Host: api.mention.net
Accept-Language: fr

User’s language

The user’s language is stored in the language_code property of the account. The client should use this language code in the Accept-Language header when sending requests to the API.

Resource URLs

In the following sections, given resource URLs must be prefixed with https://api.mention.net/api.

Rate Limits

Access to some resources may be rate limited. Limits vary based on resource types and methods.

When the limit is hitten, a 429 status code is returned along with the following headers:

X-Rate-Limit-Reset: unix timestamp at which the limit resets.

Example (PHP)

Authorization code

You first need to obtain an authorization code:

<?php

$url = "https://web.mention.net/authorize?";
$url .= http_build_query(array(
    "client_id" => $client_id,
    "redirect_uri" => "http://example.com/callback",
    "response_type" => "code",
));

header("Location: $url");
exit;

Access token

If the previous step was successful, the user has been redirected to /callback?code=...

You now need to exchange the code with an access token:

<?php

$code = $_GET['code'];

$browser = new Buzz\Browser(new Buzz\Client\Curl);
$url = "https://web.mention.net/oauth/v2/token";
$response = $browser->post($url, array(), array(
    "client_id" => $client_id,
    "client_secret" => $client_secret,
    // this MUST be the same redirect uri than the
    // one passed to /authorize
    "redirect_uri" => "http://example.com/callback",
    "response_type" => "token",
    "code" => $code,
    "grant_type" => "authorization_code",
));

if ($response->getStatusCode() != 200) {
    // handle failure
}

$content = $response->getContent();
$data = json_decode($content);
$access_token = $data->access_token;

Using the access token

Finding account id:

<?php

$access_token = "...";

$browser = new Buzz\Browser(new Buzz\Client\Curl);

// finding account's path

$url = "https://api.mention.net/api/accounts/me";

$response = $browser->get($url, array(
    "Authorization: Bearer $access_token",
    "Accept: application/json",
));

if (200 != $response->getStatusCode()) {
    // handle failure
}

$content = $response->getContent();
$data = json_decode($content);
$path = $data->_links->me->href;

// fetching account

$url = "https://api.mention.net" . $path;

$response = $browser->get($url, array(
    "Authorization: Bearer $access_token",
    "Accept: application/json",
));

if (200 != $response->getStatusCode()) {
    // handle failure
}

$content = $response->getContent();
$data = json_decode($content);
$account = $data->account;

$account_id = $account->id;

Fetching alerts list:

<?php

$browser = new Buzz\Browser(new Buzz\Client\Curl);

$url = "https://api.mention.net/api/accounts/{$account_id}/alerts";

$response = $browser->get($url, array(
    "Authorization: Bearer $access_token",
    "Accept: application/json",
));

if (200 != $response->getStatusCode()) {
    // handle failure
}

// ...