REST API Reference

Initial API specification (v0.1).

API Endpoint: https://api.abraia.me

Introduction

Abraia API REST uses resource-oriented URLs and HTTP codes to indicate API errors. It is built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned by most of API responses, including errors, although our API libraries convert responses to appropriate language-specific objects.

Authentication

Authentication to the API is performed via HTTP Basic Auth. Provide your API Key as the basic auth username value and the API Secret as the password value. You can manage your API keys in the console.

Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Example request:

curl -u apiKey:apiSecret https://api.abraia.me/files/

curl uses the -u flag to pass basic auth credentials (user:password).

To test request you must use your account API keys, replacing apiKey and apiSecret with your actual API keys. Curl uses the -u flag to pass basic auth credentials (apiKey:apiSecret).

Files storage

Upload a file

Upload a local or a remote file using the following URL:

POST /files/{userid}/{path}

This URL creates the resource on the cloud and returns the signed URL to upload the file.

A JSON object specifies the name and type of the file or the remote url.

Example

curl -u apiKey:apiSecret -X POST -d '{"name": "tiger.jpg", "type": "image/jpeg"}' https://api.abraia.me/files/userid/

The above command returns JSON structured with the upload URL like this:

{
   "uploadURL": "https://s3.eu-west-1.amazonaws.com/store.abraia.me/demo/tiger.jpg?AWSAccessKeyId=ASIAWYD4NR3V2Q3QGRHM&Content-Type=image%2Fjpeg&Expires=1539444387&Signature=PtC917pbwI33Yy%2BHLvCRUquW3Z4%3D&x-amz-security-token=FQoGZXIvYXdzEPn%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDAydZFATwU34O1CCNCLvAaQESCzuGMJjBdvp6A5rLvlfGN%2BlvdqUoTm52fwBH0Pjaf3Pq7bD2gNXk34RvbRCrG1GKMyq6nEDiMuzReJdl%2F4R7uMLhr2es%2FcvvHqYqopgsYpIwQRqVfEOCi9uxuLwOmbiuDl137QkTG9LcxnI4qc%2BswakShQZkdZ1RtkJrWluWfl0qN6LVMvDVIhFb74%2BWojy8asgw%2BvtNRV%2FAv9aaCPUjzNGmsmd%2FuLU9Vc%2Fsj0CSOns%2BD3%2BQmFKPGz5D6P4ihWqxfqhzm4i23Oq93XfiGqgrA%2FKMPNP06zfL%2F3qVpJLHZRhnkJRv27jObGVa0GoKJ2WiN4F"
}

This uploadURL needs to be used to upload the file data.

curl -H 'Content-Type: image/jpeg' -T tiger.jpg 'ttps://s3.eu-west-1.amazonaws.com/store.abraia.me/demo/tiger.jpg?AWSAccessKeyId=ASIAWYD4NR3V2Q3QGRHM&Content-Type=image%2Fjpeg&Expires=1539444387&Signature=PtC917pbwI33Yy%2BHLvCRUquW3Z4%3D&x-amz-security-token=FQoGZXIvYXdzEPn%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDAydZFATwU34O1CCNCLvAaQESCzuGMJjBdvp6A5rLvlfGN%2BlvdqUoTm52fwBH0Pjaf3Pq7bD2gNXk34RvbRCrG1GKMyq6nEDiMuzReJdl%2F4R7uMLhr2es%2FcvvHqYqopgsYpIwQRqVfEOCi9uxuLwOmbiuDl137QkTG9LcxnI4qc%2BswakShQZkdZ1RtkJrWluWfl0qN6LVMvDVIhFb74%2BWojy8asgw%2BvtNRV%2FAv9aaCPUjzNGmsmd%2FuLU9Vc%2Fsj0CSOns%2BD3%2BQmFKPGz5D6P4ihWqxfqhzm4i23Oq93XfiGqgrA%2FKMPNP06zfL%2F3qVpJLHZRhnkJRv27jObGVa0GoKJ2WiN4F'

Download a file

Retrieve an stored file using the following URL:

GET /files/{userid}/{path}

Replace {userid} and {path} with your user id and file path. The API call will return an 307 status code with the signed URL redirection to download the file data.

Example

curl -u apiKey:apiSecret -L https://api.abraia.me/files/demo/bird.jpg -o bird.jpg

Move a file

Move a stored file from an oldPath to a newPath using the following URL:

POST /files/{newPath}

This URL creates the new resource from the one specified in the JSON object with the store parameter.

Example

curl -u apiKey:apiSecret -X POST -d '{"store": "demo/bird.jpg"}' https://api.abraia.me/files/demo/test/bird.jpg

The above command returns a response as bellow:

{
  "file": {
    "name": "bird.jpg",
    "source": "demo/test/bird.jpg"
  }
}

List files

Retrieve information about all the files stored in a cloud folder using the following URL:

GET /files/{userid}/

This endpoint retrieves all the file data as a JSON structure with a list of files and folders.

Example

curl -u apiKey:apiSecret https://api.abraia.me/files/demo/

The above command returns JSON structured like this:

{
   "files": [
      {
         "date": 1513537440.0,
         "md5": "9f1f07e9884c4b11b048614561eebd89",
         "name": "random_97.jpg",
         "size": 112594,
         "source": "demo/random_97.jpg",
         "thumbnail": "demo/tb_random_97.jpg"
      },
      {
         "date": 1513533727.0,
         "md5": "7ac57ee27b4474c7109e3c643948a9de",
         "name": "random_96.jpg",
         "size": 70232,
         "source": "demo/random_96.jpg",
         "thumbnail": "demo/tb_random_96.jpg"
      }
   ],
   "folders": [
      {
         "name": "videos",
         "source":"demo/videos/"
      }
   ]
}

Delete a file

Delete a stored resource specified by its path.

DELETE /files/{userid}/{path}

Image transformation

Retrieve an optimized image using the following URL:

GET /images/{userid}/{path}?q=auto

Replace {userid} and {path} with the image path and filename. The API call transform the image on-the-fly a returns the optimized result.

Query parameters

Parameter Description
w (optional) Image width
h (optional) Image height
q (optional) Image quality
fmt (optional) Image format

Examples

Optimize and resize and image:

curl -u apiKey:apiSecret https://api.abraia.me/images/demo/bird.jpg?q=auto&w=600 -o bird.jpg

Video transcoding

Run a video transcoding task using the following URL:

GET /videos/{userid}/{path}?fmt=mp4

Replace {userid} and {path} with the video path. The API call returns the new video path.

Query parameters

Parameter Description
fmt (required) Video format
w (optional) Video width
h (optional) Video height

Example

curl -u apiKey:apiSecret https://api.abraia.me/videos/demo/videos/zara.mp4?fmt=mp4&w=600

The above command returns JSON structured like this:

{
   "path": "demo/videos/zara/zara_600.mp4"
}

Errors

Abraia uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a not found resource, etc.), and codes in the 5xx range indicate an error with Abraia's servers (these are rare).

HTTP status code summary

Code Status Description
200 OK. Successful Everything worked as expected.
201 Created A new resource was successfully created.
307 Temporal Redirect The resource requested has been temporarily moved to the URL given by the Location headers.
400 Bad Request The request was unacceptable, often due to missing a required parameter.
401 Unauthorized No valid API key provided.
403 Not allowed No credits available.
404 Not Found The resource requested does not exist.
500 Server Error Something went wrong on the service.