Tags and Tag Categories

Intro

Tags are used to mark objects in Metro Publisher, for example to define what an article is about, who wrote the book that is being reviewed, or who took a photo that is attached to the article.

Each tag has a public overview page ("/topics/<tag-urlname>") which lists all (published) objects that were marked by the tag.

Tags are split up into two different types:

• person
• other

Every tag has the following information:

• type
• urlname
• title / last name
• content
• description
• feature image
• synonyms
• state

Person tags, i.e. tags with type=='person', have an additional attribute:

• first name

This attribute is not required and may be empty.

Note

Tags can be used on various objects in Metro Publisher. See Tagging for information about how to mark objects with tags.

Goal

In this chapter we will create several tags as well as two tag categories to group the tags.

Tags:

• Rome
  • type: default
  • UUID: aaaaaaaa-aaaa-aaaa-aaaa-111111111111
• Mike Meyers
  • type: person
  • UUID: aaaaaaaa-aaaa-aaaa-aaaa-222222222222
• Jane Doe
  • type: person
  • UUID: aaaaaaaa-aaaa-aaaa-aaaa-333333333333
• London
  • type: default
  • UUID: aaaaaaaa-aaaa-aaaa-aaaa-444444444444
• New York
  • type: default
  • UUID: aaaaaaaa-aaaa-aaaa-aaaa-555555555555

Categories:

• Authors (UUID: 11111111-1111-1111-1111-111111111111)
• Cities (UUID: 22222222-2222-2222-2222-222222222222)

Tags

Creating Tags

The first tag we are going to add, is a non-person (i.e. 'default') type of tag: Rome.

>>> PUT("/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-111111111111",
...     {'type': 'default',
...      'last_name_or_title': 'Rome',
...      'urlname': 'rome',
...      'state': 'approved'})
{'url': 'https://api.metropublisher.com/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-111111111111'}

The next tag is a person tag. Person tags have the attribute first_name in addition to the normal title-related attribute last_name_or_title. For the tag 'Mike Meyers' we'll add a bit more information, such as content, feature_image (an image from the Metro Publisher File Library that was uploaded some time earlier), created and modified, just to give the tag a bit more "life":

>>> PUT("/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-222222222222",
...     {'type': 'person',
...      'last_name_or_title': 'Meyers',
...      'first_name': 'Mike',
...      'urlname': 'mike-meyers',
...      'email': 'mm@test-newsmag.com',
...      'twitter_username': '@mike_meyers_tnm',
...      'content': '<p>Mike Meyers is the <em>Editor-in-chief</em> and has been with our publication since 1991.</p>',
...      'state': 'approved',
...      'created': '2014-11-10T12:00',
...      'modified': '2014-11-10T12:00',
...      'feature_image_uuid': '12345678-1234-1234-1234-123456789abc'})
{'url': 'https://api.metropublisher.com/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-222222222222'}

Note

The content field allows XML-compliant HTML, with restrictions. The field value must comply with the HTML schema shown in RelaxNG Schema for XML-compliant HTML.

Let's add the other three tags so we can use them later:

>>> PUT("/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-333333333333",
...     {'type': 'person',
...      'last_name_or_title': 'Doe',
...      'first_name': 'Jane',
...      'urlname': 'jane-doe',
...      'state': 'approved'})
{'url': 'https://api.metropublisher.com/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-333333333333'}
>>> PUT("/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-444444444444",
...     {'type': 'default',
...      'last_name_or_title': 'London',
...      'urlname': 'london',
...      'state': 'approved'})
{'url': 'https://api.metropublisher.com/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-444444444444'}
>>> PUT("/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-555555555555",
...     {'type': 'default',
...      'last_name_or_title': 'New York',
...      'urlname': 'new-york',
...      'state': 'approved'})
{'url': 'https://api.metropublisher.com/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-555555555555'}

Retrieving a List of Tags

Now that the five tags were added, we can send a request to GET /{iid}/tags and see a list of these tags. There are a number of fields that can be specified to define what information is returned for each tag:

>>> GET("/123/tags?fields=title-last_name_or_title-first_name-type")
{'items': [['Jane Doe', 'Doe', 'Jane', 'person'],
           ['London', 'London', None, 'default'],
           ['Mike Meyers', 'Meyers', 'Mike', 'person'],
           ['New York', 'New York', None, 'default'],
           ['Rome', 'Rome', None, 'default']]}

See /{iid}/tags for a list of available parameters for this collection resource.

Retrieving Tag Information

The Mike Meyers tag we added earlier has the most data, so let's send a GET request to the resource /{iid}/tags/{uuid} to retrieve the information for this tag:

