Use short CURIEs instead of full URIs

[rmccue]

Originally ​https://github.com/WP-API/WP-API/issues/1488

One small annoyance in the API right now is that link relations are full URIs. In JavaScript, this means that while you have _links.self and _links.author, you have to do _links["http://v2.wp-api.org/term"]. This is a bit ugly, and can be confusing.

We should instead switch to [CURIEs](​https://en.wikipedia.org/wiki/CURIE). These are an abbreviated form of the full URI that's easier to work with, but can be expanded out to the full URI if needed. They look like this:

{
    "_links": {
        "curies": [
            {
                "name": "wp",
                "href": "http://v2.wp-api.org/{rel}",
                "templated": true
            }
        ],

        "wp:term": [
            {
                "taxonomy": "category",
                "href": "..."
            },
            {
                "taxonomy": "post_tag",
                "href": "..."
            }
        ]
    }
}

[danielbachhuber]

#35086 was marked as a duplicate.

[joehoyle]

Added initial patch that outputs the correct response data, need to upload some tests here too.

[joehoyle]

Added new patch that supports any type of pattern in the CURIE href attribute such as http://docs.something.com/{rel}.html

[joehoyle]

@rmccue could you take a look at my updated patch for feedsback?

[rmccue]

Couple of notes on the patch:

• Singular form should be "CURIE", not "CURI"
• Should return/continue early if possible

Otherwise, looking good.

[joehoyle]

@rmccue new patch with tests, returning early, typo fixes and also the ability to filter the CURIEs so plugins etc can add their own if they so wish.

[rmccue]

In 36533:

REST API: Add support for CURIEs.

CURIEs are Compact URIs, which provide a more usable way to use
custom relations in the API. The wp CURIE is registered by default
for https://api.w.org/ URI relations.

Fixes #34729.
Props joehoyle.

[rachelbaker]

In 36593:

Docs: Add missing @since and @access tags to get_curies method and filter from r36533

See #34729, #32246.

[danielbachhuber]

The regex doesn't handle https://api.w.org/post_type

​https://github.com/WP-API/WP-API/commit/ede21aa1ccea94ff8e4f8c30b23cae741e9cf776 is one approach, but I'm not sure if https://api.w.org/?foo would be considered a valid curie and need to be handled too

[rmccue]

Replying to danielbachhuber:

The regex doesn't handle https://api.w.org/post_type

​https://github.com/WP-API/WP-API/commit/ede21aa1ccea94ff8e4f8c30b23cae741e9cf776 is one approach, but I'm not sure if https://api.w.org/?foo would be considered a valid curie and need to be handled too

This should just be .+ I think; https://example.com/a/b?c#d is valid. We should also be anchoring to the start/end of the string though, I think.

[joehoyle]

Ok, I took another stab at the approach. I think the above is a red herring (though I think we should laxen the regex either way.)

Most of the issue stem from the fact that we generate the curies at the server level, this means things like collection resources get curies applied at a difference stage to top level ones, which screws up our unit tests.

Instead, I've taken the approach of curies being abstracted in the WP_REST_Response class via get_links, so virtually any "exposed" link, even internally will be "curie-ified". This makes things a lot simpler, as you don't need to know whether a response has come in via the Server's serve_request method, or via dispatch.

For backwards compatibility, this might present a challenge however, because we can't shim the get_links method of the WP_REST_Response class for WordPress 4.4. That might not be a huge issue, and it's possible we could fudge it somehow at the server level (similar to what @danielbachhuber tried to do in ​https://github.com/WP-API/WP-API/pull/2295.

_Ideally_ we could subclass WP_REST_Response in the plugin for backwards compat, but we don't support filtering the Response class so that wouldn't be possible I think.

Looking to get this wrapped up today, will chat with @rmccue when he is online.

[joehoyle]

Also, while we are changing this, it might be a good idea to add a filter to the get_links in the WP_REST_Response class so we can provide future flexibility.

[DrewAPicture]

In 37015:

Docs: Use a third-person singular verb in the DocBlock summary for WP_REST_Response::get_curies(), introduced in [36533].

Also adds a missing return description.

See #34729. See #35986.

[joehoyle]

Added patch with maximum backwards compatibility. This makes the method easier to Shim in the rest api and also provides a way to get the non-compact links just as before. If needed we could also add the ability for the client to specify if it wants curies or not. Also, if anything was internally using get_response_links that method is still now available, unchanged.

[joehoyle]

In 37041:

REST API: Provide better method for generating CURIEs

In [36533] CURIEs were added to the API responses for the link relation URIs, this makes
it a lot easier for clients to look up links by relation. That patch was functional, but
broke on edge cases such as embedded responses and collection items with links in the items.

This patch instead takes a less obtrusive approach by creating a new get_compact_response_links
to compliment get_response_links making both old and new functionality available.

Also the regex for curie relations has been relaxed to .+ as rel names can have any uri-valid charector in it.

Fixes #34729.

[sanchothefat]

Patch to make sure CURIEs are added to items in collections too

[sanchothefat]

Make links array order stays the same and curies output not processed as part of the data

[sanchothefat]

Items in a collection don't get CURIEs added, only the top level response object or embedded objects get processed this way.

Patch 7 works but there's definitely a neater way it could be done, I wasn't sure if there was a specific reason for handling it in the server rather than the response.

I'll add to the tests too.

[SergeyBiryukov]

Replying to sanchothefat:

Items in a collection don't get CURIEs added, only the top level response object or embedded objects get processed this way.

This ticket was closed on a completed milestone, could you create a new one? Thanks!