rvi-http-api-spec v0.0.5

RVI HTTP API Spec (2016-2-23)

• Schema
• Authentication
• Response Codes
  • HTTP 200 OK
  • HTTP 400 Bad Request
  • HTTP 401 Unauthorized
  • HTTP 403 Forbidden
  • HTTP 404 Not Found
  • HTTP 409 Conflict
  • HTTP 429 Too Many Requests
  • HTTP 430 Limit Exceeded
  • HTTP 500 Internal Server Error
  • HTTP 501 Not Implemented

Schema

The API schema is written in Swagger v2.0. To view the schema you can visit this URL or view it locally by following these instructions.

Authentication

Authentication is outside the scope of the API specification and is up to the implementation to decide on what authentication to use.

Response Codes

The RVI HTTP API uses the following HTTP status codes to communicate the various success and error states of requests.

Response types are defined by standard HTTP Status Code Definitions.

Each non-200 status code returns the following format:

{
  "error": "...",
  "message": "..."
}

• error: the error name which corresponds to the error code it was returned with. (e.g. A validation_error corresponds with a HTTP 400)
• message: a more detailed description of the error

HTTP 200 OK

The request was successful, the corresponding resource will be returned.

HTTP 400 Bad Request

The request was malformed due to either bad syntax, or missing parameters

{
  "error": "validation_error",
  "message": "Invalid or missing request parameters."
}

HTTP 401 Unauthorized

The provided credentials were incorrect.

{
  "error": "authentication_error",
  "message": "Invalid or expired token provided."
}

HTTP 403 Forbidden

The credentials provided have insufficient permissions to access the requested resource.

{
  "error": "permission_error",
  "message": "Insufficient permissions to access requested resource."
}

HTTP 404 Not Found

The requested resource does not exist.

{
  "error": "resource_not_found_error",
  "message": "The requested resource was not found."
}

HTTP 409 Conflict

The vehicle is not capable of performing the request in its current state. For example, you cannot open the vehicle's trunk when the vehicle is moving.

{
  "error": "vehicle_state_error",
  "message": "Vehicle is not capable of performing request in current state."
}

HTTP 429 Too Many Requests

The application has sent too many requests and must slow down.

{
  "error": "rate_limiting_error",
  "message": "The application has sent too many requests and cannot be served due to the application's rate limit being exhausted."
}

HTTP 430 Limit Exceeded

The application has sent exceeded its monthly request limit.

{
  "error": "monthly_limit_exceeded",
  "message": "The application has exceeded its monthly limit. Please upgrade the billing plan on the account dashboard."
}

HTTP 500 Internal Server Error

The server unexpectedly had an internal error. This may include failures with vehicle to cloud communications.

{
  "error": "server_error",
  "message": "Unexpected server error, please try again."
}

HTTP 501 Not Implemented

The vehicle is not capable of performing the request. For example, a vehicle without a sunroof cannot perform an 'open sunroof' command.

{
  "error": "not_capable_error",
  "message": "Vehicle is not capable of performing request"
}