Collections

Listing Collections

GET /api2/collections

List all collections that the user is authorized to see.

This returns a flat list of collections. If you need a hierarchical view of the collections, see GET /api2/collections/tree.

Query Parameters:
 
  • permission (optional) – Return only those collections where you have the specified permission.
  • is_podcast (optional) – Return only podcast collections by setting this to 1. Return only non-podcast collections by setting this to 0. Leave this undefined to get both podcast and non-podcast collections.
  • parent_id (optional) – Filter for collections that are direct descendants of the given parent collection ID.
  • display_name (optional) – Filter for collections by name. It must be an exact match to be returned.
  • joins (optional) – A comma separated list of links to bundle into the response. Currently, the only supported value is thumbs. See Joining related GET requests.

Note

This requires the collection-read permission.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "items": [
    {
      "id": "1",
      "parent_id": null,
      "slug": "pacific-university",
      "display_name": "Pacific University",
      "description": "<p>Welcome to the Pacific University library.</p>",
      "description_plain": "Welcome to the Pacific University library.",
      "media_count": 31,
      "inherit_memberships": false,
      "is_podcast": false,
      "autotranscribe_enabled": false,
      "autotranscribe_subcollections": false,
      "autotranscribe_profile_id": null,
      "links": {
         "self": "/api2/collections/1",
         "parent": "/api2/collections/",
         "media": "/api2/media?collection_id=1",
         "podcast_details": null,
         "thumbs": "/api2/collections/1/thumbs",
         "view": "/api2/collections/1/view"
      }
    }
  ],
  "links": {
    "self": "/api2/collections?per_page=1&_p=3",
    "prev": "/api2/media?per_page=1&_p=2",
    "next": "/api2/media?per_page=1&_p=4"
  }
}

Manually Constructing a Collections Tree

Note

There is now an endpoint that returns all collections in a tree structure. See GET /api2/collections/tree.

Constructing a complete Collections tree can be tricky. Keep in mind the following:

  • The Collection hierarchy is not, strictly speaking, a Tree. It may actually be a Forest of Trees (i.e. there may be many trees, each with their own root).
  • There may be more than one page of collections results. Consult Pagination for a description of how to traverse all pages of results.
  • A collection whose parent_id is null is a root node.
  • A collection whose parent_id doesn’t appear as an id of any other collection is a root node.

The following is an example of how you might properly construct a Collections hierarchy in Python.

def get_all_collections(api_client):
    all_collections = list()
    response_data = api_client.get('/api2/collections')

    while response_data:
        for item in response_data['items']:
            all_collections.append(item)

        next_page_url = response_data['links']['next']
        if next_page_url:
            response_data = api_client.get(next_page_url)
        else:
            response_data = None

    return all_collections

def nest_collections(collections):
    available_ids = set()
    children_for_id = dict()

    # Map each Collection ID to a list of the children of that Collection
    for cln in collections:
        id = cln['id']
        available_ids.add(id)
        children_for_id[id] = list()

    # The root nodes will be in this list
    children_for_id['no_parent'] = list()

    # Populate the arrays of children
    for cln in collections:
        id = cln['id']
        parent_id = cln['parent_id']

        if parent_id not in available_ids:
            parent_id = 'no_parent'

         child_list = children_for_id[parent_id]
         child_list.append(cln)

    return children_for_id

 # Print all the root nodes and their direct children
 collections = get_all_collections(api_client)
 children_for_id = nest_collections(collections)
 root_nodes = children_for_id['no_parent']
 for cln in root_nodes:
     print 'Root node:', cln
     cln_id = cln['id']
     children = children_for_id[cln_id]
     for child_cln in children:
         print '    child:', child_cln

Fetching the Collections Tree

GET /api2/collections/tree

Fetch all available collections in a tree structure.

There will always be one root collection. In some cases, an artificial root will be created with an ID of “-1”.

Query Parameters:
 
  • root_id (optional) – Specify a collection ID which should be the root of the tree.
  • permission (optional) – Return only those collections where you have the specified permission.
  • media_count (optional) – Add a media_count attribute to each collection. You must specify either all (to return the count of all items including drafts) or published (to return the count of only published items).
  • additive_counts (optional) – Whether to include an additive_count which is the sum of its media items and all the media items within its descendant collections.
  • omit_empty (optional) – Whether to filter out collections which contain no media items and have no descendant collections which contains media items.

