Collections are not compatible to HAL standard

[maennchen]

The HAL specification is quite clear on the definition of an HAL resource:

Its root object MUST be a Resource Object.

The current API does clearly violate the standard for all collections.

If an API complies with the standard, the root would be an object, which contains links to the elements and mostly also embeds them.

Problems because of the violation of the standard:

• The API is not consumable for standard HAL clients. If the API complies with the standard, no dedicated client libraries have to be written for wordpress. All HAL clients can be used instead.

Advantages by using the standard:

• Additional Information on the collection can be saved inside of the collection. This way things like totals, page counts etc. can be delivered easily. (No custom Headers, like they are used for X-WP-Total)
• Links for the next, previous, first and last page can be added to the collection. That way the client doesn't has to generate the url's himself.

[maennchen]

Link to RFC: ​https://tools.ietf.org/html/draft-kelly-json-hal-08#section-3

[jeremyzahner]

Agree on all points.

[rachelbaker]

Related issue filed in Github repo: ​https://github.com/WP-API/WP-API/issues/2560

[rmccue]

We intentionally deviated from the HAL specification here in favour of user ergonomics. It's a pain for regular clients to handle collections formatted in the HAL way, as it's not a simple add-on like with objects. This is annoying, but the reality that we have to deal with is that most clients aren't going to use a HAL parser.

The combination of extra headers with a list in our current approach uses HTTP's standard for linking (the Link header) along with per-item links, which strikes a reasonable compromise.

Marking this as wontfix, as it's a conscious decision not to follow the spec to the letter here.

[maennchen]

Ergonomics

That's exactly where I can't agree with you. An API is made to be consumed by a machine and not a user. If you want to write something, thats aesthetic to the eye, you should've gone with something like JSON-LD.

The ergonomics are far worse than if you were using the standard, because this way all libraries can't process the API.

The HAL standard is highly standardised, which allows generic clients to interact with any API. If you are not in fact planning to be HAL compliant, please do not label it as HAL compliant. (Which is sad, because HAL would've been a great choice to use.)

Documentation mentioning HAL

​http://v2.wp-api.org/extending/linking/

The linking system we use is based on HAL (Hypertext Application Language).

No, it is not based on the HAL standard, it may look similar, but it is not.

​http://v2.wp-api.org/changes-beta-1.html

Changed: Hypermedia links have changed from meta.links to _links to follow the HAL standard. In custom endpoints, you can either return _links in your data, or use WP_REST_Response->add_link

No, it does not follow the HAL standard, it may look similar, but it is not.

[netweb]

Moving reopened tickets without a milestone back to Awaiting Review for review

[joehoyle]

@maennchen I appreciate your response and follow up here, and recognise it's true that WordPress isn't following the full standard here. However, either way the ship has sailed on this - so to avoid having a ticket around forever that is not likely to change until maybe a new version of the REST API, I'm going to close this out.

[kadamwhite]

I have updated ​https://developer.wordpress.org/rest-api/linking-and-embedding/ to clarify that our mechanism is inspired by the HAL standard without asserting that we are compliant. This is not a perfect fix but should reduce, if not eliminate, the confusion. I believe linking to HAL is still useful because it explains a very similar and at times identical mechanism in more depth.