Tag

Tags are keywords that can be associated with any piece of content within Metro Publisher. They appear by default in the public pages of all content types as links to topics pages. This allows visitors to a Metro Publisher site to find other content that might interest them based on a topic or subject.

Synonyms

Synonyms are used to find tags already in the system. In order to avoid duplicating similar tags, the search for tags in the admin will return results based on synonyms.

Tag Categories

As of MP 2.14, tags can be grouped into custom categories. A tag can be in more than one category but not more than once in one specific category.

/{iid}/tags/categories

GET

Additional Information

Roles:

• public_user
• super

Retrieve a batched collection of tag categories.

This resource returns a batched list of tag categories.

Sample Call

>>> GET("/123/tags/categories?fields=uuid-title-url&order=title")
{'items': [['22222222-2222-2222-2222-222222222222',
            'Another Category',
            'https://api.metropublisher.com/123/tags/categories/22222222-2222-2222-2222-222222222222'],
           ['11111111-1111-1111-1111-111111111111',
            'Category 1',
            'https://api.metropublisher.com/123/tags/categories/11111111-1111-1111-1111-111111111111']]}

Parameters

page:

The page number to retrieve.

optional

Default: 1

Values must not be lower than 1

rpp:

The number of results per page.

optional

Default: 20

Values must not be lower than 1 or higher than 100

fields:

A dash-separated list of fields to return.

optional

Default: ['url']

Example value: 'title-uuid'

Every element of the list must be any of the following

title:The category title url:URL to the category uuid:The UUID of the category

order:

A dash-separated list of orderings to apply

optional

Default: []

Example value: 'title'

Every element of the list must be any of the following

title:Sort by title ascending title.asc:Sort by title ascending title.desc:Sort by title descending

/{iid}/tags/categories/{uuid}

GET

Additional Information

Roles:

• public_user
• super

Retrieve one tag category.

This resource returns information about one specific tag category.

Sample Call

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

Return Value

title: url:The URL to the tag uuid:The UUID of the tag.

PUT

Additional Information

Roles:

• super

Create/update a tag category.

Sending data to this resource does one of two things:

• creates a new category if no category with the given UUID was found, or
• updates the category with the given UUID.

See also Tagging.

Sample Call

>>> PUT("/123/tags/categories/12345678-1234-1234-1234-123456789abc",
...            {"title": "Category A"})
{'url': 'https://api.metropublisher.com/123/tags/categories/12345678-1234-1234-1234-123456789abc',
 'uuid': '12345678-1234-1234-1234-123456789abc'}

Parameters

title:

The category title

required

Example value: "Companies & other Organizations"

/{iid}/tags/categories/{uuid}

PATCH

Additional Information

Roles:

• super

Update a tag category.

Sample Call

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

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

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

Parameters

title:

The category title

required

Example value: "Companies & other Organizations"

/{iid}/tags/categories/{uuid}/tags

GET

Additional Information

Roles:

• public_user
• super

Retrieve a batched collection of tags of a specific category.

This resource returns a batched list of tags that are assigned to a specific category.

Sample Call

>>> GET("/123/tags/categories/11111111-1111-1111-1111-111111111111/tags?fields=uuid-title-url&order=title")
{'items': [['7fbbe910-a998-11e1-afa6-0800200c9a66',
            'Jane Doe',
            'https://api.metropublisher.com/123/tags/7fbbe910-a998-11e1-afa6-0800200c9a66'],
           ['60183d70-a998-11e1-afa6-0800200c9a66',
            'Sample Tag',
            'https://api.metropublisher.com/123/tags/60183d70-a998-11e1-afa6-0800200c9a66']]}

Parameters

page:

The page number to retrieve.

optional

Default: 1

Values must not be lower than 1

rpp:

The number of results per page.

optional

Default: 20

Values must not be lower than 1 or higher than 100

state:

optional

Default: 'approved' if the user is a public user else None.

Values must be any of the following

internal:

Only internal tags

Access is restricted to users with these roles:

• super

approved:

Only approved tags

provisional:

Only provisional tags

Access is restricted to users with these roles:

• super

fields:

A dash-separated list of fields to return.

optional

Default: ['url']

Example value: 'category-uuid'

Every element of the list must be any of the following

