Silverstone tags API

This API allows you to list and create tags in Silverstone.

Stories contain one or more tags which control where they appear on the news websites, or influence the way they are displayed.

In particular, business feature stories are treated differently from regular stories. These are tagged with bf-title-... tags. Each business feature has its own unique tag.

Overview

• API endpoint: https://silverstone.fairfaxregional.com.au/api/v2/tag/ (n.b.: trailing / is required)
• Authentication method: OAuth 2, client credentials grant type
• Access token URL: https://monza.fairfaxregional.com.au/o/token/
• API type: REST
• Response encoding: JSON

Authentication

Authenticate to the API using OAuth 2 using our Monza microservice. Your client ID and secret will be provided to you.

If you fail to authenticate, or provide invalid credentials, the API will respond with a 401 Unauthorized status code.

Creating tags

• Method: POST
• Request encoding: JSON

Important: Please note that once tags are created, they cannot be renamed or deleted.

Request

Supply the tag name in a JSON object.

The name must be lower-case, alphanumeric with hyphen-separated words. The name must start with a letter and must not end with a hyphen. These rules are enforced by the API.

For business feature tags, the format must be bf-title-....

POST /api/v2/tag/ HTTP/1.1
Content-Type: application/json

{
  "name":"example-tag"
}

Response

The created tag's name is included in the response. It may differ from the name you provided as the tag is converted to lowercase with the whitespace trimmed.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "name":"example-tag"
}

Errors

If you supply an invalid tag name, the response code is 400 Bad Request and the body is a JSON object listing the error(s).

Invalid tag names include: * Empty, missing, or whitespace-only name * Invalid format (e.g., not alphanumeric)

The JSON object contains keys for each field, with values being an array of error message strings.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "name": [
    "This field may not be blank."
  ]
}

Listing tags

• Method: GET

Tags are provided as a JSON array of strings. The response contains all tags in Silverstone.

Request

GET /api/v2/tag/ HTTP/1.1

Response

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

[
  "example-tag",
  "another-tag",
  "..."
]