Data File Uploads

Data File Upload Process

This page describes the basic process a device should follow to successfully upload data files to Spoke Zone. The header of any data file API upload request should always include an x-access-token field with the device access token.

v2 API

For detailed information about the API endpoints, check out the API Docs.

For detailed information on types of data files, check out this page.

The v2 API uses a two step process to upload a data file.

POST /api/v2/data-files to setup the data file.
- The body of the request should be in JSON format and include a type variable to determine the type of data file to be uploaded.
  - Example body: { "type": "log" }
- If the request was successful, the API will send a 200 response with a JSON object containing the id of the newly created data file.
  - Use the id from this response in the next request to specify which data file ID to upload content to.
POST /api/v2/data-files/:id/file to upload the contents of the data file.
- The body of the request should be in form-data format and requires a files field with the file to be uploaded.
- If the request was successful, the API will send a 200 response with a JSON object containing the file upload path.

Notes

If a device tries to upload an empty file, the Spoke Zone API will reject it with a 400 response and a File is empty message.
Devices should attempt to re-upload data files when the API responds with a 5xx error code.

v1 API

This API is deprecated and should be avoided. It has several subtle bugs and oddities. It is maintained for backwards-compatibility with devices in the field.

The v1 API uses a single endpoint to upload data files to Spoke Zone.

POST /api/v1/deviceUser/read-only/saveLogFile
- The body of the request should be in form-data format and include the following fields:
  - deviceId containing the ID of the device that is trying to upload.
  - uploadType containing the data file type.
  - files containing the data file to be uploaded.
- If the request was successful, the API will send a 200 response containing the file upload path and the new data file's ID.

Notes

If a device tries to upload an empty file, the Spoke Zone API ignores it and sends a 200 response.
- A 40x response can't be sent in these situations because older devices in the field are programmed to attempt to re-upload files when they receive an error response, which would result in devices endlessly attempting to upload empty files.
There is a limit of 6 data file upload requests per device per minute for the v1 route.
- Trying to send more than 6 requests per minute will result in the API sending a 200 response with the message Too many files uploaded, this one is ignored.
Devices should attempt to re-upload data files when the API responds with a 5xx error code.