SayVU Public API (1.0 beta)

This specification describes the SayVU Public API.

This API is a REST API.

The API is currently in beta. We will attempt to avoid breaking changes but cannot guarantee it yet.

Versions will not be incremented for non-breaking changes. This may include new endpoints, properties, and parameters, as well as additional data in the responses.

Minor versions are expected to be mostly backwards compatible, though there may be deprecations and minor breaking changes.

Major versions are very likely to have significant breaking changes.

All properties and parameters in both the requests and responses use lower_snake_case.

All url paths (the part after the origin) use lower-kebab-case.

Requests must be authenticated by passing api keys as bearer tokens.

Add the api key to the Authorization header, with the following structure:

Authorization: Bearer ak_{api_key}

(Note the ak_ prefix preceding the api key.)

You cannot currently generate your own api keys. Contact support to get an api key.

The api accepts the following types of requests:

• Requests without bodies

  These are typically GET requests that fetch data.

• Requests with application/json bodies

  These are typically POST and PUT requests for creating or editing data.

  These requests do not support file uploads.

  These requests always require a root data property with the content of the request. In some cases, additional properties may be supported to modify the behavior of the endpoint.

  {
      "data": /* content goes here */
      "meta": /* optional metadata that affects the endpoint's behavior */ 
  }
  

• Requests with multipart/form-data bodies

  These are always POST or PUT requests and always support one or both of the following properties:

  • files for the binary files
  • data for the stringified json content, compliant with the application/json content type

  Each request specifies which properties are supported and/or mandatory or optional.

All endpoints return their results with a common format.

The responses are always application-json.

Responses have the following content:

• They always have a data property with the content produced by the request.
• They may have a link property whose children are discoverable links relevant to the request.
• They may have a meta property, whose children describe the result and any other relevant metadata about the request.
• If the request produces errors, they may have an errors property listing the error details. See below.

The response errors property is an array consisting of one or more error objects.

Each error object has the following properties:

• code (mandatory) - Represents the type of error
• message (optional) - Provides additional details about the error, as necessary

The api may produce the following error codes:

• INPUT_SCHEMA_VIOLATION

  This error code indicates that the structure of the content of the request does not match the schema defined for the request. This can happen, for example, if the data property is passed as an object for a request that expects it to be an array. The violating properties or additional info will usually be provided in the message property.

  The response status code should be 400 and the request will not be processed.

• MISSING_INPUT_DATA

  This error code indicates that values for mandatory input properties have not be been supplied. This can happen, for example, if a mandatory property is not specified or is null or undefined, or for an empty array in a request that requires at least one item, and so forth. The violating properties or additional info will usually be provided in the message property.

  The response status code should be 400. The request will usually not be processed, though it may be partially processed under some circumstances.

• MISSING_REPORTER

  This error code indicates a problem with the reporter associated with the api key.

  The response status code should be 401. However, this error can occur during processing, which means that the state of the request may be in a partial state.

• NO_FILES_UPLOADED

  This error code indicates that no files were uploaded to a request that requires at least one file.

  The response status code should be 400 and the request will not be processed.

• REPORT_NOT_FOUND

  This error code indicates that the report specified in the url could not be found.

  The response status code should be 404 and the request will not be processed.

• UNAUTHORIZED

  This error code indicates an auth error.

  The response status code should be 401 and the request will not be processed.

• UNEXPECTED_ERROR

  This error code indicates that an unexpected error occurred.

  The response status code should be 500 and the request will not be processed.