first_name:The first name if the tag is a "person", or None if the tag is a "default" tag. last_name_or_title:The last name if the tag is a "person", or the tag title if the tag is a "default" tag. title:The diplay title of the tag type:The tag type url:URL to the tag urlname:The urlname uuid:The UUID of the tag

order:

A dash-separated list of orderings to apply

optional

Default: []

Example value: 'first_name-urlname.desc'

Every element of the list must be any of the following

first_name:Sort by first name (applies to "person" tag only) ascending first_name.asc:Sort by first name (applies to "person" tag only) ascending first_name.desc:Sort by first name (applies to "person" tag only) descending last_name_or_title:Sort by last name / title ascending last_name_or_title.asc:Sort by last name / title ascending last_name_or_title.desc:Sort by last name / title descending title:Sort by title ascending title.asc:Sort by title ascending title.desc:Sort by title descending urlname:Sort by urlname ascending urlname.asc:Sort by urlname ascending urlname.desc:Sort by urlname descending uuid:Sort by uuid ascending uuid.asc:Sort by uuid ascending uuid.desc:Sort by uuid descending

type:

optional

Default: None

Values must be any of the following

person: default:

POST

Additional Information

Roles:

• super

Add a tag to a specific category.

This resource add the tag with the given UUID to the category.

Sample Call

Set the tags of a category:

>>> POST("/123/tags/categories/11111111-1111-1111-1111-111111111111/tags",
...            {'tag_uuid': "60183d70-a998-11e1-afa6-0800200c9a66"})
{'msg': 'tag added to category'}

Parameters

tag_uuid:

required

each item must be an existing tag UUID

PUT

Additional Information

Roles:

• super

Create/update the tags of the tag category.

This resource creates/replaces the tags of the category.

Sample Call

Set the tags of a category:

>>> PUT("/123/tags/categories/11111111-1111-1111-1111-111111111111/tags",
...            {'items': ["60183d70-a998-11e1-afa6-0800200c9a66",
...                       "7fbbe910-a998-11e1-afa6-0800200c9a66"]})
{'msg': 'category tags updated'}

Clear all tags from the category:

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

Parameters

items:

required

each item must be an existing tag UUID

Tags

/{iid}/tags

GET

Additional Information

Roles:

• public_user

  Only published tags.

• super

Retrieve a batched collection of tags.

This resource returns a batched list of tags. The tag information returned depends on the fields parameter.

See also Tagging.

Sample Call

>>> GET("/123/tags?fields=uuid-last_name_or_title-first_name-url-urlname-type&rpp=2")
{'items': [['60183d70-a998-11e1-afa6-0800200c9a66',
            'Sample Tag',
            None,
            'https://api.metropublisher.com/123/tags/60183d70-a998-11e1-afa6-0800200c9a66',
            'sample_tag',
            'default'],
           ['7fbbe910-a998-11e1-afa6-0800200c9a66',
            'Doe',
            'Jane',
            'https://api.metropublisher.com/123/tags/7fbbe910-a998-11e1-afa6-0800200c9a66',
            'jane_doe',
            'person']]}

Parameters

page:

The page number to retrieve.

optional

Default: 1

Values must not be lower than 1

rpp:

The number of results per page.

optional

Default: 20

Values must not be lower than 1 or higher than 100

state:

optional

Default: 'approved' if the user is a public user else None.

Values must be any of the following

internal:

Only internal tags

Access is restricted to users with these roles:

• super

approved:

Only approved tags

provisional:

Only provisional tags

Access is restricted to users with these roles:

• super

fields:

A dash-separated list of fields to return.

optional

Default: ['url']

Example value: 'category-uuid'

Every element of the list must be any of the following

first_name:The first name if the tag is a "person", or None if the tag is a "default" tag. last_name_or_title:The last name if the tag is a "person", or the tag title if the tag is a "default" tag. title:The diplay title of the tag type:The tag type url:URL to the tag urlname:The urlname uuid:The UUID of the tag

order:

A dash-separated list of orderings to apply

optional

Default: []

Example value: 'first_name-urlname.desc'

Every element of the list must be any of the following

