AutoPi REST API

API Endpoint
api.autopi.io

This document describes the REST API available for registered users on AutoPi.io It makes it possible for registered users to retrieve data from their account.

This documentation is seperated into 3 sections.

  • Overview Describes the api, how it works.

  • Authentication How authentication works

  • Resources Describes the main resources available.

  • Raw Data Describes how the user can retrieve raw data.

This API blueprint is subject to change due to technology restrictions, performance optimizations or changing requirements.

Media Type

Where applicable this API MUST use the JSON media-type. Requests with a message-body are using plain JSON to set or update resource states.

Content-type: application/json and Accept: application/json headers SHOULD be set on all requests if not stated otherwise.

Representation of Date and Time

All exchange of date and time-related data MUST be done according to ISO 8601 standard and stored in UTC.

When returning date and time-related data ‘YYYY-MM-DDThh:mm:ss.SSSZ’ format MUST be used.

Status Codes and Errors

This API uses HTTP status codes to communicate with the API consumer.

  • 200 OK - Response to a successful GET, PUT, PATCH or DELETE.

  • 201 Created - Response to a POST that results in a creation.

  • 204 No Content - Response to a successful request that won’t be returning a body (like a DELETE request).

  • 400 Bad Request - Malformed request; form validation errors.

  • 401 Unauthorized - When no or invalid authentication details are provided.

  • 403 Forbidden - When authentication succeeded but authenticated user doesn’t have access to the resource.

  • 404 Not Found - When a non-existent resource is requested.

  • 405 Method Not Allowed - Method not allowed.

  • 406 Not Acceptable - Could not satisfy the request Accept header.

  • 415 Unsupported Media Type - Unsupported media type in request.

Versioning

This API uses Api-Version header to identify requested version. Every minor version SHOULD be backward compatible. However, major versions MAY introduce breaking changes.

Api-Version: 1.0.0

This header SHOULD be present in every request. If not, API MUST use the newest available major release.

If requested version is not available, API SHOULD try to fall back to the next available minor release.

Authentication

  • This API uses JWT for authentication,

  • Every token MUST be refreshed before its expiration time,

  • Token MUST be provided in Authorization header,

  • Toke MUST be provided for each request that requires authentication,

  • This API issues a long-lived access tokens for consumers. A long-lived JWT generally SHOULD lasts about 30 days. If no requests are made, the token MUST expire and the user MUST go through the login flow again to get a new one.

Example Header

Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhNnZoQW8zRkc3dDEiLCJuYW1lIjoiSm9obiBEb2UiLCJpYXQiOjE0NzA1OTg5NzIsImV4cCI6MTQ3MDY4NTM3Mn0.ltA9zZmJKszBJuuV7pTWtY7LzLXrRUfebJDhy_jGMeM

User authentication

Access tokens are required to access nearly all endpoints of this API.

POST api.autopi.io/auth/authenticate
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "login": "ferdinand",
  "password": "D*823#d%d"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "login": {
      "type": "string"
    },
    "password": {
      "type": "string"
    }
  }
}
Responses200
Headers
Content-Type: application/json
Body
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "JSON Web Token."
    }
  }
}

Retrieve a token
POST/auth/authenticate

Allows to retrieve a valid JSON Web Token for username and password.

Endpoint information

Requires authentication No

POST api.autopi.io/auth/refresh-token
Requestsexample 1
Headers
Authorization: bearer <token>
Responses200
Headers
Content-Type: application/json
Body
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "New JWT"
    }
  }
}

Refresh a token
POST/auth/refresh-token

Allows to retrieve a new, valid JSON Web Token based on a valid JSON Web Token.

Expired tokens MUST NOT be refreshed.

Endpoint information

Requires authentication Yes

Resources

Section that describes the different AutoPi website resource that are available.

Trips

