Skip to main content

JSON API

JSON-API is a specification for building REST APIs for CRUID (create, read, update, and delete) operations.

Similar to GraphQL, it allows the client to control what is returned in the response payload. Unlike GraphQL, the JSON-API spells out hot to perform file operations instead of file metadata operations.

JSON-API has no standardized schema introspection. However, Athena adds this capability to file service by exporting an Open API Initiative document (formerly known as Swagger). The json-api specification is the best reference for understanding JSON-API. The following sections describe commonly used JSON-API features as well as Athena additions for filtering and swagger.

Hierarchical URLs​

Athena generally follows the JSON-API recommendations for URL design.

Athena currently requires all files to be addressed by ID within a URL parameter. For example, downloading a file with an ID of 1 must be fully qualified by ID: /file/download?fileId=1

File Identifiers​

Athena supports two mechanisms by which a newly uploaded file is assigned an ID:

  1. The file is assigned by a fixed-length ID and saved in the data store.
  2. The application provides an ID which is generated by a custom FileIdGenerator implementation by the application
note

In order to replace the default file ID generator, the custom implementation must be bound explicitly through BinderFactory. For example, when application implements a generator called 'MyIdGenerator', it will load via

@Override
protected Class<? extends FileIdGenerator> buildFileIdGenerator() {
    return MyIdGenerator.class
}

For more info on custom binding, please check out Basic Dependency Injection using Jersey's HK2