Skip to main content

Files API

The Files HTTP API allows for storing files in the Actyx swarm and retrieving them as well as naming them for easy access. Files are replicated to all other Actyx nodes in the same swarm, thus making files available locally on each node. A typical use-case is making applications (e.g. SPAs or node apps) accessible locally on Actyx nodes, i.e. rolling out applications.

The Files API is reachable at the following base URI: http://localhost:4454/api/v2/files.

Files can be uploaded by using POST with the file contents as multipart/formdata against the API endpoint. Uploading a file returns a content identifier (CID) which is a unique hash computed based on the file's contents.

The Actyx Naming Service (ANS) provides for attaching names to CIDs. To retrieve files, either these names or CIDs can be used: http://localhost:4454/api/v2/files/<cid> or http://<name>.actyx.localhost:4454/<optional path>. You can also update that name to point to a different CID, allowing you to roll out new versions of a file/app.

The API endpoint requires token authentication using the Authorization: Bearer <Actyx Auth Token> header.

A sample 'Uploader' HTML page to get you started is available on GitHub. It also supports uploading multiple files / folders conveniently as required when pushing web apps.

Prerequisites#

Communication with the Events API needs to be authenticated. Therefore an auth token which is associated with the requesting app needs to be retrieved from the Auth API. This token then needs to be passed in the Authorization header with every request to the Events API. In the following examples we will use the $AUTH_TOKEN environment variable which can be initialized with

export AUTH_TOKEN="$(curl -s localhost:4454/api/v2/auth -d'{"appId": "com.example.app","displayName": "Example App","version": "1.0"}' -H "Content-Type: application/json" | jq -r '.token')"

Attempting to call the files API endpoint without valid authorization will result in an error response with HTTP 401 Unauthorized.

Error message for missing authorization header
{  "code": "ERR_MISSING_AUTH_HEADER",  "message": "\"Authorization\" header is missing."}
Error message for invalid authorization header
{  "code": "ERR_TOKEN_INVALID",  "message": "Invalid token: 'my invalid token'. Not a signed token. Please provide a valid bearer token."}

While the following examples use cURL, other command-line or graphical tools (e.g. Postman) would work as well.

Upload File#

Files are uploaded by POSTing the file content to api/v2/files. It requires authentication and returns the files CID on success.

Request#

  • Endpoint: http://localhost:4454/api/v2/files
  • HTTP method: POST
  • HTTP headers:
    • Content-Type: must be multipart/formdata
    • Authorization: must be Bearer <valid Actyx Auth Token>
  • Request body: The file contents as multipart/formdata using the file key, the contents and a file name as the form data's key/value pairs.

Response#

  • HTTP headers:
    • Content-Type is text/plain
  • HTTP Status:
    • 200 on success
    • 401 if auth header is missing or invalid

The response body is the CID of the uploaded file.

Retrieve file by CID#

To retrieve a file's contents by its CID, you GET the file from api/v2/files/<CID> providing a valid authentication token.

If the entry points to a directory, a directory listing in JSON is returned when requested with the content type application/json.

If the content type is text/html, a directory listing is returned if the directory does not contain an index.html file. If it does, index.html is returned.

You can navigate a directory by appending a relative path within it to the URL.

Request#

  • Endpoint: http://localhost:4454/api/v2/files/<cid>
  • HTTP method: GET
  • HTTP headers:
    • Authorization: must be Bearer <valid Actyx Auth Token>

Response#

The contents of the file identified by the given CID.

  • HTTP Status:
    • 200 on success
    • 401 if auth header is missing or invalid
    • 405 if the CID is invalid.

Retrieve file by name (API)#

To retrieve a file's contents by its name, you GET the file from api/v2/files/<name>.

If the entry points to a directory, a directory listing in JSON is returned when requested with the content type application/json.

If the content type is text/html, a directory listing is returned if the directory does not contain an index.html file. If it does, index.html is returned.

You can navigate a directory by appending a relative path within it to the URL.

Request#

  • Endpoints:
    • http://localhost:4454/api/v2/files/<name> (requires authentication)
  • HTTP method: GET
  • HTTP headers:
    • Authorization: must be Bearer <valid Actyx Auth Token> when using api/v2/files

Response#

The contents of the file identified by the given name.

  • HTTP Status:
    • 200 on success
    • 401 if auth header is missing or invalid
    • 405 if the CID is invalid.

Retrieve file by name (ANS)#

ANS provides read-only access to named CIDs through http://<name>.actyx.localhost:4454 without authentication. This method is especially useful when opening Actyx apps in the browser.

If the entry points to a directory, a directory listing in JSON is returned when requested with the content type application/json.

If the content type is text/html, a directory listing is returned if the directory does not contain an index.html file. If it does, index.html is returned.

You can navigate a directory by appending a relative path within it to the URL.

Request#

  • Endpoints:
    • http://<name>.actyx.localhost:4454
  • HTTP method: GET

Response#

The contents of the file identified by the given name.

  • HTTP Status:
    • 200 on success
    • 401 if auth header is missing or invalid
    • 405 if the CID is invalid.

Assign name to a CID#

To be able to use human-understandable names when retrieving files, you can assign names to CIDs by PUTting the name to api/v2/files/<name to assign>.

If the name already exists, it is updated to point to the given CID. Names that represent valid CIDs are rejected.

Request#

  • Endpoint: http://localhost:4454/api/v2/files/<name>
  • HTTP method: PUT
  • HTTP headers:
    • Authorization: must be Bearer <valid Actyx Auth Token>
  • Body: The CID to assign the name to

Response#

  • HTTP Status:
    • 200 on success
    • 401 if auth header is missing or invalid
    • 405 if the CID is invalid.

Remove CID name#

  • Endpoint: http://localhost:4454/api/v2/files/<name>
  • HTTP method: DELETE
  • HTTP headers:
    • Authorization must be Bearer <valid Actyx Auth Token>

Response#

  • HTTP Status:
    • 200 on success
    • 401 if auth header is missing or invalid
    • 405 if the name does not exist