OpenDrives API 2.5

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 OD 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:
  • The token you generate will have the same permissions as the username you create the token for. For example, let’s say you generate a token associated with a user that has only the zfs view permission. That user will be able to send API requests to list all of the zfs filesystems but will not be able to create, edit, or destroy them.

  • We also give you the ability to designate exactly how long you would like your tokens to be valid. Our recommended lifespan for a token is around 30 days. They should rotate regularly for security purposes.

  • Lastly, we never delete tokens. When a token has expired it is simply invalid. Similarly, you have the option to enable or disable a token whenever you please. However, a token has to be both not expired and enabled in order for it to be valid for API use.

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.

Benediction

As you begin your journey into these pages, I leave you with this:

  • May your code be functional, documented, and bug-free.

  • May your users be kind, cautious, and of strong intuition.

  • May your coffee mug always be full and your inbox empty.

So say we all.