Hypermedia Affordances

[smizell]

Hello friends :)

I'd like to propose adding functionality that would allow for defining hypermedia affordances in API Elements. This would require we have a section for defining affordances and a way to list what affordances we expect for a given response.

Reason

Right now, you need an additional format for defining hypermedia controls for an API, whether it's Swagger or API Blueprint. This would provide the ground work for this in those formats along with being a foundation for moving towards Resource Blueprint.

Specification Change Proposals

Category for Affordances

For this, we will simply need to specify a category class for for affordances. I would propose affordances for this. This category may be found in the API category or the resource category, allowing users to define global and resource-specific affordances.

Affordance Element

• element: affordance
• attributes
  • controlType (enum)
    • safe - A hypermedia control that triggers a safe, idempotent state transition (e.g. HTTP.GET or HTTP.HEAD).
    • unsafe - A hypermedia control that triggers an unsafe, non-idempotent state transition (e.g. HTTP.POST).
    • idempotent - A hypermedia control that triggers an unsafe, idempotent state transition (e.g. HTTP.PUT or HTTP.DELETE).
• content (array)
  • (Copy)

The control types are borrowed from ALPS section 2.2.12. The meta.id value would be used to specify the name of the affordance.

For the element, the origin link SHOULD be used whenever an affordance (i.e. link relation) is being used that is defined elsewhere. For example, if the self link relation is being used, it could specific https://tools.ietf.org/html/rfc4287 as its origin.

The content of this element can later be used for defining other data for the affordance, such as fields for the affordance.

Response Affordances

We would then alter the HTTP response to allow for the new affordance category to be used in the content. There, ref elements will be used to reference already-defined affordances.

The presence of these affordances in a response tell the consumer that in the given transaction, these affordances SHOULD be found. This is also not specific to any hypermedia format, which goes along with the idea of data structures not being for a specific data format.

Transition Relation

Once affordances can be defined, they should be able to be used within the relation attribute for transitions. This would mean that we should add a clause specifying users that they SHOULD provide an affordance definition when using a relation. Consumers are free to throw errors in situations where a relation is used by not defined.

Other Considerations

API Blueprint

Once defined, API Blueprint could provide a section for defining link relations that would line up with the relations used within the transition. It could also be changed to provide an affordance/link relation section in a response.

Dredd Usage

Once this is in place, Dredd could be used to test expectations of hypermedia affordances. This kind of tooling is really missing in defining and testing hypermedia APIs. I've personally had to build my own tooling to make this work.

Final Thoughts

In addition to ALPS and Resource Blueprint, I have experimented with this idea here. I'd love to see formats make this available, and my proposal for adding this here in API Elements first to make that possible.

Also, I'd be happy to put together a pull request for this. Just want to put together this proposal to see what people think.