/cloud-api-doc

Eyefi Cloud API documentation

Overview

The Eyefi Cloud API is a RESTful API that uses OAuth 2.0 for authentication.

APIs are provided that allow for photo upload and download, album creation and curation, tag creation and curation, and photo searching. Eyefi will continue to maintain the publicly available API set through regular updates to the cloud-api-doc GitHub project.

Each API endpoint is described in a separate file in the endpoints folder. Parameter descriptions are provided for each API. SDKs are availabe in several languages.

Support for the API is provided on a best-effort basis through Github Issues.

Swagger

Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services. It comes with dozens of resources from SDK generators to API consoles.

The Eyefi Cloud API is Swagger 1.2 compliant. The Swagger UI API console and API documentation can be found at http://swagger.eyefi.com, which is the most up-to-date information available.

Authentication

Eyefi's Cloud API uses the OAuth 2.0 authorization framework for simple-but-effective authentication and authorization.

All requests must happen over https.

Obtaining an Access Token

An end user will obtain an access token from the Eyefi Web App. Under the account menu tree there is an option named "Developer," which controls the current list of access tokens. Select the + icon to generate a new access token to use to contact the API. Use this screen to remove or regenerate access tokens as well.

Using the Access Token

Once the token has been obtained, it should be passed with every API call in an authorization header:

Authorization: Bearer ACCESS_TOKEN

For example, if you were using curl to get the list of albums in a user's account, it would look like this:

curl https://api.eyefi.com/3/albums
    -H 'Authorization: Bearer ACCESS_TOKEN'
    -X 'GET'

API General Use

Requests

Each of the API endpoints has a series of operations with a mixture of POST, GET, PUT, and DELETE.

For POST and PUT requests, the data can be passed in the body using content type application/x-www-form-urlencoded:

curl https://api.eyefi.com/3/albums
    -H 'Authorization: Bearer ACCESS_TOKEN' 
    -X 'POST' 
    -d 'name=NAME'

or content type application/json:

curl https://api.eyefi.com/3/albums
    -H 'Authorization: Bearer ACCESS_TOKEN' 
    -X 'POST'
    -H 'Content-Type: application/json' 
    -d '{"name":"NAME"}'

Notes on Documentation

Each API call has a list of required parameters. The first parameters in the list may be required in the URL, especially those that refer to the object ID or the referenced object ID, and additional parameters are in the body.

An example is updating an album (rename album 12345678 to be "NEWNAME"). The documentation for updating an album will refer to the API call as:

PUT /albums/{albumId}

Which indicates that the {albumId} needs to be in the URL. The parameters table looks like this:


Name Type Description
albumId integer The ID of the album to update.
name string The new album name.
privacy integer Privacy setting for the album. Use 0 for private and 1 for public. Setting privacy to 1 also returns a share URL.

This table explains the meaning of all parameters, some of which are in the URL and some of which should be form or JSON encoded in the body.

A curl example then looks like this, with the object ID in the URL as {albumId} and the name parameter in the body:

curl https://api.eyefi.com/3/albums/12345678
    -H 'Authorization: Bearer ACCESS_TOKEN' 
    -X 'PUT'
    -H 'Content-Type: application/json' 
    -d '{"name":"NEWNAME"}'

Responses

All responses come in JSON format in either a simple envelope around a dictionary:

{
    "id": 100000000,
    "name": "NAME",
    "file_count": FILE_COUNT    
}

or a list:

[
    {
        "id": 100000001,
        "name": "NAME",
        "file_count": FILE_COUNT
    },
    {
        "id": 100000002,
        "name": "NAME",
        "file_count": FILE_COUNT
    }
]

Status Codes

Code Description
200 OK.
201 Resource created. Common for successful POSTs.
204 No content. Common for successful DELETEs when no data is returned.
400 Bad request. Common with malformed input such as an invalid email address, bad JSON, etc.
401 Unauthorized. Invalid or expired access token.
403 Forbidden. Happens when trying to access a resource for which a user does not have permission.
404 Not found.
409 Conflict. Resource already exists, such as an email address already in use.
500 Internal server error.

Errors

When an error occurs the server returns a 4xx or 5xx HTTP status code and an error object with more information:

{
    "message": "Invalid name",
    "status": 400,
    "code": 2060
}

Miscellaneous Items

Dates

All date fields are returned as ISO 8601-formatted strings and are normalized to UTC.

2014-02-03T12:37:08+00:00

Endpoint Listing

SDKs