Requests
All endpoints on the PhotoShelter API are located at /psapi/v3 and can be accessed at www.photoshelter.com as well as at a user subdomain and CNAME. (We encourage you to default to using only the major version number - e.g. v3 - since it is backward compatible and will always be at the latest point release.) To grab the image_id of all images in a particular gallery, for example, simply make the following request with your API key:
/psapi/v3/gallery/MY_GALLERY_ID/images?api_key=MY_API_KEY&fields=image_id
Public v. Member
There are two types of endpoints on the PhotoShelter API: public endpoints and member endpoints. The difference is that member endpoints require user authentication while public endpoints do not, since public endpoints are read-only and are subject to the permissions enforced by content owners.
Extensions
On the PhotoShelter API, an endpoint can be "extended" by one or more other related endpoints. Extensions allow one call to the API to hit two or more endpoints, enabling multiple actions to be performed with just one request. Neat, right?
To extend an endpoint, you must pass the extend
parameter to the initial endpoint. The value to the extend
parameter is a JSON object containing one or more key-value pairs, each of which represents an endpoint by which the initial endpoint is to be extended. The syntax of the key-value pairs is as follows:
Key | Value |
---|---|
Name of the record type that is returned by the extending endpoint, written in camelcase as a singular noun | An object with two property names:
|
For example, to extend Gallery (/psapi/v3/gallery/{gallery_id}) by GalleryImage (via /psapi/v3/gallery/{gallery_id}/images) and ImageLink (via /psapi/v3/image/{image_id}/link), set the extend
parameter to:
var extendGal = {
"GalleryImage": {
"fields": "image_id",
"params": {}
},
"ImageLink": {
"fields": "link,base",
"params": {
"image_mode": "fit",
"image_size": "300x300"
}
}
};
If an extension results in an error due to invalid or incomplete parameter inputs, the error will generally be ignored. The API will return the data that is possible to extract.
Check the reference to see what endpoints, if any, by which an endpoint can be extended.
JSONP
JSONP is supported by setting the callback
parameter to the name of the callback function. For example:
/psapi/v3/image/MY_IMAGE_ID?api_key=MY_API_KEY&fields=image_id&callback=mycallback
Would respond with:
mycallback({...});
Request parameters
fields |
When requesting data, you need to specify the fields to be returned by providing a fields parameter. The value is a comma separated list of the requested fields. Note that if the object id is an available output field (e.g. image_id or gallery_id), it must be included. * is supported to retrieve all fields, but its usage is discouraged. |
callback |
If you would like to wrap the response in a callback function (as in a JSONP request), specify the callback parameter in your API call. |
format (default is “JSON”) |
To receive the response in XML, instead of the default JSON, set format=xml . Note that the format parameter takes precedence over the callback parameter, which means that any callback function that is set will not be executed if the response format is set to XML. |
extend |
You can choose to extend an endpoint by one or more of its available extension endpoints by passing the extend parameter |
api_key |
You may pass your API key in the request URL using the api_key parameter. Alternatively, consider sending this in an HTTP header. |
auth_token |
If you request an access token (rather than HTTP cookies) to be returned upon user authentication, you need to set the auth_token parameter to this token in order to access member endpoints. Alternatively, consider sending this in an HTTP header. |