Tag API Response

[sebgie]

The structure of our JSON/REST APIs are up for spring cleaning #2124. I have compiled what I think could be changed to improve consistency and readability for tags?

Single Tag

GET /ghost/api/v0.1/tags/1 - not implemented yet

JSON Object (v0.1)

{
    id: 1,
    uuid: "9c8d3aa0-205d-440c-a49c-412f3ca4bc62",
    name: "tag",
    slug: "tag-post",
    description: null,
    parent_id: null,
    meta_title: null,
    meta_description: null,
    created_at: "2014-03-06T14:04:22.495Z",
    created_by: 1,
    updated_at: "2014-03-06T14:04:22.495Z",
    updated_by: 1
}

New JSON Object:

• renamed parent_id to `parent and added as linked object.
• wrapped in an object that contains a settings key and holds an array (jsonapi.org/format - singular ressource)
• added links property (jsonapi.org/format - To-One Relationships)
• added linked property (jsonapi.org/format - Compound documents)
• Subject to change: created_by and updated_by could become expandable properties later (see Expanding JSON API Objects #2346).

{
    links: {
        tags.created_by: {
            href: "http://tbd.com",
            type: "users"
        },
        tags.updated_by: {
            href: "http://tbd.com",
            type: "users"
        },
        users.roles: {
            href: "http://tbd.com",
            type: "roles"
        },
        roles.permissions: {
            href: "http://tbd.com",
            type: "permissions"
        }
    },
    tags: [{
        id: 1,
        uuid: "9c8d3aa0-205d-440c-a49c-412f3ca4bc62",
        name: "tag",
        slug: "tag-post",
        description: null,
        meta_title: null,
        meta_description: null,
        created_at: "2014-03-06T14:04:22.495Z",
        updated_at: "2014-03-06T14:04:22.495Z",
        links: {
            parent: null,
            created_by: 1,
            updated_by: 1
        }
    ]},
    linked: {
        users: [
            {
                id: 1,
                uuid: '27771667-2134-4899-891a-551c22e3b815',
                name: 'Joe Bloggs',
                slug: 'joe-blogs',
                ...,
                links: {
                    roles: 1
                }
            }
        ],
        roles: [
            {
                id: 1,
                description: 'Administrators,
                name: 'Administrator',
                ...,
                links: {
                    permissions: [1]
                }
            }
        ],
        permissions: [
            {
                id: 1,
                name: 'Edit posts',
                ...,
            },
            {...}
        ]
    }
}

Tag Collection

GET /ghost/api/v0.1/tags/

JSON Object (v0.1)

[
    {...},
    {...}
]

New JSON Object:

• respond with an object and move the tags array into a tags property
• added linked property (jsonapi.org/format - Compound documents)
• added links property (jsonapi.org/format - Compound documents)

{
    links: {...},
    tags: [
        {...},
        {...},
    ],
    linked: {
        users: [
            {...}
        ],
        roles: [
            {...}
        ],
        permissions: [
            {...},
            {...}
        ]
    }
}

[ErisDS]

👍

[sebgie]

I updated the user responses to follow the JSON API format. See #2362.

[hswolff]

Should parent_id also be linked?

[sebgie]

Updated:
parent_id is renamed to parent and added as linked object. parent is not used or implemented at the moment.

@hswolff: 👍!

[ErisDS]

Another API response that's good to go

[ErisDS]

Single tag:

{ 
    tags: [{
        id: 1,
        uuid: "9c8d3aa0-205d-440c-a49c-412f3ca4bc62",
        name: "tag",
        slug: "tag-post",
        description: null,
        parent: {...}, (or null for now?)
        meta_title: null,
        meta_description: null,
        created_at: "2014-03-06T14:04:22.495Z",
        created_by: {...},
        updated_at: "2014-03-06T14:04:22.495Z",
        updated_by: {...}
    }]
}

Tag collection:

{
    tags: [{...}, {...}],
    meta: {
        ...
    }
}

Would need to be paginated but likely with a different default limit to posts? 15 is a weird limit for such a small thing as tags I think?