API method documentation

Introduction

Put simply, an API is a formal line of communication between two programs. A REST API is one that utilizes inherent features of the Web to enable communication between a client and a server. It’s important to note that APIs aren’t designed to be exposed to you, the end user, except through intermediary programs. Remember this when you’re experimenting directly with the API; otherwise you may get frustrated.

Promoter Digital Gallery REST API provides an endpoint against which you can query, create, update, and delete resources:

http://digitalgallery.promoter.it/api

You can see which resources are available by appending /resources?pretty_print to your endpoint, like this:

http://digitalgallery.promoter.it/api/resources?pretty_print

Here you are getting the /resources resource as a JSON object containing all the available resources and other information about them. (?pretty_print is helpful to get back nicely formatted JSON, but is not necessary.)

In the above response you’ll notice that all resources have at least one action. These actions, while not important to a beginner, correspond to HTTP request methods. These methods are central to REST, and you should know what they do:

• GET gets one or more representations of a resource;
• POST creates a new resource and returns the representation of the newly created resource;
• PUT modifies an existing resource and returns the representation of the newly modified resource;
• DELETE deletes an existing resource.

Until you start building your own API client, you won’t need to make POST, PUT, or DELETE requests, but GET is well suited for beginners because you can run them directly from your Web browser, as you probably did above with /resources.

A representation, in this case, is a JSON object that represents a resource. In other words, you are not getting a resource itself, but rather a representation of it. This is very much like viewing an item on the website: the item show page is not the item itself, but a representation of the item.

Promoter Digital Gallery comes with the following resources:

• /collections
• /items
• /files
• /item_types
• /elements
• /element_sets
• /tags

Using the Promoter Digital Gallery API

Let’s take a look at the /items resource by making a GET request to the following URL using your Web browser:

http://digitalgallery.promoter.it/api/items

You’ll see a JSON array of item representations, each with an “id” (the item ID), a “url” (the direct URL to that item), and other metadata about the item. Copy that URL to your Web browser and make another GET request (you’ll first need to remove backslashes from the URL, which were a necessary part of JSON formatting):

http://digitalgallery.promoter.it/api/items/:id

Where :id is the item ID. You’ll see the same JSON representation of the item, but by itself. This URL is the item’s canonical URL, that is, it is an unambiguous and permanent link that represents the item itself.

So far you’ve only been using the GET method to get representations of resources. To experiment with POST, PUT, and DELETE you’ll need to use a program that is capable of sending those requests.