dlvr. - API Documentation

API Introduction

The dlvr. API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Authentication is made via the header with the keys dlvr-id and dlvr-token.

Authentication

We can check if the user has entered a valid Token by querying /validate/ passing dlvr-id and dlvr-token in as headers.

Endpoints

GET /validate

Query

curl --location --request GET 'https://api.dlvr.photos/validate/' \
--header 'dlvr-id: 12345' \
--header 'dlvr-token: 1111-2222-3333-4444-5'

Response

[
  {
      "message": "authenticated"
  }
]

Status Codes

200 Valid API token provided 400 Token or ID not specified 401 Invalid API token provided

Clients

A list of Clients a user can deliver photos to, in the Clients Area. Clients are usually named after the business or the people the photos are shot for. For example 'Joe's Windows LTD' or 'Kate + John'.

Endpoints

GET /clients/:id GET /clients POST /clients

List all Clients

Query

curl --location --request GET 'https://api.dlvr.photos/clients/' \
--header 'dlvr-id: 12345' \
--header 'dlvr-token: 1111-2222-3333-4444-5'

Response

[
    {
        "id": "1",
        "client": "Joe's Windows LTD"
    },
    {
        "id": "2",
        "client": "Kate + John"
    }
]

List single Client
Specify an id number in the request URL to get a single client's details.

Query

curl --location --request GET 'https://api.dlvr.photos/clients/1234/' \
--header 'dlvr-id: 12345' \
--header 'dlvr-token: 1111-2222-3333-4444-5'

Response

[
    {
        "id": "1234",
        "client": "Super Cool Hats"
    }
]

Create a new Client
Parameters required:

client string

The name of the new client in plain text.

Query

curl --location --request POST 'https://api.dlvr.photos/clients/' \
--header 'dlvr-id: 12345' \
--header 'dlvr-token: 1111-2222-3333-4444-5' \
--data-raw '{"client":"Oooober"}'

Response

[
    {
        "id": "1234",
        "client": "Oooober"
    }
]

Collections

A list of created Collections of photos. Collections can be either of type Portfolio which show on the user's website or type Client where the collection shows in the Clients Area for only the Client.

Endpoints

GET /collections/:id GET /collections POST /collections

List all Collections

Query

curl --location --request GET 'https://api.dlvr.photos/collections/' \
--header 'dlvr-id: 12345' \
--header 'dlvr-token: 1111-2222-3333-4444-5'

Response

[
    {
        "id": "1",
        "name": "Portraits",
        "url": "portraits",
        "type": "portfolio",
        "client": "0"
    },
    {
        "id": "2",
        "name": "Landscapes",
        "url": "landscapes",
        "type": "portfolio",
        "client": "0"
    },
    {
        "id": "3",
        "name": "Kate + John",
        "url": "kate-and-john",
        "type": "client",
        "client": "2"
    }
]

List single Collection
Specify an id number in the request URL to get a single collection's details.

Query

curl --location --request GET 'https://api.dlvr.photos/collections/3/' \
--header 'dlvr-id: 12345' \
--header 'dlvr-token: 1111-2222-3333-4444-5'

Response

[
    {
        "id": "3",
        "name": "Kate + John",
        "url": "kate-and-john",
        "type": "client",
        "client": "2"
    }
]

Create a new Collection
Parameters required:

name string

The name of the new collection in plain text.

client integer

For collection type of Portfolio set client to 0, for collection type of Client set the client to the relevant client ID.

Query

curl --location --request POST 'https://api.dlvr.photos/collections/' \
--header 'dlvr-id: 12345' \
--header 'dlvr-token: 1111-2222-3333-4444-5' \
--data-raw '{"name":"Oooober Head Shots", "client":"1234"}'

Response

[
    {
        "id": "1234",
        "name": "Oooober Head Shots",
        "url": "oooober-head-shots",
        "type": "client",
        "client": "1234"
    }
]

Images

A list of Images organised into Collections.

Endpoints

GET /collections/:id/images GET /collections/:id/images/:id POST /collections/:id/images

List all Images in a Collection
Specify an id number in the request URL to get a collection's images.

Query

curl --location --request GET 'https://api.dlvr.photos/collections/4/images/' \
--header 'dlvr-id: 12345' \
--header 'dlvr-token: 1111-2222-3333-4444-5'

Response

[
    {
        "id": "428",
        "filename": "Oooober Head Shots - IMG_0480.jpg"
    },
    {
        "id": "429",
        "filename": "Oooober Head Shots - IMG_0481.jpg"
    },
    {
        "id": "430",
        "filename": "Oooober Head Shots - IMG_0482.jpg"
    }
]

List single Image in a Collection
Specify an id number for both the collection and image in the request URL to get a specific image's data.

Query

curl --location --request GET 'https://api.dlvr.photos/collections/4/images/430/' \
--header 'dlvr-id: 12345' \
--header 'dlvr-token: 1111-2222-3333-4444-5'

Response

[
    {
        "id": "430",
        "filename": "Oooober Head Shots - IMG_0482.jpg"
    }
]

Upload a new Image to a Collection
Specify an id number in the request URL to set the destination collection.

Parameters required:

upload file

The image to be uploaded should be sent as form-data with the key name upload.

Images can be in the following formats:

.jpg .jpeg .png .gif

Maximum file size allowed is 100MB.

Query

curl --location --request POST 'https://api.dlvr.photos/collections/4/images/' \
--header 'dlvr-id: 12345' \
--header 'dlvr-token: 1111-2222-3333-4444-5' \
--form 'upload=@"path/filename.jpg"'

Response

[
    {
        "collection": "1",
        "filename": "filename.jpg"
    }
]

Settings

A list of settings and account details related to the dlvr. account.

Endpoints

GET /settings

List all Settings

Query

curl --location --request GET 'https://api.dlvr.photos/settings/' \
--header 'dlvr-id: 12345' \
--header 'dlvr-token: 1111-2222-3333-4444-5'

Response

[
    {
        "id": "12345",
        "domain": "johnsmithphotography.com",
        "title": "John Smith Photography",
        "package": "Pro Unlimited",
        "usage": "220 GB / 1 TB"
}
  ]

Errors / HTTP Status Codes

We use standard HTTP response codes, across all Resources.

Status Codes

200 Successfully executed query 204 Successfully created item 204 Success but empty result 400 Incomplete parameters received 401 Invalid token provided 404 API resource doesn't exist 405 Method not supported, only GET & POST are supported 409 Conflict, item already exists 503 API unavailable