Skip to main content

API guide

Introduction

Shadline provides its customers with an Application Programming Interface (API) that enables automated file management of its dedicated Storage instance.

Shadline’s technology ensures data protection and notably reinforces compliance with the RGPD (General Data Protection Regulation) which came into force in May 2018.

Our solution is distinguished from other storage services by multiple data encryption mechanisms (« in motion » and « at rest »), coupled with file fragmentation.

Thanks to this API, Shadline allows you to quickly deploy containers, i.e. secure and watertight storage areas to guarantee the confidentiality, integrity, availability and isolation of your company’s critical data.

Technical preamble

A RESTful API

The API proposed by Shadline complies with the RESTful standard (REpresentative State Transfer).

All flows exchanged with the API are encrypted in HTTPS using the TLS protocol. Only TLS secured connections are accepted by the Shadline infrastructure.

The two formats returned by the API are binary (return when requesting a file) and JSON (JavaScript Object Notation).

Functions exposed by the API

The web services exposed by Shadline allow API users to benefit from secure file storage. The major functionalities available to manage documents are:

  • Storing files in Shadline (upload)
  • Retrieving files stored on Shadline (download)
  • Deleting files stored on Shadline (erasure)

The storage operation must be performed on a file-by-file basis. The API does not currently support batch file storage.

Functions allowing to list documents, to organise them in a tree structure (visible from the Shadline web and mobile application), to obtain metadata and statistics related to the use of the service are available. It is also possible to assign an expiry date to each file after which it will be automatically deleted.

These functionalities are detailed in the rest of this document by describing the associated requests, the necessary parameters and the possible return codes.

API_Description_EN
Limits of use

Each customer can use his company storage to upload the files of his choice. The Shadline API is compatible with all file formats: Word / Excel / PowerPoint, PDF, TXT, CSV, images, videos, archives, binary, etc.

The maximum size allowed per file is defined according to your contract.

Authentication

Authentication mechanisms to access the API

The Shadline API implements various additional authentication and authorization mechanisms.

1. Certificate-based authentication of the product’s client (company)

    • The user must have the certificate issued by Shadline in order to exchange with the solution. The API server checks the validity of the certificate fingerprint presented by the user for each request made.
    • This client certificate must be used for all requests to the API.

2. A global identification to the API

    • The user must have an API identifier (called x-api-key) provided by Shadline in order to be able to exchange with the solution. The API server checks the validity of this identifier presented by the user at each request made. The identifier is the same for all the users of the same company, it is common to all the containers used.
    • This key must be used for all requests to the API.

3. An identification by container

    • The user must have a « container » ID (called x-user-key because a container is equivalent to an API account) in order to interact with the content of the desired container. The API server checks the validity of this identifier presented by the user at each request made.
    • This identifier is generated during the creation of the container by the company. It can be obtained from the Shadline web administration interface. It is different for each container. It is a secret element that protects access to the container data.
    • This key must be used for all requests to the API.

4. Container password authentication

    • The user must have an identifier called hPassword corresponding to the derivative of the password chosen during the container’s initialisation. The API server returns a localPassword during this initialization in order to be able to interact with the content of the desired container. The API server checks the validity of this string presented by the user for each request made.
    • This value must be used for all requests to the API involving access to documents (upload, download or delete).

In addition, a single-use token (JWT token) is inserted in each application request in order to reinforce the control of authorisations. Any request is thus carried out in 2 stages:

  • A token request
  • Then the call to the desired function with the obtained token

The token has a duration of validity of 5 minutes.

Note: At the time of the first connection with an API container, you will be asked to provide the derivative of your password in SHA512 (hpassword) in order to obtain the associated localPassword.

The following diagram shows the main authentication elements used:

API_Authentication_EN
Sequencing of authentication and authorization actions

The sequence of steps is done according to the diagram below:

API_Sequencing_EN

The first exchanges are used to initialize the environment. They are only performed once.

1. The Shadline server verifies the identity of the client (using the upstream client certificate and API key). The customer receives a token in return.