GET api.autopi.io/trips?from=&to=
Requestsexample 1
Headers
Authorization: bearer <token>
Responses200401
Headers
Content-Type: application/json
Body
[
  {
    "id": "Xy0MVKupFES9NpmZ9TiHcw",
    "device_id": "AQUDDAAODQcDAAULBA8IDg",
    "trip_started": "2017-01-20T16:54:15.335Z",
    "trip_ended": "2017-01-20T17:05:43.758Z",
    "distance": 6.767,
    "start_position": {
      "lat": 43.32322,
      "lng": 23.32322
    },
    "end_position": {
      "lat": 43.32322,
      "lng": 23.32322
    },
    "tags": [
      {
        "id": 5,
        "name": "private"
      }
    ],
    "error_codes": [
      {
        "id": "CQYJDQcGBQYNBAYNBAsJCw",
        "code": "P0110",
        "message": "Intake Air Temperature Circuit Malfunction",
        "timestamp": "2017-01-20T16:54:15.335Z"
      }
    ],
    "metadata": {
      "dongle_version": "342.34234.2123"
    }
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}
Headers
Content-Type: application/json
Body
{
  "message": "Not authorized"
}

List trips
GET/trips{?from,to}

Retrieves a list of all trips, ordered by date they occurred

Endpoint information

Requires authentication Yes
URI Parameters
HideShow
from
string (optional) 

datetime from.

to
string (optional) 

datetime to.


GET api.autopi.io/trips/Xy0MVKupFES9NpmZ9TiHcw
Requestsexample 1
Headers
Authorization: bearer <token>
Responses200404401
Headers
Content-Type: application/json
Body
{
  "id": "Xy0MVKupFES9NpmZ9TiHcw",
  "device_id": "AQUDDAAODQcDAAULBA8IDg",
  "trip_started": "2017-01-20T16:54:15.335Z",
  "trip_ended": "2017-01-20T17:05:43.758Z",
  "distance": 6.767,
  "start_position": {
    "lat": 43.32322,
    "lng": 23.32322
  },
  "end_position": {
    "lat": 43.32322,
    "lng": 23.32322
  },
  "tags": [
    {
      "id": 5,
      "name": "private"
    }
  ],
  "error_codes": [
    {
      "id": "CQYJDQcGBQYNBAYNBAsJCw",
      "code": "P0110",
      "message": "Intake Air Temperature Circuit Malfunction",
      "timestamp": "2017-01-20T16:54:15.335Z"
    }
  ],
  "metadata": {
    "dongle_version": "342.34234.2123"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "device_id": {
      "type": "string"
    },
    "trip_started": {
      "type": "string",
      "description": "Time and date the trip started."
    },
    "trip_ended": {
      "type": "string",
      "description": "Time and date the trip ended."
    },
    "distance": {
      "type": "number",
      "description": "Distance in km / miles, depending on user settings."
    },
    "start_position": {
      "type": "object",
      "properties": {
        "lat": {
          "type": "number",
          "description": "Latitude"
        },
        "lng": {
          "type": "number",
          "description": "Longitude"
        }
      },
      "description": "Start position."
    },
    "end_position": {
      "type": "object",
      "properties": {
        "lat": {
          "type": "number",
          "description": "Latitude"
        },
        "lng": {
          "type": "number",
          "description": "Longitude"
        }
      },
      "description": "End position."
    },
    "tags": {
      "type": "array",
      "description": "List of tags assigned to trip"
    },
    "error_codes": {
      "type": "array",
      "description": "Error codes reported by the car, during trip"
    },
    "metadata": {
      "type": "object",
      "properties": {
        "dongle_version": {
          "type": "string",
          "description": "Version of the dongle software"
        }
      },
      "description": "Metadata for diagnostics purposes"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "message": "Not found"
}
Headers
Content-Type: application/json
Body
{
  "message": "Not authorized"
}

Trip details
GET/trips/{id}

Retrieves a list of all trips, ordered by date they occurred

Endpoint information

Requires authentication Yes
URI Parameters
HideShow
id
string (required) Example: Xy0MVKupFES9NpmZ9TiHcw

id of the trip.


GET api.autopi.io/tripXy0MVKupFES9NpmZ9TiHcw/rawData
Requestsexample 1
Headers
Authorization: bearer <token>
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "timestamp": "2017-01-20T16:54:15.335Z",
    "speed": 45.3,
    "acc": "Hello, world!",
    "fuel": "Hello, world!",
    "battery_voltage_percentage": 97.6,
    "engine_temperature": 78.5,
    "rpm": 2354,
    "position": {
      "lat": 43.32322,
      "lng": 23.32322
    }
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List raw data for trip
GET/trip{id}/rawData

Retrieves a list of all raw data, ordered by timestamp

Endpoint information

Requires authentication Yes
URI Parameters
HideShow
id
string (required) Example: Xy0MVKupFES9NpmZ9TiHcw

id of the trip.


Raw Data

Raw Data

GET api.autopi.io/rawfrom&to
Requestsexample 1
Headers
Authorization: bearer <token>
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "timestamp": "2017-01-20T16:54:15.335Z",
    "speed": 45.3,
    "acc": "Hello, world!",
    "fuel": "Hello, world!",
    "battery_voltage_percentage": 97.6,
    "engine_temperature": 78.5,
    "rpm": 2354,
    "position": {
      "lat": 43.32322,
      "lng": 23.32322
    }
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List raw data
GET/raw{from,to}

Retrieves a list of all raw data, ordered by timestamp

Endpoint information

Requires authentication Yes
URI Parameters
HideShow
from
string (optional) 

datetime from.

to
string (optional) 

datetime to.


Generated by aglio on 28 Feb 2017