first_name:Sort by first name (applies to "person" tag only) ascending first_name.asc:Sort by first name (applies to "person" tag only) ascending first_name.desc:Sort by first name (applies to "person" tag only) descending last_name_or_title:Sort by last name / title ascending last_name_or_title.asc:Sort by last name / title ascending last_name_or_title.desc:Sort by last name / title descending title:Sort by title ascending title.asc:Sort by title ascending title.desc:Sort by title descending urlname:Sort by urlname ascending urlname.asc:Sort by urlname ascending urlname.desc:Sort by urlname descending uuid:Sort by uuid ascending uuid.asc:Sort by uuid ascending uuid.desc:Sort by uuid descending

type:

optional

Default: None

Values must be any of the following

person: default:

/{iid}/tags/{uuid}

GET

Additional Information

Roles:

• public_user

  Access is restricted to certain attributes of the tag.

• super

Retrieve one tag.

This resource returns information about one specific tag. The information it returns depends on the role of the API key. Some attributes are not publicly available.

See also Tagging.

Sample Call

>>> GET("/123/tags/7fbbe910-a998-11e1-afa6-0800200c9a66")
{'content': '<p>This is descriptive text for a tag. ...</p>',
 'created': '2010-12-02T20:49:46.815676',
 'description': 'This is descriptive text for a tag. ... ',
 'email': None,
 'fb_username': None,
 'feature_image_url': 'https://api.metropublisher.com/123/files/1e0cf561-ee6b-3872-afa7-704b0979e11a',
 'first_name': 'Jane',
 'instagram_username': None,
 'last_name_or_title': 'Doe',
 'linkedin_url': None,
 'modified': '2010-12-02T20:49:46.815676',
 'objectcount': 3,
 'state': 'approved',
 'synonyms': None,
 'title': 'Jane Doe',
 'twitter_username': None,
 'type': 'person',
 'url': 'https://api.metropublisher.com/123/tags/7fbbe910-a998-11e1-afa6-0800200c9a66',
 'urlname': 'jane_doe',
 'uuid': '7fbbe910-a998-11e1-afa6-0800200c9a66',
 'website': None}

Return Value

content:

Longer description of the tag.

created:

The creation date/time of the tag.

Access is restricted to users with these roles:

• super

description:

Short description of the tag.

feature_image_url:

URL of the tag's feature image.

first_name:

The first name of a 'person' tag.

last_name_or_title:

The last name ('person' tag) or title ('default' tag) of the tag.

modified:

The last modification date/time of the tag.

Access is restricted to users with these roles:

• super

objectcount:

The number of objects tagged with this tag.

Access is restricted to users with these roles:

• super

state:

The tag state, i.e. 'provisional', 'internal' or 'approved'

synonyms:

The tag synonyms.

title:

The display title of the tag. If this is a 'person' tag, the display title will consist of the first (if it exists) and the last name.

type:

The tag type, either 'default' or 'person'.

url:

The URL to the tag.

urlname:

see urlname

uuid:

The UUID of the tag.

Additional return values for type: person

email:The person's email address. fb_username:The person's Facebook username. instagram_username:The person's Instagram username. linkedin_url:The person's LinkedIN url. twitter_username:The person's Twitter username. website:The person's website.

PUT

Additional Information

Roles:

• super

Create/update a tag.

Sending data to this resource does one of two things:

• creates a new tag if no tag with the given UUID was found, or
• updates the tag with the given UUID.

See also Tagging.

Sample Call

>>> PUT("/123/tags/12345678-1234-1234-1234-123456789abc",
...            {"urlname": "tag-a",
...             "title": "Tag A",
...             "category": "subject",
...             "created": "2000-01-01T10:00:00",
...             "modified": "2000-01-01T10:00:00",
...             "feature_imgage_uuid": "4f305f88-27de-39f1-9e08-790cc30b1454"})
{'url': 'https://api.metropublisher.com/123/tags/12345678-1234-1234-1234-123456789abc'}

Parameters

urlname:

see urlname

required

Example value: "edwin-e-aldrin-jr"

Values must obey all the conditions

• match the following regular expression:

  ^[^/@+][^/]*$

  Info: may not start with either @ or + and may not contain /.

• be unique

last_name_or_title:

The tag title if type=='default' or last name if type=='person'.

optional

Example value: "Aldrin, Jr."

first_name:

The first name of a 'person' tag.

optional

Default: None

Example value: "Edwin E."

only allowed if type=='person'

description:

A short description of the tag.

optional

Default: None

