Extend an Endpoint

Sometimes, you need data from several related endpoints. You can chain a few API requests together, but that quickly increases your application's overhead. This is where endpoint extensions come in. The PhotoShelter API allows you to extend an endpoint by other related endpoints, when available, returning the combined data with just one HTTP request. Let's see how this works.

The example code in this guide is written in JavaScript, using the JavaScript library jQuery, but you can use your programming language of choice.

Overview

In the previous guide, we got image data like file size and file name from the API via the /psapi/v3/image/{image_id} endpoint. This endpoint doesn't return a link to the image, though, since that's controlled by a different endpoint /psapi/v3/image/{image_id}/link. To get data from both endpoints in one call, we extend the first endpoint by the second.

What you need

• An API key with PhotoShelter, which is required to access the API. To run the example code in this guide, replace "MY_API_KEY" with your own key. Register for an API key, or learn more about Connecting to the PhotoShelter API.
• Access to a PhotoShelter account. If you don't have one, you can sign up for a free Trial Account. Trial Accounts have limited storage and theme options, but it will allow you to test the PhotoShelter API for up to 14 days. If you need an extension on the trial, reach out to our Technical Support team.

What to do

Initial endpoint

We can get image data image_id, file_name, and file_size from the PhotoShelter API by making a request like this:

var initEp = "/psapi/v3/image/MY_IMAGE_ID?api_key=MY_API_KEY&fields=image_id,file_name,file_size";

Set extend parameter

To extend this endpoint, we pass the parameter extend to the initial endpoint and set it to a JSON object that has the record type of the extending endpoint as the key. (In this case, the record type returned by the endpoint /psapi/v3/image/{image_id}/link is ImageLink.) The value is another object with properties fields and params. This is what the object looks like:

var extend = {
	"ImageLink": {
		"fields": "link,base",
		"params": {
			"image_mode": "fill",
			"image_size": "300x300"
		}
	}
};

We can use the JSON.stringify function to convert the JSON object into a string, so as to attach it to the request query string.

var extendStr = "extend=" + JSON.stringify(extend);
var request = initEp + "&" + extendStr;

Make the call

We make an Ajax call with the request URL and log the response in order to inspect it.

$.get(request, function(data){
	console.log(data);
});

The response

The response contains data from the initial endpoint, as well as data from the extending endpoints:

{
	"status": "ok",
	"data": {
		"Image": {
			"ImageLink": {
				"base": ...,
				"link": ...
			},
			"file_name": "my_image.JPG",
			"image_id": "MY_IMAGE_ID"
		}
	}
}

Viola! What would normally take two calls to the API has been accomplished by one.

Extend by multiple endpoints

Say that you want to get links to all the images in a gallery. How do we do this?

Notice that Gallery (/psapi/v3/gallery/{gallery_id}) can be extended by GalleryImage, which can be extended by ImageLink. As a result, we simply build up the extend JSON object like so:

var extendGal = {
	"GalleryImage": {
			"fields": "image_id",
			"params": {}
		},
	"ImageLink": {
		"fields": "link,base",
		"params": {
			"image_mode": "fit",
			"image_size": "300x300"
		}
	}
};

What you should know

An endpoint can only be extended by endpoints that are logically related. This means that not all endpoints are extendable, and those that can be extended are not extendable by all endpoints. To find out if whether, and by what, an endpoint is extendable, read the reference documentation for that endpoint.

Further Reading

• /psapi/v3/image/{image_id} reference documentation
• /psapi/v3/image/{image_id}/link reference documentation
• /psapi/v3/gallery/{gallery_id} reference documentation
• PhotoShelter API user guide