Items and Resources are Different Things - Talis Aspire APIs Documentation

Concepts :: Items and Resources are Different Things

Background

Talis Aspire provides a way for people to bookmark many “things” from many places and use these “things” on many different lists, and multiple times on any list. There are many-to-many relationships at all these points and we discuss these in more detail in this article.

Terminology

List
- noun: A list is a collection of items in some user defined order. Each list is identified by a unique ID.
Item
- noun: An Item is a unique occurrence of a resource on a list in a particular position. If a resource appears on a list multiple times, it will be represented as a number of different and unique Items. Each item is identified by a unique ID. Items may have additional data related to their position on a list, such as importance and library note.
Resource
- noun: A thing, taking the form of a collection of metadata, that will later be added to a reading list. It could be anything from a print book to an online resource. It will have a title and a type as a minimum and may have a mixture of other properties which describe what it is. Each resource is identified by a unique identifier (ID).
Bookmark
- verb: The capturing of a resource from some other source for later addition to a list.
- noun: The captured resource in the collection of resources collected by a single user.

Relationships

The Talis Aspire V3 APIs provide a mechanism for identifying which resource is related to which item.

It is often useful to get both the item and resource in a single API call by using getItem and the include=resource parameter to get the resource details.

https://rl.talis.com/3/{shortCode}/items/{itemGuid}?include=resource

The resource details will be in the included section of the response and will be referenced using a type of resource and an id that is found in the key data.relationships.resource.data.id property.

{
    "data": {
        "type": "items",
        "id": "379acae3-a516-4997-bba3-f5e621cc08a7",
        "attributes": {
            "student_note": "",
            "library_note": ""
        },
        "relationships": {
            "tenant": {
                "data": {
                    "type": "tenants",
                    "id": "technicalone"
                }
            },
            "content": {
                "data": null
            },
            "importance": {
                "data": null
            },
            "resource": {
                "data": {
                    "type": "resources",
                    "id": "09FB55AE-4630-0FB2-5EBE-785B4FED0ED5"
                }
            }
        },
        "links": {
            "self": "https://rl.talis.com/3/technicalone/items/379acae3-a516-4997-bba3-f5e621cc08a7"
        },
        "meta": {
            "default_online_resource": {
                "isbns": [
                    "9781539370895"
                ],
                "type": "google_books"
            }
        }
    },
    "included": [
        {
            "type": "resources",
            "id": "09FB55AE-4630-0FB2-5EBE-785B4FED0ED5",
            "attributes": {
                "authors": [
                    {
                        "first_name": "Cs",
                        "surname": "Creations",
                        "type": "person"
                    }
                ],
                "editors": [],
                "isbn10s": [],
                "isbn13s": [
                    "9781539370895"
                ],
                "dates": [
                    "2016-10-06"
                ],
                "doi": null,
                "edition": null,
                "eissns": [],
                "issns": [],
                "issue": null,
                "lcn": null,
                "format": null,
                "online_resource": null,
                "page_start": null,
                "page_end": null,
                "places_of_publication": [],
                "publisher_names": [
                    "Createspace Independent Publishing Platform"
                ],
                "resource_type": "Book",
                "title": "Enigma Rotor-Key Machine Journal",
                "volume": null,
                "web_addresses": null
            },
            "meta": {
                "default_online_resource": {
                    "isbns": [
                        "9781539370895"
                    ],
                    "type": "google_books"
                }
            }
        }
    ]
}