PhotoShelter API
back to all topics
Integration with the PhotoShelter API
Overview
The PhotoShelter API (Application Programming Interface) v1.1 allows programmers to integrate other applications with PhotoShelter through the use of remote calls. For example, it would be possible to develop a "plug-in" to an image editing program to export files to PhotoShelter directly. This would circumvent the use of the Uploader. The API uses open standards like XML to ensure the broadest possible application.
Who Should Use This API?
The API requires knowledge of programming and web communications. The API is not meant for a general audience, and support is very limited. Use of the API is governed by our licensing agreement.
Components
The API implements three main components:
- Authentication Request
- Data Request
- Functional Request
XML Response Format
The standard XML response format is as follows:<?xml version="1.1" encoding="ISO=8859-1"?> <BitShelterAPI version="1.1"> <identity> <company>BitShelter, LLC</company> <application>PhotoShelter</application> </identity> <response> ((<success>>[<class></class>][<message></message>]</success>)+)| (<error><class></class>[<var></var>]<message></message><error>)+)) </response> [<usage><desc></desc>[<input></input>][<output></output>]] [<session></session>] [<return></return>] </BitShelterAPI>
- BitShelterAPI
- root element
- identity
- site identity
- response
- response container element that will contain at least one success or error element
- success
- success element
- error
- error element
- class
- success or error class (can be used as a code)
- message
- human readable message
- usage
- usage element available on error
- desc
- description
- input
- input element that contains form variable names and description
- output
- output element that contains XML elements and descriptions for items contained in the return element (described below)
- session
- session element available with a valid session
- return
- return values from the module described by the output element
Authentication
Authentication allows the external application to sign in to a BitShelter application. The external application will send a login and password across HTTPS: https://www.photoshelter.com/bsapi/1.1/auth?U_EMAIL=&U_PASSWORD=Note: The application does not reject non-encrypted communications. It is YOUR responsibility to communicate via HTTPS.
On failure, the response will only be errors. On success, a session Cookie will be returned in both the XML and HTTP headers (Set-Cookie) that will be used for all subsequent requests to other modules. The HTTP cookie(s) must be resent as is and the format is subject to change. The XML session information can be used by the external application for display purposes.
When a valid session cookie is used with other modules, a new session cookie is returned in both the error and success response conditions. The new cookie has an updated expiration time used by the system to determine an idle session. By default, sessions time out after 2 hours of inactivity. The PhotoShelter system tracks concurrent sessions and has the ability to enforce a maximum per account. With this in mind, it is recommended that sessions be logged out when all requests are completed. This can be done by calling the authentication module with no parameters. For the same reason, the authentication module should not be called (with a valid email and password) if a handle to an active session is available since this creates a new session.Multi-User Authentication
Upon successful authentication using the auth module, all valid Multi-User accounts that the user has access to will be returned in the <org> tag. The org-auth module can then be called using the respective <O_ID> to authenticate the session for the specified Multi-User account. Calling the org-auth module without the O_ID parameter will revert the session back to single user mode.Data Request
A data request is one that an external application requests some information from a BitShelter application. Such requests include: all album names for logged in user, gallery names that are public for logged in user. Data requests may result in an XML response or a more specific Content-type (e.g. download full sized image). The format of which is determined by the type of request.<?xml version="1.1" encoding="ISO=8859-1"?> <BitShelterAPI version="1.1"> <response>(see above)</response> <return> return contents </return> </BitShelterAPI>Album Query and response contents: https://www.photoshelter.com/bsapi/1.1/alb-qry
(<alb><A_ID>id</A_ID><A_NAME>name</A_NAME>...</alb>)*
Functional Request
A functional request is one that an external application requests PhotoShelter to perform some action. Such requests include: upload image, toggle gallery public, etc. Image Upload (using enctype=multipart/form-data): https://www.photoshelter.com/bsapi/1.1/img-upl?I_FILE[]=&I_F_PUB= Album Insert: https://www.photoshelter.com/bsapi/1.1/alb-ins?A_NAME= In the above two examples, the response will be XML.Interfacing with Integration Layer
The integration layer uses common standards thus allowing a variety of choices (a lot of which are free). There should be library sets that can cross target multiple platforms (Win/Mac/Unix). Most of these are written in C, and some of the more popular ones have implementations or wrappers in Java or PHP.- curl
- DOM XML parser