Example response with no ?media_count parameter:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "root": {
    "id": "100",
    "display_name": "My MediaCore Site",
    "is_podcast": false,
    "slug": "my-mediacore-site",
    "children": [
      {
        "id": "101",
        "display_name": "Public",
        "is_podcast": false,
        "slug": "slug",
        "children": []
      },
      {
        "id": "102",
        "display_name": "Courses",
        "is_podcast": false,
        "slug": "courses",
        "children": [
          {
            "id": "103",
            "display_name": "Econ 100",
            "is_podcast": false,
            "slug": "econ-100",
            "children": []
          }
        ]
      }
    ]
  }
}

Example response for ?media_count=published:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "root": {
    "id": "100",
    "display_name": "My MediaCore Site",
    "is_podcast": false,
    "slug": "my-mediacore-site",
    "media_count": 0,
    "children": [
      {
        "id": "101",
        "display_name": "Public",
        "is_podcast": false,
        "slug": "slug",
        "media_count": 5,
        "children": []
      },
      {
        "id": "102",
        "display_name": "Courses",
        "is_podcast": false,
        "slug": "courses",
        "media_count": 0,
        "children": [
          {
            "id": "103",
            "display_name": "Econ 100",
            "is_podcast": false,
            "slug": "econ-100",
            "media_count": 3,
            "children": []
          }
        ]
      }
    ]
  }
}

Example response for ?media_count=published&additive_counts=1:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "root": {
    "id": "100",
    "display_name": "My MediaCore Site",
    "is_podcast": false,
    "slug": "my-mediacore-site",
    "media_count": 8,
    "children": [
      {
        "id": "101",
        "display_name": "Public",
        "is_podcast": false,
        "slug": "slug",
        "media_count": 5,
        "children": []
      },
      {
        "id": "102",
        "display_name": "Courses",
        "is_podcast": false,
        "slug": "courses",
        "media_count": 3,
        "children": [
          {
            "id": "103",
            "display_name": "Econ 100",
            "is_podcast": false,
            "slug": "econ-100",
            "media_count": 3,
            "children": []
          }
        ]
      }
    ]
  }
}

Example response with an artificial root collection:

In this example, the user has access to Public and Econ 100 but not My MediaCore Site or Courses. For consistency, we create a special My Collections root for the tree.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "root": {
    "id": "-1",
    "display_name": "My Collections",
    "is_podcast": null,
    "slug": "my-collections",
    "children": [
      {
        "id": "101",
        "display_name": "Public",
        "is_podcast": false,
        "slug": "slug",
        "media_count": 5,
        "children": []
      },
      {
        "id": "103",
        "display_name": "Econ 100",
        "is_podcast": false,
        "slug": "econ-100",
        "media_count": 3,
        "children": []
      }
    ]
  }
}

Fetching a Collection

GET /api2/collections/(collection_id)

Fetch an individual collection by its unique ID.

Query Parameters:
 
  • joins (optional) – A comma separated list of links to bundle into the response. Currently, the only supported value is thumbs. See Joining related GET requests.

Note

This requires the collection-read permission.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "1",
  "parent_id": null,
  "slug": "pacific-university",
  "display_name": "Pacific University",
  "description": "<p>Welcome to the Pacific University library.</p>",
  "description_plain": "Welcome to the Pacific University library.",
  "media_count": 31,
  "inherit_memberships": false,
  "is_podcast": false,
  "autotranscribe_enabled": false,
  "autotranscribe_subcollections": false,
  "autotranscribe_profile_id": null,
  "links": {
    "self": "/api2/collections/1",
    "parent": "/api2/collections/",
    "media": "/api2/media?collection_id=1",
    "podcast_details": null,
    "thumbs": "/api2/collections/1/thumbs",
    "view": "/api2/collections/1/view"
  }
}

Creating a Collection

POST /api2/collections

Add a new collection.

Json Parameters:
 
  • display_name (required) – Display name for the collection.
  • parent_id (required) – The ID of the collection that will become the new parent.
  • slug (optional) – The slug to use in the collection URL. Must be unique in your site. Attempting to use a duplicate slug will result in a 409 Conflict response.
  • is_podcast (optional) – Whether to make the new collection a podcast.
  • autotranscribe_enabled (optional) – Whether to automatically create a transcription job for new media items in this collection.
  • autotranscribe_profile_id (optional) – The ID of a transcription profile to use when automatically transcribing media items in this collection.
  • autotranscribe_subcollections (optional) – Whether to also apply autotransctiption settings to subcollections.
  • inherit_memberships (optional) – Whether to inherit the memberships of the parent collection. This will give the same access permissions to the new collection as its parent.
  • description (optional) – A string of XHTML to use as the collection’s description.