Values must not be longer than 250

state:

optional

Default: 'provisional'

Values must be any of the following

approved:

This tag is approved and will appear on the public site.

internal:

This tag is an internal tag and will not be visible on the public site.

provisional:

This tag is provisional and pending approval. It will not be visible on the public site.

type:

optional

Example value: "person"

Values must be any of the following

person:

A person tag. May have a first_name.

default:

A non-person tag. Tag does not have a first_name.

synonyms:

optional

Default: None

Example value: "edwin aldrin buzz"

content:

see HTML-XML

optional

Default: None

Example value: "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.<p>"

Values must obey all the conditions

• Value must not contain unicode characters x00-x08 or x0b-x1f

• XML-compliant HTML, see HTML-XML for restrictions on HTML tags

feature_image_uuid:

UUID of a linked image

optional

Default: None

Example value: '123456578-1234-1234-1234-123456789abc'

Values must obey all the conditions

• be existing image UUID

• be UUID or None

created:

The creation date/time in ISO 8601 format. See Dates and Times.

optional

Default: <current timestamp>

Example value: '2012-01-01T11:30:45'

Values must restricted to users with these roles:

• super

modified:

The date/time of last modification in ISO 8601 format. See Dates and Times.

optional

Default: <current timestamp>

Example value: '2012-01-01T11:30:45'

Values must restricted to users with these roles:

• super

Additional parameters for type: person

email:

The person's email address.

optional

Default: None

Values must obey all the conditions

• must not be used if tag is not a person

