Post API: Returning additional objects

[ErisDS]

This issue is a result of the API format discussion in #2362, and is part of a larger project to move our API towards the JSON-API format which is documented in the Epic: #2124. This is one step in the journey towards achieving the Post JSON object format laid out in #2347, and is related to #2604.

---

The posts API is currently the most functional API. It is the only API which handles proper browse requests with pagination and other options. This is logical and will continue to be built upon.
One of the extra features in the post browse request, is the ability to return all the posts which have a particular tag. This will soon be expanded to also allow you to request all the posts which have a particular user. When making these requests, the object queried for (tag or user) is also included in the response.

Currently this object is returned as a top level property called aspect:

{
    posts: [{...}, {...}],
    aspect: {
        tag: {...}
    }, 
    limit: #,
    ...
}

We want to move this aspect object into the meta object:

{
    posts: [{...}, {...}],
    meta: {
        pagination: {...},
        aspect: {...}
    }
}

We also want to consider whether aspect is the right name for this object, or if there is a better name for it... any suggestions?

[hswolff]

We could take a cue from JSONAPI and include it under the top level linked key.

{
    posts: [{...}, {...}],
    meta: {
        pagination: {...},
    },
    linked: {
         tag: {...},
         user: {...},
    }
}

[sebgie]

meta is according to JSON API the suggested place to put meta-information about a resource. As aspect is some kind of meta-information it should go there.

More questions:

• What happens if a tag is not found? At the moment an empty posts result with an invalid tag object as aspect is returned. I think that aspect is empty in that case?

{
    posts: [ ],
    meta: {
        ...
    },
    aspect: {
        tag: {
            slug: "getting"
        }
    }
}

• Is it possible to have more than one aspect? If yes returning aspects: [{...}] as array would be good.

[ErisDS]

Trying desperately to thing of a better name than aspect / aspects. subject? It is the subject of the query. query? queryObject ?

Plural would probably be a good idea though - I imagine one day having posts requested for a particular tag by a particular author. Then there is text search...

[sebgie]

I think that what is implemented right now is a filter that exactly matches one tag object and then returns all posts that are related with the tag. Maybe filters or filterObjects would be a suitable name?

I don't think that this issue is related to search since a search term is never represented by an object available in our database?

[ErisDS]

filters 👍