Example Response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api2/collections/1

{
  "id": "1",
  "parent_id": null,
  "slug": "pacific-university",
  "display_name": "Pacific University",
  "description": "<p>Welcome to the Pacific University library.</p>",
  "description_plain": "Welcome to the Pacific University library.",
  "media_count": 0,
  "inherit_memberships": false,
  "is_podcast": false,
  "autotranscribe_enabled": false,
  "autotranscribe_subcollections": false,
  "autotranscribe_profile_id": null,
  "links": {
    "self": "/api2/collections/1",
    "parent": "/api2/collections/",
    "media": "/api2/media?collection_id=1",
    "podcast_details": null,
    "thumbs": "/api2/collections/1/thumbs",
    "view": "/api2/collections/1/view"
  }
}

Note

This requires the collection-create permission.

Updating a Collection

POST /api2/collections/(collection_id)

Update an individual collection.

All fields are optional; only the fields specified will be saved to the media item.

This endpoint accepts all the same JSON fields as GET /api2/collections/create.

Note

This requires the collection-update permission.

POST /api2/collections/(collection_id/reslugify

Regenerate the slug of a collection

Note

This requires the collection-update permission.

POST /api2/collections/(collection_id)/move

Trying to move a collection into one of its own sub-collections will result in a 403 Forbidden response.

Trying to move a root collection result in a 403 Forbidden response.

Move a collection in the collections tree.

Json Parameters:
 
  • new_parent_id (required) – The ID of the collection that will become the new parent.

Note

This requires the collection-move permission on the moving collection, and on the old parent of the moving collection, collection-create in the new parent collection, and collection-delete in the former parent collection.

Deleting a Collection

DELETE /api2/collections/(collection_id)

Delete a collection and all of its descendant collections.

All media items within the collection must be deleted first. Attempting to delete a collection that still has media in it will result in a 409 Conflict response.

Root collection can not be deleted. Attempting to delete a collection that is root will result in a 409 Conflict response.

This endpoint is idempotent; attempting to delete a media item that does not exist will return a successful response.

Note

This requires the collection-delete permission on this collection and all of its descendants.

Example Response:

HTTP/1.1 204 No Content

Podcasts

There are also a number of podcast-specific endpoints.

Note

The following methods will only work on collections that are podcasts. Attempting to use them with non-podcast collections will result in a 400 Bad Request response.

GET /api2/collections/(collection_id)/podcast-details

Get podcast-specific details for a collection.

Example Response:

HTTP/1.1 200 OK

{
  "itunes_author_name": "Paul Lansky",
  "itunes_author_email": "paul@somedomain.com",
  "itunes_subtitle": "Podcast Subtitle",
  "itunes_explicit": "clean",
  "itunes_category": "Arts > Design",
  "copyright": "2015 Paul Lansky",
  "itunes_url": null,
  "itunesu_category": null,
  "feedburner_url": null
}

Note

This requires the collection-read permission on this collection.

POST /api2/collections/(collection_id)/podcast-details

Update the details of a podcast

Json Parameters:
 
  • itunes_author_name (optional) – The author of the podcast.
  • itunes_author_email (optional) – The podcast author’s email address.
  • itunes_subtitle (optional) – The podcast subtitle.
  • itunes_explicit (optional) – Whether or not the podcast contains explicit content. Must be one of no, yes, or clean.
  • itunes_category (optional) – The iTunes category and subcategory this podcast belongs in.
  • copyright (optional) – A string of copyright information.
  • itunes_url (optional) – The podcast’s url in iTunes.
  • intunesu_category (optional) – The podcast’s iTunesU category.
  • feedburner_url (optional) – The podcast’s FeedBurner url.

Example Response:

HTTP/1.1 200 OK

{
  "itunes_author_name": "Paul Lansky",
  "itunes_author_email": "paul@somedomain.com",
  "itunes_subtitle": "Podcast Subtitle",
  "itunes_explicit": "clean",
  "itunes_category": "Arts > Design",
  "copyright": "2015 Paul Lansky",
  "itunes_url": null,
  "itunesu_category": null,
  "feedburner_url": null
}

Note

This requires the collection-update permission on this collection.