Atlas Core API 2.7
Your OpenDrives system is powered by a RESTful API, which is available for you to utilize in non-interactive programming environments as well. If you know your way around a command line, Postman, or any programming language that can create HTTP requests, then you’ll hopefully be delighted with this documentation that will walk you through how and why to use your Atlas Core API to extend the functionality of your Network Attached Storage beyond its normal limits.
For the best API experience, please be sure to read this entire introduction before proceeding. We also recommend the 'Getting Started' Section before digging too deeply into the documentation
About this Documentation
The API documentation is written in standard AsciiDoc format and translated here via a documentation creator called Antora. We offer our sincere gratitude to the open source contributions that we have benefitted from.
Document Organization
In each section noted, we have organized the items as logically as possible, grouping Storage, Network, Administration, and Containerization functionalities with like functionalities. In each grouping, we have individual documents for each API subsection, which should all have individual endpoints listed with:
-
A schema which describes the data format
-
An example of the request and response
This should be sufficient to see what can be passed vs what would be normally passed into each call.
|
Using the API
Here are some small notes that you should know before you start to use the API
-
All request to the API can be made through
https://localhost/api/v2 -
All data should be sent in JSON
-
All data returned will be in JSON Object or JSON Object Array
Authorization
The overwhelming majority of API calls require proper authorization with your OpenDrives system. The exceptions being calls to login, logout, and view basic system information
We are using an authorization bearer token in HTTP Headers to authorize incoming API requests, so please pass token:BLAHBLAHYOURTOKENHERE in the header of your calls.
Please view the Authorizations portion of your system’s user interface to create a token for yourself. A tutorial for this is available in the Getting Started section.
|
A bit about tokens:
|
Query Parameters vs Body Data
For most requests, we follow the sensible pattern of
-
POST calls use body parameters
-
GET calls use query strings
Body parameters (not included in the URL as query parameters) should be
encoded as JSON with a Content-Type of 'application/json':
Sometimes we deviate from this pattern, and we’re working on aligning our API calls to this pattern moving forward.
Errors
Valid requests will return an http status code of 200 or something in
the 2XX or 3XX range.
Bad requests will return the status code 400 or something in the 4XX
range.
If for some reason the API server errors, we will send a status code of
500 or something in the 5XX range.
All error objects should have the following structure
{
"name":error_name,
"code":error_code,
"message":error_message,
"i18n": error_i18n_code
}
Timestamps and Time Zones
Almost all timestamps are in the format YYYY-MM-DDTHH:MM:SSZ, or a Unix Timestamp in places that we needed to do simple math on how much time has passed.
For users in the year 2038 still reading this documentation, I apologize.
HTTPS and Certificates
The API is currently offered only over HTTPS, to provide a safe encryption of traffic to and from the server. To utilize this API you must either apply the root certificate of the OpenDrives system to your computer’s local keychain’s trusted certificates (if you have a 'vanilla' OD machine, which only ships with self-signed certs, you’ll need to trust that self-signed cert)
This process can be somewhat confusing for first time API programmers, so consult a search engine on how to accept a certificate into the trusted list for your computer’s OS.