Settings API: move to primary document format

[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 Settings JSON object format laid out in #2350.

---

The equivalent task for Posts (#2580) has been done with the PR #2596, however the task for settings is SIGNIFICANTLY different.

At present, the settings API responses are completely different to all of our other APIs. The response when requesting a single setting looks like:

{
    key: "title",
    value: "Ghost"
}

And when requesting a collection, you get a response like:

{
    title: "Ghost",
    description: "Just a blogging platform.",
    email: "john.blogs@myblog.com"
}

The aim of this task is to make these responses consistent with all of our other JSON-API-esque responses. That is, return the full object (with anything sensitive omitted), with a plural-form named key:

{
    settings: [{...}, {...}]
}

In terms of the API itself, this is going to involve ripping out a LOT of code, but the settings API is the most heavily used, and so will require a lot of work updating the various places where it is called.

The settings API is also the only are which has an in-memory cache, which should also be transformed to work with the new format.

The request format should also be changed, meaning the client side models and code for saving settings will need adjusting.

The weird hacks for adding availableThemes and availableApps can remain for the time being, until the work on the individual Apps and Themes APIs are completed.

Finally, all the tests should be updated, and coverage should be added where it is missing.

It would also be appreciated if you would add docs to this (#2125) as you go. Thanks 👍

[jgable]

Question from over at #2061

• Currently the browse implementation returns by type, should it be changed to match the rest of the API where it will return all?
• If the browse() request is not internal, should this throw an error since it will return core settings?

[ErisDS]

Sorry for the confusion here, but I think these questions are very specifically about #2061. This issue should change the format, not what the API does.

[ErisDS]

One thing worth noting - I guess if the request is for a type, the type ought to be returned as E.g. meta.aspect.type=core as discussed in #2620.

Although I want to change the name of aspect... filters is probably best.

{
    settings: [{...}, {...}],
    meta: {
        filters: { type: core }
    }
}

[jgable]

I worked through this yesterday and am just finishing up getting the tests to run now. The admin/settings pages look like they are working and all responses are now in the { settings: [{...}, {...}] }

[ErisDS]

👍