Catalog JSON API Documentation

So, you want to develop some tooling around the Catalog API - perhaps some custom reports? Great! This API gives you everything that Catalog has to offer.

Authentication

Visit this page to create an API key. Once you’ve received your key, treat it like a password.

Use SSL for all requests to the API. Non-SSL requests will result in redirects, and your API key will be sent in the clear.

To authenticate, send the API key as a request header. Here’s an example using cURL:

curl https://www.my-catalog.edu/api/v1/products -H 'Authorization: Token token="my-api-key"'

Pagination

All index endpoints support pagination. Specifically, we implement RFC5988.

Pagination Options

You can use ?page= to set the page of data you want to retrieve. If no items exist for that page, the response will be a root key with an empty array.

curl https://www.my-catalog.edu/api/v1/courses?page=2

{
  "courses": []
}

To change the number of items returned for each page, you can use ?per_page=. This defaults to 20 and has a max of 100.

curl https://www.my-catalog.edu/api/v1/courses?per_page=40&page=2

Link Headers

Information about pagination is provided in the Link header. Here is an example of what the header could look like

curl -I https://www.my-catalog.edu/api/v1/courses?page=3

Link: <https://www.my-catalog.edu/api/v1/courses?page=4>; rel="next",  
      <https://www.my-catalog.edu/api/v1/courses?page=15>; rel="last",
      <https://www.my-catalog.edu/api/v1/courses?page=1>; rel="first",
      <https://www.my-catalog.edu/api/v1/courses?page=2>; rel="prev"

Let’s talk about what each link means. rel="next" lets us know that the next page of data is page=4. This make sense given that we requested page 3. rel="prev" lets us know that the page previous to the one we requested is page=2. rel="next" indicates the next page of data to request. rel="last" tells us the last and total number of pages of data that currently exist.

Not all rel= links will exist on every response. For instance, the response for the first page of data will not have rel="first" or rel="prev". The same is true for the last page of data. This means that you can programmatically traverse all pages of data by requesting the first page and continuing to request the rel="next" until the response does not contain a rel="next".

It’s important to note that altering the per_page= will change the total number of pages.

Listing Image

If you are uploading a product image in SVG format. You will need to specify the file type.

curl https://www.my-catalog.edu/api/v1/products -F "course[listing_image]=@somefile.svg;type=image/svg+xml"'