2. The customer defines his password. It receives in return the localPassword value.

The customer can then use one of the API services to execute the desired functionality.

3. The customer requests a token again before each application call.

4. The customer can call up the function of his choice using the authentication elements in his possession.

Format of requests and associated returns

All actions are performed using HTTP request types (such as GET, POST, PUT, DELETE, HEAD, etc.) followed by the entry point, or URL, that will impact the requested resource.

Overall, the requests are formulated as follows:

ACTION /api/[impacted_resource]/{resource_credential}

The HTTP response includes a code representing the status of the operation (e.g. 200 for a successful operation) as well as a data part in JSON or binary for file return. The returned JSON always follows the following format:

"data": {}, // Requested data: object or table according to the resource

The « data » field is present even without specific data, it will then be empty.

In the event of an error, a return of the following form is obtained:

{

"type": "TYPE_ERROR",
"message": "description Human-readable",
"data": [],
"uri": "URI link to error description in API documentation if available."

}

« data » may for instance be present in the case of an error in the validation of input parameters. It specifies the parameters involved and the reasons.

All possible return codes (and any associated error types) are described in section Return codes and error types of this page.

Versioning

Several versions of APIs may be available in a client instance.

The version used must be specified in each URI, after the « /api » term:

/api/vx/[...]

vx represents the version of the API used (« x » is the version number) and […] the call to the resource. For instance:

/api/v2/storage

If this value is not specified, the latest version of the API will be used automatically. We therefore recommend that you indicate the version number in all URIs to ensure the operation of your applications in the event of an API update.

The version of API that can be used will be specified by the Shadline technical team.

Note: The version life cycle is maintained by the Shadline technical team. When an « n » version is deployed in Production, the « n-1 » version remains active and maintained for several months to allow the transition of our customers’ applications to this last release. In addition to adding new routes, technical changes to the input and output parameters can be made to existing routes during these changes. The date of transition of a version of the API to « unsupported » status (unsupported, ie « end-of-life ») will be communicated upstream by Shadline.

Technical description of the requests (list of endpoints)

The list of endpoints is accessible from the following URL:

https://documenter.getpostman.com/view/14673366/TzsWuqXw

Postman collection

A Postman collection gathering all the endpoints can be downloaded via the following link to facilitate development work in order to connect to our API :

https://doc.shadline.com/wp-content/uploads/2022/04/Shadline-API-Public-Edition.postman_collection.json_.zip

The configuration of the Postman tool is detailed in the following document:

https://doc.shadline.com/wp-content/uploads/2022/04/SHADLINE_Postman_Configuration.pdf

Return codes and error types

Code Type Meaning
200 OK Request successfully executed
201 CREATED Successfully stored file
400 BAD_PARAMETER
BAD REQUEST
Provided parameters doesn’t respect the expected types
400 ERR_INVALID_TOKEN Token not properly formatted
400 ERR_NO_APIKEY No “x-api-key” header identified
400 ERR_NO_TOKEN No « Authorization: Bearer » field identified
400 ERR_UNABLE_DECODE_PARAM The payload of the token is corrupted/td>
401 UNAUTHORIZED Token expired or invalid

or x-api-key not present or invalid
or x-user-key not present or invalid

403 ERR_ORIGIN_NOT_ALLOWED Wrong authentication server
403 FORBIDDEN Access prohibited because the account has already been initialized
404 ERR_ORIGIN_NOT_FOUND The authentication server is unknown
404 FOLDER_NOT_FOUND No folder found
404 ITEM_NOT_FOUND No document found
404 FILE_NOT_FOUND No file found
404 NOT FOUND Requested document not found
404 USER_NOT_FOUND No container found
413 PAYLOAD TOO LARGE The file is too large
422 UNPROCESSABLE ENTITY File format problem or invalid expected settings
500 ERROR Generic error (internal to services)
509 LIMITATION_REACHED API limitations reached
524 REQUEST_TIMEOUT The request lasted too long