Summary

This is the version 1 of the Rexpense API. You'll find the navigation menu on the left sidebar, the resources documentation on the middle section and the examples on the right sidebar. All codes and endpoints will be aligned with its subject. If you have any doubts or suggestions, fell free to get in touch via support@rexpense.com.

Authentication

Before accessing the Rexpense API you must create an account at Rexpense. If you already have one, you need to get your API Token on Passaporte Web security page. This token is required in all requests in the API to identify you.

Authentication in the Rexpense API is carried out using HTTP Basic, however you'll not use your login and password as usual. You'll have to use your API Token as your login and an empty password (if your HTTP client requires a password, you can type X).

API Token authentication

Request Example

$ curl -i -u $YOUR_API_TOKEN:X
  -H 'User-Agent: My App 1.0' \
  -H 'Accept: application/json' \
  -H 'Content-type: application/json' \
  -X GET https://app.rexpense.com/api/v1

Requirements

In all requests you have to inform the User-Agent HTTP header. It is mandatory and you'll not be able to access any information if this header is omitted.

User-Agent header requirement

Request Example

$ curl -i -u $YOUR_API_TOKEN:X
  -H 'User-Agent: My App 1.0' \
  -H 'Accept: application/json' \
  -H 'Content-type: application/json' \
  -X GET https://app.rexpense.com/api/v1

Conventions

The Rexpense API uses some conventions to facilitate and standardize the comunication.

Request and Response format

The only format available for request and response is JSON.

JSON format

Example Request

$ curl -i -u $YOUR_API_TOKEN:X
  -H 'User-Agent: My App 1.0' \
  -H 'Accept: application/json' \
  -H 'Content-type: application/json' \
  -X GET https://app.rexpense.com/api/v1

Example Response

    {
      "key": "value"
    }

Locale

For now, the Rexpense API supports two locales.

Language Symbol
English (US) en
Portuguese (Brazil) pt

There are three ways that the locale can be set. First by the HTTP header Accept-Language, second by the user's preference, and third by the system default locale (en). They have the following precedence: Accept-Language header > user's preference > system default.

List all available Locales

Example Request

GET /api/v1/locales

Example Response

    {
      "locales": [
        {"pt": "Português (Brasil)"},
        {"en": "English (US)"}
      ]
    }

Use a specific Accept-Language by header

Example Request

$ curl -i -u $YOUR_API_TOKEN:X
  -H 'User-Agent: My App 1.0' \
  -H 'Accept: application/json' \
  -H 'Content-type: application/json' \
  -H 'Accept-Language: pt' \
  -X GET https://app.rexpense.com/api/v1

Set a Locale as the user's preference

Definition

PATCH /api/v1/user/preferences

Request Example

$ curl -i -u $YOUR_API_TOKEN:X
  -H 'User-Agent: My App 1.0' \
  -H 'Accept: application/json' \
  -H 'Content-type: application/json' \
  -H 'Accept-Language: pt' \
  -X PATCH https://app.rexpense.com/api/v1/user/preferences \
  -d '{"user":{"locale":"pt"}}'
    
    {
      "user": {
        "locale": "pt"
      }
    }

Timezone

All data received and sent through the Rexpense API will be based on UTC timezone. However, a user can have a preference for a timezone. This timezone will be used for presenting and notification purpose. It will not affect the response in API (it will be still in UTC).

List all timezones

Definition

GET /api/v1/timezones

Request Example

$ curl -i -u $YOUR_API_TOKEN:X
  -H 'User-Agent: My App 1.0' \
  -H 'Accept: application/json' \
  -H 'Content-type: application/json' \
  -X GET https://app.rexpense.com/api/v1/timezones

Response Example

    [
      {
        "name": "Brasilia",
        "description": "(GMT-03:00) Brasilia"
      },
      {
        "name": "Bogota",
        "description": "(GMT-05:00) Bogota"
      },
      ...
    ]

Set Timezone by user's preferences

Definition

PATCH /api/v1/user/preferences

Request Example

$ curl -i -u $YOUR_API_TOKEN:X
  -H 'User-Agent: My App 1.0' \
  -H 'Accept: application/json' \
  -H 'Content-type: application/json' \
  -H 'Accept-Language: pt' \
  -X PATCH https://app.rexpense.com/api/v1/user/preferences \
  -d '{"user":{"timezone":"Brasilia"}}'

Response Example

    {
      "user": {
        "timezone": "Brasilia"
      }
    }

Date and Time formats

All dates and times will be formatted according to the ISO 8601 standard, and will always be given in UTC / GMT time zone.

You must also always provide your date and time values in the same ISO 8601 format and in the UTC time zone.

Type Format Example
Date YYYY-mm-dd 2014-05-29
Datetime YYYY-mm-ddTHH:MM:SSZ 2014-05-29T19:11:34Z

Numbers format

All numbers will be provided as either integers or floats, native to JSON.

Currencies code

All currencies code are based according in ISO 4217. You must provide a code that is included in this list.