>>> GET("/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-222222222222")
{'content': '<p>Mike Meyers is the <em>Editor-in-chief</em> and has been with our publication since 1991.</p>',
 'created': '2014-11-10T12:00:00',
 'description': None,
 'email': 'mm@test-newsmag.com',
 'fb_username': None,
 'feature_image_url': 'https://api.metropublisher.com/123/files/12345678-1234-1234-1234-123456789abc',
 'first_name': 'Mike',
 'instagram_username': None,
 'last_name_or_title': 'Meyers',
 'linkedin_url': None,
 'modified': '2014-11-10T12:00:00',
 'objectcount': 0,
 'state': 'approved',
 'synonyms': None,
 'title': 'Mike Meyers',
 'twitter_username': '@mike_meyers_tnm',
 'type': 'person',
 'url': 'https://api.metropublisher.com/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-222222222222',
 'urlname': 'mike-meyers',
 'uuid': 'aaaaaaaa-aaaa-aaaa-aaaa-222222222222',
 'website': None}

Categories

As mentioned above, categories are groupings of tags. We want to group the five tags we added into two categories: Authors and Cities.

Creating Tag Categories

To create a category, we send a PUT request to /{iid}/tags/categories/{uuid}. At the moment, tag categories consist only of a title and a UUID, so the data sent to the resource is simple:

>>> PUT("/123/tags/categories/11111111-1111-1111-1111-111111111111",
...     {'title': 'Authors'})
{'url': 'https://api.metropublisher.com/123/tags/categories/11111111-1111-1111-1111-111111111111',
 'uuid': '11111111-1111-1111-1111-111111111111'}

>>> PUT("/123/tags/categories/22222222-2222-2222-2222-222222222222",
...     {'title': 'Cities'})
{'url': 'https://api.metropublisher.com/123/tags/categories/22222222-2222-2222-2222-222222222222',
 'uuid': '22222222-2222-2222-2222-222222222222'}

Adding Tags to a Category

Now that there are two categories, we can add tags to each category. The easiest way to do this is by sending a PUT request with a list of the tag UUIDs to /{iid}/tags/categories/{uuid}:

>>> PUT("/123/tags/categories/11111111-1111-1111-1111-111111111111/tags",
...     {'items': ['aaaaaaaa-aaaa-aaaa-aaaa-222222222222',
...                'aaaaaaaa-aaaa-aaaa-aaaa-333333333333']})
{'msg': 'category tags updated'}

The above resource sets the entire list of the category tags. It is also possible to add tags individually to a category. For this we send POST requests to /{iid}/tags/categories/{uuid}/tags with one tag UUID:

>>> POST("/123/tags/categories/22222222-2222-2222-2222-222222222222/tags",
...     {'tag_uuid': 'aaaaaaaa-aaaa-aaaa-aaaa-111111111111'})
{'msg': 'tag added to category'}
>>> POST("/123/tags/categories/22222222-2222-2222-2222-222222222222/tags",
...     {'tag_uuid': 'aaaaaaaa-aaaa-aaaa-aaaa-444444444444'})
{'msg': 'tag added to category'}
>>> POST("/123/tags/categories/22222222-2222-2222-2222-222222222222/tags",
...     {'tag_uuid': 'aaaaaaaa-aaaa-aaaa-aaaa-555555555555'})
{'msg': 'tag added to category'}

Getting Category Tags

To see the tags associated with a specific category, we send a GET request to /{iid}/tags/categories/{uuid}/tags:

>>> GET("/123/tags/categories/11111111-1111-1111-1111-111111111111/tags?fields=title-uuid")
{'items': [['Jane Doe', 'aaaaaaaa-aaaa-aaaa-aaaa-333333333333'],
           ['Mike Meyers', 'aaaaaaaa-aaaa-aaaa-aaaa-222222222222']]}

>>> GET("/123/tags/categories/22222222-2222-2222-2222-222222222222/tags?fields=title-uuid")
{'items': [['London', 'aaaaaaaa-aaaa-aaaa-aaaa-444444444444'],
           ['New York', 'aaaaaaaa-aaaa-aaaa-aaaa-555555555555'],
           ['Rome', 'aaaaaaaa-aaaa-aaaa-aaaa-111111111111']]}

You can see the available parameters for this collection resource here.

Getting Tag Categories

Above, we retrieved the tags associated with a category. To see the other direction of this connection, i.e. the categories associated with a specific tag, we send a GET request to /{iid}/tags/{uuid}/categories, which is a sub-resource of the tag resource for one specific tag (the UUID here is the tag's UUID):

>>> GET("/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-111111111111/categories?fields=title-uuid")
{'items': [['Cities', '22222222-2222-2222-2222-222222222222']]}

So, the tag Rome (UUID: aaaaaaaa-aaaa-aaaa-aaaa-111111111111) is associated with the category Cities.

The available parameters for this resource are listed here.