Initial Settings Endpoint

[joehoyle]

Merged in from https://github.com/WP-API/wp-api-site-endpoints. The
bulk of this comes from
WP-API/wp-api-site-endpoints#13

[joehoyle]

I've been chatting about this with @rmccue and we are considering making the response object key => { value: "A value", group: "A group", ... } to allow for more things to be specific about a setting.

This would be a lot better for forward compatibility as any other fields for a specific setting could be added to the object.

[westonruter]

Does this mean that you could then store null values? Like sending {"blogname": null} can mean delete vs storing an actual null could be {"blogname": {"value": null}}. Normal updates would then look like {"blogname": {"value": "Example"}}.

[westonruter]

I suppose this would be in theory only as currently null gets stored as an empty string.

[joehoyle]

@westonruter no, you can't store a value as null - doing so essentially causes a delete_option on that option value, in which case the option is basically set back to it's default value.

This is only for the response format, not the storage, so this would not effect being (or rather not being) able to store null in an option.

[kadamwhite]

Discussed in slack during Oct 3 team meeting, decisions to be documented here by @joehoyle—tl;dr is that we are going to stick with key: 'value' (as opposed to key: { value: 'value' }) for now, and will attempt to expose group information via the schema.

[kadamwhite]

Additional slack discussion: I feel that having this resource be publicly queryable, exposing obviously-public content like title, URL & description, and possibly posts_per_page, would be useful. I am 👎 on continuing to load up the root API index with arbitrary options when we have this new /settings resource available (esp. if any of these vary by site in multi-site: not sure how that works)

[joehoyle]

So we have a couple of things to sort out before merging this, but we are very close:

1. What do we do if a setting value in the database does not match the type used in register_setting, this becomes a problem when there is serialized data in the option value. Right now we are forcing this to be a null value in the rest api responses. The problem with this approach is sending that data back to the settings endpoint will cause a delete of that option value (as null in this case is essentially a delete operation).
2. Having support for object recursion and array types in the Schema would be very nice, allowing settings that are either objects or arrays. Though this doesn't need to be done for merge I think.
3. Currently reading all options is behind a manage_options cap check, we need to work out if we want to publicly expose option values for some settings. If we do this, we'd need a way in register_setting or via some kind of read_setting meta cap to work out what settings should be exposed publicly (or at specific permissions checks).

[rmccue]

So we have a couple of things to sort out before merging this, but we are very close:

We decided that these shouldn't block the PR merge, but do need to be fixed before final release. :)