• match the following regular expression:

  ^[A-Za-z0-9!#$%&'*+/=?^_`{|}~.-]+@[A-Za-z0-9.-]+\.[A-Za-z]*$

  Info: The regular expression tries to verify the following pattern:

  <string of characters>@<string of characters>.<string of characters>

  The first string may contain a number of different special characters besides letters and numbers, such as an underscore (_) or asterisk (*), while the second string must contain only letters, numbers, dashes (-) and dots (.).

website:

The person's website.

optional

Default: None

Values must obey all the conditions

• must not be used if tag is not a person

• obey all the conditions

  • match the following regular expression:

    ^[A-Za-z][-A-Za-z0-9+\.]*:

    Info: The value should be a URL with a scheme. The regular expression does a simple check to make sure the value starts with a letter, is followed by zero or more letters, numbers, or the plus-sign (+), minus-sign (-) or dot (.), and then a colon (:).

  • Value must be more than just the URL scheme (i.e. more than just 'http://').

twitter_username:

The person's Twitter username.

optional

Default: None

Values must obey all the conditions

• must not be used if tag is not a person

• must start with @

• must be no longer than 15 characters

• can only contain alphanumeric characters (letters A-Z, numbers 0-9) and underscores

fb_username:

The person's Facebook username.

optional

Default: None

Values must obey all the conditions

• must not be used if tag is not a person

• must be at least 5 characters

• can only contain alphanumeric characters (letters A-Z, numbers 0-9) and dots

instagram_username:

The person's Instagram username.

optional

Default: None

Values must obey all the conditions

• must not be used if tag is not a person

• cannot be longer than 30 characters

• must start with an alphanumeric character or an underscore

• can only contain alphanumeric characters (letters A-Z, numbers 0-9), underscores and dots

• must not end with a dot

linkedin_url:

The person's LinkedIN URL.

optional

Default: None

Values must obey all the conditions

• must not be used if tag is not a person

• obey all the conditions

  • match the following regular expression:

    ^[A-Za-z][-A-Za-z0-9+\.]*:

    Info: The value should be a URL with a scheme. The regular expression does a simple check to make sure the value starts with a letter, is followed by zero or more letters, numbers, or the plus-sign (+), minus-sign (-) or dot (.), and then a colon (:).

  • Value must be more than just the URL scheme (i.e. more than just 'http://').

• match the following regular expression:

  ^https?://((www|\w\w)\.)?linkedin.com/

  Info: The regular expression does a simple check to verify the following pattern:

  <http or https>://<www or country code>.linkedin.com/

/{iid}/tags/{uuid}

PATCH

Additional Information

Roles:

• super

Update specific attributes of a tag.

Sample Call

>>> GET("/123/tags/7fbbe910-a998-11e1-afa6-0800200c9a66")
{'content': '<p>This is descriptive text for a tag. ...</p>',
 'created': '2010-12-02T20:49:46.815676',
 'description': 'This is descriptive text for a tag. ... ',
 'email': None,
 'fb_username': None,
 'feature_image_url': None,
 'first_name': 'Jane',
 'instagram_username': None,
 'last_name_or_title': 'Doe',
 'linkedin_url': None,
 'modified': '2010-12-02T20:49:46.815676',
 'objectcount': 3,
 'state': 'approved',
 'synonyms': None,
 'title': 'Jane Doe',
 'twitter_username': None,
 'type': 'person',
 'url': 'https://api.metropublisher.com/123/tags/7fbbe910-a998-11e1-afa6-0800200c9a66',
 'urlname': 'jane_doe',
 'uuid': '7fbbe910-a998-11e1-afa6-0800200c9a66',
 'website': None}

>>> PATCH("/123/tags/7fbbe910-a998-11e1-afa6-0800200c9a66",
...            {'first_name': 'Jane T.',
...             'urlname': 'jane_t_doe',
...             'email': 'jane@doe.com',
...             'twitter_username': '@janedoe',
...             'instagram_username': 'janedoe',
...             'fb_username': 'janedoe',
...             'website': 'https://www.janedoe.com',
...             'linkedin_url': 'https://www.linkedin.com/in/1234'})
{'url': 'https://api.metropublisher.com/123/tags/7fbbe910-a998-11e1-afa6-0800200c9a66',
 'uuid': '7fbbe910-a998-11e1-afa6-0800200c9a66'}

>>> GET("/123/tags/7fbbe910-a998-11e1-afa6-0800200c9a66")
{'content': '<p>This is descriptive text for a tag. ...</p>',
 'created': '2010-12-02T20:49:46.815676',
 'description': 'This is descriptive text for a tag. ... ',
 'email': 'jane@doe.com',
 'fb_username': 'janedoe',
 'feature_image_url': None,
 'first_name': 'Jane T.',
 'instagram_username': 'janedoe',
 'last_name_or_title': 'Doe',
 'linkedin_url': 'https://www.linkedin.com/in/1234',
 'modified': '2010-12-02T20:49:46.815676',
 'objectcount': 3,
 'state': 'approved',
 'synonyms': None,
 'title': 'Jane T. Doe',
 'twitter_username': '@janedoe',
 'type': 'person',
 'url': 'https://api.metropublisher.com/123/tags/7fbbe910-a998-11e1-afa6-0800200c9a66',
 'urlname': 'jane_t_doe',
 'uuid': '7fbbe910-a998-11e1-afa6-0800200c9a66',
 'website': 'https://www.janedoe.com'}

Parameters

urlname:

see urlname

optional

Example value: "edwin-e-aldrin-jr"

Values must match the following regular expression:

^[^/@+][^/]*$

Info: may not start with either @ or + and may not contain /.

last_name_or_title:

The tag title if type=='default' or last name if type=='person'.

optional

Example value: "Aldrin, Jr."

first_name:

The first name of a 'person' tag.

optional

Example value: "Edwin E."

only allowed if type=='person'

description:

A short description of the tag.

optional

Values must not be longer than 250

state:

optional

Values must be any of the following

approved:

This tag is approved and will appear on the public site.

internal:

This tag is an internal tag and will not be visible on the public site.

provisional:

This tag is provisional and pending approval. It will not be visible on the public site.

type:

optional

Example value: "person"

Values must be any of the following

person:

A person tag. May have a first_name.

default:

A non-person tag. Tag does not have a first_name.

synonyms:

optional

Example value: "edwin aldrin buzz"

content:

see HTML-XML

optional

Example value: "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.<p>"

Values must obey all the conditions

• Value must not contain unicode characters x00-x08 or x0b-x1f

• XML-compliant HTML, see HTML-XML for restrictions on HTML tags

feature_image_uuid:

UUID of a linked image

optional

Example value: '123456578-1234-1234-1234-123456789abc'

Values must obey all the conditions

• be existing image UUID

• be UUID or None

created:

The creation date/time in ISO 8601 format. See Dates and Times.

optional

Example value: '2012-01-01T11:30:45'

Values must restricted to users with these roles:

• super

modified:

The date/time of last modification in ISO 8601 format. See Dates and Times.

optional

Example value: '2012-01-01T11:30:45'

Values must restricted to users with these roles:

• super

Additional parameters for type: person

email:

The person's email address.

optional

Values must obey all the conditions

• must not be used if tag is not a person

• match the following regular expression:

  ^[A-Za-z0-9!#$%&'*+/=?^_`{|}~.-]+@[A-Za-z0-9.-]+\.[A-Za-z]*$

  Info: The regular expression tries to verify the following pattern:

  <string of characters>@<string of characters>.<string of characters>

  The first string may contain a number of different special characters besides letters and numbers, such as an underscore (_) or asterisk (*), while the second string must contain only letters, numbers, dashes (-) and dots (.).

website:

The person's website.

optional

Values must obey all the conditions

• must not be used if tag is not a person

• obey all the conditions

  • match the following regular expression:

    ^[A-Za-z][-A-Za-z0-9+\.]*:

    Info: The value should be a URL with a scheme. The regular expression does a simple check to make sure the value starts with a letter, is followed by zero or more letters, numbers, or the plus-sign (+), minus-sign (-) or dot (.), and then a colon (:).

  • Value must be more than just the URL scheme (i.e. more than just 'http://').

twitter_username:

The person's Twitter username.

optional

Values must obey all the conditions

• must not be used if tag is not a person

• must start with @

• must be no longer than 15 characters

• can only contain alphanumeric characters (letters A-Z, numbers 0-9) and underscores

fb_username:

The person's Facebook username.

optional

Values must obey all the conditions

• must not be used if tag is not a person

• must be at least 5 characters

• can only contain alphanumeric characters (letters A-Z, numbers 0-9) and dots

instagram_username:

The person's Instagram username.

optional

Values must obey all the conditions

• must not be used if tag is not a person

• cannot be longer than 30 characters

• must start with an alphanumeric character or an underscore

• can only contain alphanumeric characters (letters A-Z, numbers 0-9), underscores and dots

• must not end with a dot

linkedin_url:

The person's LinkedIN URL.

optional

Values must obey all the conditions

• must not be used if tag is not a person

• obey all the conditions

  • match the following regular expression:

    ^[A-Za-z][-A-Za-z0-9+\.]*:

    Info: The value should be a URL with a scheme. The regular expression does a simple check to make sure the value starts with a letter, is followed by zero or more letters, numbers, or the plus-sign (+), minus-sign (-) or dot (.), and then a colon (:).

  • Value must be more than just the URL scheme (i.e. more than just 'http://').

• match the following regular expression:

  ^https?://((www|\w\w)\.)?linkedin.com/

  Info: The regular expression does a simple check to verify the following pattern:

  <http or https>://<www or country code>.linkedin.com/

/{iid}/tags/{uuid}/categories

GET

Additional Information

Roles:

• public_user

  Access is restricted to certain attributes of the tag.

• super

Retrieve a batched collection of the categories of a specific tag.

This resource returns a batched list of tag categories.

Sample Call

>>> GET("/123/tags/60183d70-a998-11e1-afa6-0800200c9a66/categories?fields=uuid-title-url&order=title")
{'items': [['22222222-2222-2222-2222-222222222222',
            'Another Category',
            'https://api.metropublisher.com/123/tags/categories/22222222-2222-2222-2222-222222222222'],
           ['11111111-1111-1111-1111-111111111111',
            'Category 1',
            'https://api.metropublisher.com/123/tags/categories/11111111-1111-1111-1111-111111111111']]}

Parameters

page:

The page number to retrieve.

optional

Default: 1

Values must not be lower than 1

rpp:

The number of results per page.

optional

Default: 20

Values must not be lower than 1 or higher than 100

fields:

A dash-separated list of fields to return.

optional

Default: ['url']

Example value: 'title-uuid'

Every element of the list must be any of the following

title:The category title url:URL to the category uuid:The UUID of the category

order:

A dash-separated list of orderings to apply

optional

Default: []

Example value: 'title'

Every element of the list must be any of the following

title:Sort by title ascending title.asc:Sort by title ascending title.desc:Sort by title descending

Tagging Objects

/{iid}/tags/{uuid}/all

GET

Additional Information

Roles:

• public_user

  Access is restricted to certain attributes of the tag.

• super

Retrieve a batched list of information about relationships between various objects and a specific tag.

See also Tagging and tag predicates.

Sample Call

>>> GET("/123/tags/7fbbe910-a998-11e1-afa6-0800200c9a66/all?fields=created-url-object_url-predicate&order=created.desc")
{'items': [['2010-12-05T15:52:31.829274',
            'https://api.metropublisher.com/123/tags/7fbbe910-a998-11e1-afa6-0800200c9a66/authored/a33b5997-00ca-11e0-b096-001ec21bff9e',
            'https://api.metropublisher.com/123/content/a33b5997-00ca-11e0-b096-001ec21bff9e',
            'authored'],
           ['2010-12-05T10:42:28.784406',
            'https://api.metropublisher.com/123/tags/7fbbe910-a998-11e1-afa6-0800200c9a66/describes/2e06fa2e-008e-11e0-9a76-001ec21bff9e',
            'https://api.metropublisher.com/123/content/2e06fa2e-008e-11e0-9a76-001ec21bff9e',
            'describes'],
           ['2010-10-05T08:42:28.784406',
            'https://api.metropublisher.com/123/tags/7fbbe910-a998-11e1-afa6-0800200c9a66/is_brand_of_reviewed/12345678-1234-1234-1234-123456789abc',
            'https://api.metropublisher.com/123/content/12345678-1234-1234-1234-123456789abc',
            'is_brand_of_reviewed']]}

Parameters

page:

The page number to retrieve.

optional

Default: 1

Values must not be lower than 1

rpp:

The number of results per page.

optional

Default: 20

Values must not be lower than 1 or higher than 100

fields:

A dash-separated list of fields to return.

optional

Default: ['url']

Example value: 'created-url'

Every element of the list must be any of the following

created:Creation date/time of the tagging relationship. object_url:The URL of the tagged object. object_uuid:The UUID of the tagged object. predicate:The predicate of the tagging relationship. url:URL to the tagging relationship.

order:

A dash-separated list of orderings to apply

optional

Default: []

Example value: 'created'

Every element of the list must be any of the following

created:Ascending created.asc:Ascending created.desc:Descending

/{iid}/tags/{uuid}/{predicate}

GET

Additional Information

Roles:

• public_user

  Access is restricted to certain attributes of the tag.

• super

Retrieve a batched list of information about relationships between various objects and a specific tag filtered by 'predicate'.

See also Tagging and tag predicates.

Sample Call

>>> GET("/123/tags/7fbbe910-a998-11e1-afa6-0800200c9a66/authored?fields=created-url-object_url-predicate&order=created.desc&rpp=2")
{'items': [['2010-12-05T15:52:31.829274',
            'https://api.metropublisher.com/123/tags/7fbbe910-a998-11e1-afa6-0800200c9a66/authored/a33b5997-00ca-11e0-b096-001ec21bff9e',
            'https://api.metropublisher.com/123/content/a33b5997-00ca-11e0-b096-001ec21bff9e',
            'authored'],
           ['2010-12-05T08:42:28.784406',
            'https://api.metropublisher.com/123/tags/7fbbe910-a998-11e1-afa6-0800200c9a66/authored/2e06fa2e-008e-11e0-9a76-001ec21bff9e',
            'https://api.metropublisher.com/123/content/2e06fa2e-008e-11e0-9a76-001ec21bff9e',
            'authored']],
 'next': 'fields=created-url-object_url-predicate&order=created.desc&page=2&rpp=2'}

Parameters

page:

The page number to retrieve.

optional

Default: 1

Values must not be lower than 1

rpp:

The number of results per page.

optional

Default: 20

Values must not be lower than 1 or higher than 100

fields:

A dash-separated list of fields to return.

optional

Default: ['url']

Example value: 'created-url'

Every element of the list must be any of the following

created:Creation date/time of the tagging relationship. object_url:The URL of the tagged object. object_uuid:The UUID of the tagged object. predicate:The predicate of the tagging relationship. url:URL to the tagging relationship.

order:

A dash-separated list of orderings to apply

optional

Default: []

Example value: 'created'

Every element of the list must be any of the following

created:Ascending created.asc:Ascending created.desc:Descending

/{iid}/tags/{uuid}/{predicate}/{object_uuid}

DELETE

Additional Information

Roles:

• super

Removes a tag from an object.

See also Tagging and tag predicates.

Sample Call

>>> DELETE("/123/tags/60183d70-a998-11e1-afa6-0800200c9a66/describes/799d6c73-fe75-11df-837b-001ec21bff9e")
{'msg': 'deleted'}

GET

Additional Information

Roles:

• public_user

  Access is restricted depending on the status of the tag and the tagged object.

• super

Retrieve one tag connection.

This resource returns information about one specific tag connection.

See also Tagging and tag predicates.

Sample Call

>>> GET("/123/tags/7fbbe910-a998-11e1-afa6-0800200c9a66/authored/a33b5997-00ca-11e0-b096-001ec21bff9e")
{'created': '2010-12-05T15:52:31.829274',
 'object_url': 'https://api.metropublisher.com/123/content/a33b5997-00ca-11e0-b096-001ec21bff9e',
 'object_uuid': 'a33b5997-00ca-11e0-b096-001ec21bff9e',
 'predicate': 'authored',
 'tag_url': 'https://api.metropublisher.com/123/tags/7fbbe910-a998-11e1-afa6-0800200c9a66',
 'tag_uuid': '7fbbe910-a998-11e1-afa6-0800200c9a66'}

Return Value

created:

Access is restricted to users with these roles:

• super

object_url:

The URL to the tagged object

object_uuid:

The UUID of the tagged object

predicate:

The predicate defining the relationship between 'tag' and 'object'.

tag_url:

The URL to the tag

tag_uuid:

The UUID of the tag

PUT

Additional Information

Roles:

• super

Create/update a tag connection.

Sending data to this resource does one of two things:

• tags the object with the given UUID if it isn't yet tagged, or
• updates the tag connection.

See also Tagging and tag predicates.

Sample Call

>>> PUT("/123/tags/60183d70-a998-11e1-afa6-0800200c9a66/describes/799d6c73-fe75-11df-837b-001ec21bff9e",
...                   {"created": "2000-01-01T10:00:00"})
{'url': 'https://api.metropublisher.com/123/tags/60183d70-a998-11e1-afa6-0800200c9a66/describes/799d6c73-fe75-11df-837b-001ec21bff9e'}

Parameters

created:

The creation date/time in ISO 8601 format. See Dates and Times.

optional

Default: <current timestamp>

Example value: '2012-01-01T11:30:45'

Values must restricted to users with these roles:

• super

Tag Path History

/{iid}/tags/{uuid}/path_history

GET

Additional Information

Roles:

• public_user

  Access is restricted to certain attributes of the tag.

• super

Get the path history of a tag.

Sample Call

>>> GET("/123/tags/799d6c73-fe75-11df-837b-001ec21bff9e/path_history")
{'items': [{'path': '/old-tag/'},
           {'path': '/index.php?t_id=123'},
           {'path': '/old-tag/index.php'}]}

/{iid}/tags/{uuid}/path_history

POST

Additional Information

Roles:

• super

Create new path history entry for the tag.

This resource creates a new path history entry and adds it to the existing list of path history entries for the tag.

Sample Call

Add a new path history entry:

>>> POST("/123/tags/799d6c73-fe75-11df-837b-001ec21bff9e/path_history",
...                      {"path": "/old-tag/index.html"})
{'msg': 'path added'}

Parameters

path:

The unquoted, utf-8-decoded old path to the tag.

required

Example value: "/old-tag/index.html"

must be an absolute path

/{iid}/tags/{uuid}/path_history

PUT

Additional Information

Roles:

• super

Create/update the path_history of the tag.

This resource creates/replaces the path_history of the tag.

Sample Call

Set the path history of a tag:

>>> PUT("/123/tags/799d6c73-fe75-11df-837b-001ec21bff9e/path_history",
...            {'items': [{"path": "/tag-123"},
...                       {"path": "/old-tag/index.html"}]})
{'msg': 'path history updated'}

Remove a tag's path history:

>>> PUT("/123/tags/799d6c73-fe75-11df-837b-001ec21bff9e/path_history",
...            {'items': []})
{'msg': 'path history updated'}

Parameters

items:

required

Every element of the list is a dictionary, each consisting of the following fields:

path:

The unquoted, utf-8-decoded old path to the tag.

required

Example value: "/old-tag/index.html"

must be an absolute path