Overview

  1. Authentication
  2. Request Format
  3. Response Format
  4. Request Methods
  5. Errors
  6. Validation Errors
  7. Date Format
  8. API Endpoint
  9. Rate Limits
  10. API Version

Authentication

The API uses bearer tokens for authentication. They are passed in HTTP headers or the query string. The following subsections explain how to obtain an token, and how to use it during API calls.

Obtaining an access token

For your Mention account

To obtain an access token, first you need to create an app. Once you've done this, an access token is readily available at the bottom of the app's details page. Keep it confidential, as it gives full access to your account.

For a third-party account

It's possible to obtain an access token for an other Mention account by using OAuth2. The protocol allows a Mention user to grant permission to access their account, resulting in an access token being delivered.

See OAuth2 for more information.

Passing the access token

The access token can be passed in the Authorization header or in the access_token query string parameter, as explained below.

In the Authorization header

When passing the access token in the Authorization header, it must be prefixed with the string Bearer, followed by a white space.

This is the preferred way to pass tokens, as it doesn't involve URL manipulations.

Example request:

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

In the query string

Example request:

GET /api/accounts/me?access_token=a1d0c6e83f027327d8461063f4ac58a6 HTTP/1.1
Host: api.mention.net

Request format

Clients must send POST and PUT data in JSON format, unless otherwise specified, and specify a Content-Type: application/json header.

Example request:

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

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

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

Response format

Most API endpoints guarantee the response format to be JSON, unless otherwise specified, in the following cases:

  • The request is successfull (status code 200)
  • Validation errors occured (status code 400), and the HTTP request was otherwise valid

Request methods

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 designed 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).

DELETE

DELETE requests delete a resource.

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

Validation errors

Validation errors following a POST or PUT request are notified using a 400 status code. Error details are returned in the body of the response, in JSON format:

{
    "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 are meant to be displayed directly to the user when they're the result of a form submission.

Date format

Dates are formatted using the W3C date format level 6, as defined in https://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

Language

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

Example:

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

See appendix/Languages for more informations.

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.

API endpoint

Resource URLs given in the documentation 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.

API version

Requesting a particular API version can be done by passing an Accept-Version header.

Example request:

GET /api/app/data HTTP/1.1
Host: api.mention.net
Accept-Version: 1.8

When a version is not specified, the version configured in your app's settings is used.

This documentation is about the API version 1.8.