Tagging

Goal

Let's say we have four different objects:

• an article:
  • title: 'My Last Trip to Rome'
  • UUID: 11111111-1111-1111-1111-111111111111
• a blog:
  • title: 'Rome Vacation Blog'
  • UUID: 22222222-2222-2222-2222-222222222222
• a file:
  • title: 'Rome 01'
  • UUID: 33333333-3333-3333-3333-333333333333
• a book review:
  • title: 'Rome Travel Guide - Book Review'
  • UUID: 44444444-4444-4444-4444-444444444444

We also have two tags:

• a geography tag:
  • title: 'Rome'
  • UUID: aaaaaaaa-aaaa-aaaa-aaaa-111111111111
• an author tag:
  • last name: 'Meyers'
  • first name: 'Mike'
  • UUID: aaaaaaaa-aaaa-aaaa-aaaa-222222222222

All four objects have something to do with the city of Rome, so it makes sense to tag them all with the 'Rome' tag. Tagging the objects with the same tag will allow us to get a collection of the tagged objects in order to, for example, construct an overview of objects that concern a specific topic, in this case the topic of Rome.

Tagging Objects

So, let's start by tagging the article, i.e. assigning the tag 'Rome' to the article 'My Last Trip to Rome':

>>> PUT("/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-111111111111/describes/11111111-1111-1111-1111-111111111111",
...     {'created': '2012-08-12T10:00:00'})
{'url': 'https://api.metropublisher.com/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-111111111111/describes/11111111-1111-1111-1111-111111111111'}

The syntax here says:

The tag 'Rome' (UUID: aaaaaaaa-aaaa-aaaa-aaaa-111111111111) describes something inside the article 'My Last Trip to Rome' (UUID: 11111111-1111-1111-1111-111111111111). The resource url (/{iid}/tags/{uuid}/{predicate}/{object_uuid}) contains the tag predicate "describes", therefore defining the relationship between the tag and the article. The 'created' parameter passed to the resource tells the system at what date/time the article was tagged.

Let's do the same with the other three objects: the blog, the file and the book review.

>>> PUT("/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-111111111111/describes/22222222-2222-2222-2222-222222222222",
...     {'created': '2012-08-12T10:15:00'})
{'url': 'https://api.metropublisher.com/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-111111111111/describes/22222222-2222-2222-2222-222222222222'}

>>> PUT("/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-111111111111/describes/33333333-3333-3333-3333-333333333333",
...     {'created': '2012-08-12T10:30:00'})
{'url': 'https://api.metropublisher.com/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-111111111111/describes/33333333-3333-3333-3333-333333333333'}

>>> PUT("/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-111111111111/describes/44444444-4444-4444-4444-444444444444",
...     {'created': '2012-08-12T10:45:00'})
{'url': 'https://api.metropublisher.com/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-111111111111/describes/44444444-4444-4444-4444-444444444444'}

All four objects (article, blog, file, book review) have now been tagged with the 'Rome' tag. There are various ways to see this but we'll get to that later.

Right now, we also want to let the system know that Mike Meyers is the author of the article. We already have a tag for Mike but this time we need a different type of relationship between the tag and the article. In this case, the tag isn't describing something inside the article, so the relationship is not 'tag'->'describes'->'object'. Mike is the author of the article, therefore the relationship is 'tag'->'authored'->'object'.

>>> PUT("/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-222222222222/authored/11111111-1111-1111-1111-111111111111",
...     {'created': '2012-08-12T10:45:00'})
{'url': 'https://api.metropublisher.com/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-222222222222/authored/11111111-1111-1111-1111-111111111111'}

The predicate here is authored.

Let's say that Mike Meyers wrote the book that is reviewed in the book review 'Rome Travel Guide - Book Review'.With a book review, there are some additional predicates that can be used to define a relationship between a tag and an object. In this case we want to let the system know that Mike Meyers is the author/creator of the book, not the author of the book review. For this we use the review predicate created_reviewed:

>>> PUT("/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-222222222222/created_reviewed/44444444-4444-4444-4444-444444444444",
...     {'created': '2012-08-12T11:00:00'})
{'url': 'https://api.metropublisher.com/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-222222222222/created_reviewed/44444444-4444-4444-4444-444444444444'}

Since the object '44444444-4444-4444-4444-444444444444' is a book review, the predicate created_reviewed refers to who created the book that the review is about.

Here's what we have now:

• all four objects (article, blog, file, review) tagged with 'Rome'
• one object (article) tagged with 'Meyers, Mike' as the author
• one object (book review) tagged with 'Meyers, Mike' as the author of the reviewed book

Retrieving Tagging Information

If we want to construct an overview page with objects concerning the topic 'Rome', we can retrieve a list of tagged objects like this:

>>> GET("/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-111111111111/describes?fields=created-object_url&order=created.desc")
{'items': [['2012-08-12T10:45:00',
            'https://api.metropublisher.com/123/content/44444444-4444-4444-4444-444444444444'],
           ['2012-08-12T10:30:00',
            'https://api.metropublisher.com/123/files/33333333-3333-3333-3333-333333333333'],
           ['2012-08-12T10:15:00',
            'https://api.metropublisher.com/123/blogs/22222222-2222-2222-2222-222222222222'],
           ['2012-08-12T10:00:00',
            'https://api.metropublisher.com/123/content/11111111-1111-1111-1111-111111111111']]}

With the information returned here, we can make calls to the API using the returned urls (object_url) in order to retrieve the objects' titles, issue dates, etc.

>>> GET("https://api.metropublisher.com/123/content/11111111-1111-1111-1111-111111111111")
{'blog_uuid': None,
 'canonical_url': None,
 'content': '<p>Wonderful trip!</p>',
 'content_type': 'article',
 'created': '2012-08-08T10:00:00',
 'description': None,
 'evergreen': False,
 'feature_image_alttext': None,
 'feature_image_caption': None,
 'feature_image_url': None,
 'feature_thumb_url': None,
 'header_image_url': None,
 'issued': '2012-08-08T12:00:00',
 'meta_description': None,
 'meta_title': None,
 'modified': '2012-08-08T11:59:00',
 'perma_url_path': None,
 'print_description': None,
 'section_uuid': None,
 'state': 'draft',
 'sub_title': None,
 'teaser_image_url': None,
 'title': 'My Last Trip to Rome',
 'urlname': 'my-last-trip-to-rome',
 'uuid': '11111111-1111-1111-1111-111111111111',
 'video_uuid': None}

To find out the tags for a specific object, let's say the article, we can call a tags resource for an article: /{iid}/content/{uuid}/tags

>>> GET("/123/content/11111111-1111-1111-1111-111111111111/tags")
{'items': [{'predicate': 'describes',
            'title': 'Rome',
            'url': 'https://api.metropublisher.com/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-111111111111',
            'uuid': 'aaaaaaaa-aaaa-aaaa-aaaa-111111111111'},
           {'predicate': 'authored',
            'title': 'Mike Meyers',
            'url': 'https://api.metropublisher.com/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-222222222222',
            'uuid': 'aaaaaaaa-aaaa-aaaa-aaaa-222222222222'}]}

This can also be split up to just retrieve the tags with a specific predicate, such as 'authored':

>>> GET("/123/content/11111111-1111-1111-1111-111111111111/tags/authored")
{'items': [{'predicate': 'authored',
            'title': 'Mike Meyers',
            'url': 'https://api.metropublisher.com/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-222222222222',
            'uuid': 'aaaaaaaa-aaaa-aaaa-aaaa-222222222222'}]}