# 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"
# File API V2
# POST Session in an Object Storage
# objects/{objectId}/models/{modelId}/session/
Example url: https://domain/filemanager-api/v2/objects/123-abcd-123/models/abb.model/session/
TIP
objectId and modelId is a mandatory route parameter.
# 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 Session in a Global Storage
# session/
Example url: https://domain/filemanager-api/v2/session/
TIP
objectId and modelId is a mandatory route parameter.
# 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 |
# PUT Upload a File into an Object Storage
# objects/{objectId}/models/{modelId}/files/
Example url: https://domain/filemanager-api/v2/objects/123-abcd-123/models/abb.model/files/
TIP
objectId and modelId is a mandatory route parameter.
# 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 |
# PUT Upload a File to Global Storage
# files/
Example url: https://domain/filemanager-api/v2/files/
# 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}
Example url: https://domain/filemanager-api/v2/objects/123-abcd-123/models/abb.model/files/
# 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 |
# GET Download a File from Global Storage
# files/
Example url: https://domain/filemanager-api/v2/files/
# 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/
Example url: https://domain/filemanager-api/v2/objects/123-abcd-123/models/abb.model/files/
TIP
objectId and modelId is a mandatory route parameter.
# 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 |
# DELETE Remove a file from Global Storage
# files/
Example url: https://domain/filemanager-api/v2/files/
TIP
objectId and modelId is a mandatory route parameter.
# 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 and Object Storage
# search/files/
Example url: https://domain/filemanager-api/v2/search/files/
TIP
Global or Object Is determined based on Storage-Type.
# 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 |