WordPress.org

Make WordPress Core

Opened 2 years ago

Closed 20 months ago

Last modified 12 months ago

#34729 closed task (blessed) (fixed)

Use short CURIEs instead of full URIs

Reported by: rmccue Owned by: joehoyle
Milestone: 4.5 Priority: normal
Severity: normal Version:
Component: REST API Keywords: needs-patch
Focuses: Cc:

Description

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": "..."
            }
        ]
    }
}

Attachments (7)

34729.diff (2.0 KB) - added by joehoyle 23 months ago.
34729.2.diff (2.0 KB) - added by joehoyle 23 months ago.
34729.3.diff (3.6 KB) - added by joehoyle 22 months ago.
34729.4.diff (3.2 KB) - added by joehoyle 21 months ago.
34729.5.diff (2.9 KB) - added by joehoyle 20 months ago.
34729.6.diff (4.2 KB) - added by sanchothefat 16 months ago.
Patch to make sure CURIEs are added to items in collections too
34729.7.diff (4.5 KB) - added by sanchothefat 16 months ago.
Make links array order stays the same and curies output not processed as part of the data

Download all attachments as: .zip

Change History (41)

#1 @danielbachhuber
2 years ago

#35086 was marked as a duplicate.

#2 @danielbachhuber
2 years ago

  • Milestone changed from Awaiting Review to 4.5
  • Owner set to danielbachhuber
  • Status changed from new to assigned

#3 @joehoyle
23 months ago

  • Owner changed from danielbachhuber to joehoyle

@joehoyle
23 months ago

#4 @joehoyle
23 months ago

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

@joehoyle
23 months ago

#5 @joehoyle
23 months ago

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

This ticket was mentioned in Slack in #core-restapi by joehoyle. View the logs.


23 months ago

#7 @joehoyle
23 months ago

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

#8 @rmccue
23 months ago

Couple of notes on the patch:

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

Otherwise, looking good.

#9 @joehoyle
22 months ago

  • Keywords needs-unit-tests added

This ticket was mentioned in Slack in #core-restapi by jnylen. View the logs.


22 months ago

@joehoyle
22 months ago

#11 @joehoyle
22 months ago

  • Keywords has-patch 2nd-opinion added; needs-patch needs-unit-tests removed

#12 @joehoyle
22 months ago

  • Status changed from assigned to reviewing

@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.

This ticket was mentioned in Slack in #core-restapi by joehoyle. View the logs.


22 months ago

This ticket was mentioned in Slack in #core-restapi by rmccue. View the logs.


22 months ago

#15 @rmccue
22 months ago

  • Resolution set to fixed
  • Status changed from reviewing to closed

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.

#16 @rachelbaker
21 months ago

In 36593:

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

See #34729, #32246.

#17 follow-up: @danielbachhuber
21 months ago

  • Keywords needs-patch added; has-patch 2nd-opinion removed
  • Resolution fixed deleted
  • Status changed from closed to reopened

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 ticket was mentioned in Slack in #core by jorbin. View the logs.


21 months ago

#19 @jorbin
21 months ago

  • Type changed from enhancement to task (blessed)

#20 in reply to: ↑ 17 @rmccue
21 months ago

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.

This ticket was mentioned in Slack in #core by chriscct7. View the logs.


21 months ago

This ticket was mentioned in Slack in #core-restapi by joehoyle. View the logs.


21 months ago

#23 @joehoyle
21 months ago

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.

Last edited 21 months ago by joehoyle (previous) (diff)

#24 @joehoyle
21 months ago

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.

This ticket was mentioned in Slack in #core-restapi by joehoyle. View the logs.


21 months ago

This ticket was mentioned in Slack in #core by chriscct7. View the logs.


21 months ago

@joehoyle
21 months ago

#27 @DrewAPicture
21 months ago

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.

This ticket was mentioned in Slack in #core by mike. View the logs.


21 months ago

@joehoyle
20 months ago

#29 @joehoyle
20 months ago

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.

This ticket was mentioned in Slack in #core-restapi by joehoyle. View the logs.


20 months ago

#31 @joehoyle
20 months ago

  • Resolution set to fixed
  • Status changed from reopened to closed

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
16 months ago

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

@sanchothefat
16 months ago

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

#32 follow-up: @sanchothefat
16 months ago

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.

Last edited 16 months ago by sanchothefat (previous) (diff)

#33 in reply to: ↑ 32 @SergeyBiryukov
16 months ago

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!

This ticket was mentioned in Slack in #core-restapi by rachelbaker. View the logs.


12 months ago

Note: See TracTickets for help on using tickets.