# Storage APIs
The Storage APIs are split into 2 categories: Object Storage and Global Storage. The Object Storage is individual for each information model object. As an example, it is used by the devices when they upload files. The Global Storage is shared, it is not scoped to any particular objectId. As an example, it is used when invoking commands with file inputs. The files are then sent to the target device from the Global Storage.
NOTE
A few of the endpoints have the {path} parameter in their URLs. Users can pass
any complex file path into this parameter as they see fit. However, if the path
contains a '/' it will cause an error. The value being passed to the parameter
must have the '/' encoded as
'%2F' for the path to work as expected.
Example of an encoded url:
objects/<objectID>/models/abb.ability.device/files/example%2Fmyfile.json. In
this case the path is "example/myfile.json"
# GET Search for Files in an Object Storage
# /storage/object/files/search
# Description
Filterable properties:
- objectId: string
- model: string
- path:
string
- timestamp: dateTime
# Parameters
| Name | Located in | Description | Required | Schema |
|---|---|---|---|---|
| filter | query | A boolean expression used to filter the results | Yes | WhereClause |
| limit | query | Limit the number of returned values. Defaults to 100 if not specified | No | LimitClause |
# Responses
| Code | Description | Schema |
|---|---|---|
| 200 | Success | FileServiceResponse |
| 400 | Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc | ServiceErrors |
| 401 | Not Authorized. Either the Access token is missing or the access token validation failed | |
| 403 | Access Forbidden. Requesting entity does not have enough permissions to access the resource | |
| 429 | Too many requests - indicates the user has sent too many requests in a given amount of time | ServiceErrors |
| 500 | Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors | ServiceErrors |
# POST Upload a File into an Object Storage
# objects/{objectId}/models/{modelId}/files/{path}
# Description
The body of the request contains the file to be uploaded. The content type should be set to application/octet-stream.
TIP
There is also a legacy endpoint: POST storage/object/files/upload. The legacy endpoint contained both the file as well as object data (such as the objectId and modelId) in the body of the payload. The content type in this scenario was multipart/form-data.
# Responses
| Code | Description | Schema |
|---|---|---|
| 201 | File was uploaded successfully | |
| 400 | Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc | ServiceErrors |
| 401 | Not Authorized. Either the Access token is missing or the access token validation failed | |
| 403 | Access Forbidden. Requesting entity does not have enough permissions to access the resource | |
| 429 | Too many requests - indicates the user has sent too many requests in a given amount of time | ServiceErrors |
| 500 | Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors | ServiceErrors |
# GET Download a File from an Object Storage
# objects/{objectId}/models/{modelId}/files/{path}
# Description
TIP
There is also a legacy endpoint: POST storage/object/files/download. The HTTP verb has changed from POST to GET, so a body is no longer needed for the new endpoint.
# Responses
| Code | Description | Schema |
|---|---|---|
| 200 | Success | |
| 400 | Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc | ServiceErrors |
| 401 | Not Authorized. Either the Access token is missing or the access token validation failed | |
| 403 | Access Forbidden. Requesting entity does not have enough permissions to access the resource | |
| 404 | File not found | ServiceErrors |
| 429 | Too many requests - indicates the user has sent too many requests in a given amount of time | ServiceErrors |
| 500 | Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors | ServiceErrors |
# DELETE Remove a File from an Object Storage
# objects/{objectId}/models/{modelId}/files/{path}
# Description
TIP
There is also a legacy endpoint: POST storage/object/files/delete. The HTTP verb has changed from POST to DELETE, so a body is no longer needed for the new endpoint.
# Responses
| Code | Description | Schema |
|---|---|---|
| 204 | File was removed successfully | |
| 400 | Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc | ServiceErrors |
| 401 | Not Authorized. Either the Access token is missing or the access token validation failed | |
| 403 | Access Forbidden. Requesting entity does not have enough permissions to access the resource | |
| 404 | File not found | ServiceErrors |
| 429 | Too many requests - indicates the user has sent too many requests in a given amount of time | ServiceErrors |
| 500 | Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors | ServiceErrors |
# GET Search for Files in Global Storage
# /storage/global/files/search
# Description
Filterable properties:
- path: string
- timestamp: dateTime
# Parameters
| Name | Located in | Description | Required | Schema |
|---|---|---|---|---|
| filter | query | A boolean expression used to filter the results | Yes | WhereClause |
| limit | query | Limit the number of returned values. Defaults to 100 if not specified | No | LimitClause |
# Responses
| Code | Description | Schema |
|---|---|---|
| 200 | Success | GlobalFileServiceResponse |
| 400 | Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc | ServiceErrors |
| 401 | Not Authorized. Either the Access token is missing or the access token validation failed | |
| 403 | Access Forbidden. Requesting entity does not have enough permissions to access the resource | |
| 429 | Too many requests - indicates the user has sent too many requests in a given amount of time | ServiceErrors |
| 500 | Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors | ServiceErrors |
# POST Upload a File to Global Storage
Files from this storage can be used in methods that have file data type properties. The maximum file size is 250MB.
# /storage/global/files/upload
# Responses
| Code | Description | Schema |
|---|---|---|
| 201 | File was uploaded successfully | |
| 400 | Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc | ServiceErrors |
| 401 | Not Authorized. Either the Access token is missing or the access token validation failed | |
| 403 | Access Forbidden. Requesting entity does not have enough permissions to access the resource | |
| 429 | Too many requests - indicates the user has sent too many requests in a given amount of time | ServiceErrors |
| 500 | Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors | ServiceErrors |
# POST Download a File from Global Storage
# /storage/global/files/download
# Responses
| Code | Description | Schema |
|---|---|---|
| 200 | Success | |
| 400 | Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc | ServiceErrors |
| 401 | Not Authorized. Either the Access token is missing or the access token validation failed | |
| 403 | Access Forbidden. Requesting entity does not have enough permissions to access the resource | |
| 404 | File not found | ServiceErrors |
| 429 | Too many requests - indicates the user has sent too many requests in a given amount of time | ServiceErrors |
| 500 | Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors | ServiceErrors |
# POST Remove a file from Global Storage
# /storage/global/files/delete
# Responses
| Code | Description | Schema |
|---|---|---|
| 204 | File was removed successfully | |
| 400 | Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc | ServiceErrors |
| 401 | Not Authorized. Either the Access token is missing or the access token validation failed | |
| 403 | Access Forbidden. Requesting entity does not have enough permissions to access the resource | |
| 404 | File not found | ServiceErrors |
| 429 | Too many requests - indicates the user has sent too many requests in a given amount of time | ServiceErrors |
| 500 | Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors | ServiceErrors |