I think some way to discover the available actions is needed, but the way to do it is far from obvious: the approaches range from the most granular (e.g. resource-level data like you're proposing) to schemas, schema documents, and specs like json home. So I think your proposal is a very good start to the discussion, but I suspect it will certainly trigger a heated debate, and so is probably something best left to consider after 1.0, which now has a (supposed) release date of May 21.

approaches range from the most granular (e.g. resource-level data like you're proposing) to schemas, schema documents, and specs like json home.

@ethanresnick, exactly, this PR is specifically about granular control, which could enable HATEOAS features in the APIs. It specifically requires the returned information to be valid for the given client on the given resource at the given moment of time. Another consideration is that it should not require additional trips to the server: this could be very important to some APIs.

Schemas are static. I think, they do not fit the bill.

Ashamed of my ignorance, but what is "schema document"? Could you provide a reference?

As for JSON Home, AFAIK, it is endpoint-centric, i.e. it allows to provide additional information about specific endpoint but does not allow to link custom endpoints to the "parent" endpoint, which is the primary goal of this proposal. Am I wrong?

Also, JSON Home documents are supposed to be provided at separate endpoints. The format of JSON Home messages could be potentially reused inside JSON API responses, but it is unclear whether it gives much of advantage without full conformance to JSON Home spec.

I am ready to rewrite this PR to comply with a standard which can accommodate the proposed change. Are there such standards?

it will certainly trigger a heated debate, and so is probably something best left to consider after 1.0, which now has a (supposed) release date of May 21.

If it happens, it will inevitably have to wait until post 1.0, but it is not the case as of yet. Not that I am going to stop caring about JSON API after 1.0, but given how long 1.0 has taken, 1.1 may easily take another year, having in mind that backward compatibility guarantees will be in place and things will likely be considered with extra caution (the cost of minting a new media type seems pretty high to me). As I tried to describe in section Milestoning of #431 (comment), there is a POV of the spec and libraries, and there is a POV of specific APIs. From the POV of specific APIs (the end users of the spec), there is no point to postpone anything post 1.0 if it can be handled before 1.0 (e.g., because it is clear and non-controversial), whether the change is additive or not. The spec is timeless "law of the land", the APIs are "people", who are born and die under that law, and they have no second chance if the law happened to be changed too late in their lifetime. Lawmakers should care about both abstract justice and people.

Ashamed of my ignorance, but what is "schema document"? Could you provide a reference?

Sorry, my mistake using loose terminology. By schema vs. schema document, I was just trying to distinguish between proposals we've had to serve the schema at the top-level of each request, vs. to create a dedicated endpoint for it (the contents of that endpoint being what I was calling the "schema document"). But they're basically the same :) Also, I think that some of those proposals tried to describe (at least) the valid https methods for the resources they were describing, which is why I put them alongside json-home.

As for JSON Home, AFAIK, it is endpoint-centric, i.e. it allows to provide additional information about specific endpoint but does not allow to link custom endpoints to the "parent" endpoint, which is the primary goal of this proposal. Am I wrong?

Gotcha. You're looking for true HATEOS, as opposed to just some API-wide documentation (even if machine-readable) at a separate endpoint. I think this could be a good idea, though I'm not passionate either way.

All I'd suggest for this PR, then, is checking out the history https://github.com/json-api/json-api/issues/159, which is applicable at least to the choice of the "label" keyword. Also check out the other efforts to support Web Linking in JSON, if you haven't seen them already. (Decent overview here.)

@ethanresnick, thanks for the references!

You're looking for true HATEOS

Not necessarily. I am actually looking for a flexible option, which can hopefully be used by "true HATEOAS" APIs as well as by API clients which do not really browse endpoints in a HATEOAS sense, but still can benefit from knowing the list of actions available on a given resource to a given user at a given moment of time. For example, this can allow web frontend to accurately display to the end user only the UI controls which are currently available to her on a given resource, which is orthogonal to HATEOAS.

I have formulated another proposal to address the issue in a more general way. I am closing this PR in favor of #622.