[openstack-dev] [api] link definitions guideline to help align differing styles

michael mccune msm at redhat.com
Mon Nov 23 22:14:18 UTC 2015


hello all,

there has recently been some activity in the guidelines surrounding the 
use of links embedded in response objects. it appears that with the 
recently merged error guideline[1] and the currently frozen pagination 
guideline[2], that we are on the precipice of introducing a bifurcation 
with respect to link usage.

i think we should discuss the differences and create a guideline for 
link style, and then fixup whichever guideline(s) may be out of 
alignment with regards to our decision.

with that said, there appears to be two main implementations that we are 
looking at; the json hyper-schema link description objects[3] (hereafter 
referred to as the LDO approach), and the json hypertext application 
language link objects[4] (hereafter referred to the HAL approach).

on first inspection it would appear that the HAL approach provides more 
options for decorating the link with metadata. i'm not sure if this 
makes it a win in and of itself, but we should juxtapose that against 
the idea that we currently have several examples of the LDO style in use[5].

i'm curious to open this topic up for discussion to help forge a path 
forward.

thoughts?

regards,
mike

[1]: http://specs.openstack.org/openstack/api-wg/guidelines/errors.html
[2]: https://review.openstack.org/#/c/190743
[3]: http://json-schema.org/latest/json-schema-hypermedia.html#anchor17
[4]: https://tools.ietf.org/html/draft-kelly-json-hal-07#section-5
[5]: https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Links



More information about the OpenStack-dev mailing list