A new element, describing link relation to curies. Structure:
- name - should match to a defined curie by name, required
- value - the value or values that will expand to curie template by position, optional, defaults to link name
Added a new collection of curied relations, described above.
Can be a single object or an array.
Given curies:
"curies": [
{"name": "doc", "href": "http://example.com/api/documentation/orders#{rel}", "templated": true},
{"name": "usage", "href": "http://help.example.com/articles/orders/{rel}", "templated": true},
{"name": "multi", "href": "http://help.example.com/articles/orders/{rel}?{pageNumber}", "templated": true}
]
The following link: "next": {"href":"/orders", "curied": "doc"}
Is resolved only to doc curie and expands to: http://example.com/api/documentation/orders#next
Here the value for the {rel}
is calculated from link name, as before.
One can also add explicit value, e.g.: "next": {"href":"/orders", "curied": {"doc": "getNextPage"}}
Is resolved only to doc curie and expands to: http://example.com/api/documentation/orders#getNextPage
Here the value for the {rel}
is taken from curied value because it's explicitly set.
Multiple values can be set as well, e.g.: "next": {"href":"/orders", "curied": {"multi": ["next", "2"]}}
Is resolved only to multi curie and expands to: http://help.example.com/articles/orders/next?2
Here the values for the {rel}
and {pageNumber}
are taken from curied value because they are explicitly set.
Multiple curies would be set e.g. like this:
"next": {"href":"/orders", "curied": [
{"doc"},
{"usage": "browseOrders?method=getNextPage"}
{"multi": ["next", "2"]}
]}
These are resolved to all three curies and expand to:
- doc:
http://example.com/api/documentation/orders#next
- usage:
http://help.example.com/articles/orders/browseOrders?method=getNextPage
- multi:
http://help.example.com/articles/orders/next?2
Or with default values: "next": {"href":"/orders", "curied": [{"doc"}, {"usage"}, {"multi"}]}
In which case it expands to:
- doc:
http://example.com/api/documentation/orders#next
- usage:
http://help.example.com/articles/orders/next
- multi:
http://help.example.com/articles/orders/next?
{
"_links": {
"self": {"href": "/orders", "curied": {"doc": "orders"}},
"next": {"href": "/orders?page=2", "curied": {"doc": "orders/next"}},
"find": {
"href": "/orders{?id}",
"templated": true,
"curied": [{"doc": "orders/find"}, {"usage": "searching"}]
},
"admin": [
{"href": "/admins/2", "title": "Fred", "curied": {"adminDoc"}},
{"href": "/admins/5", "title": "Kate", "curied": {"adminDoc"}}
],
"curies": [
{"name": "doc", "href": "http://example.com/api/documentation#orders/{rel}", "templated": true},
{"name": "adminDoc", "href": "http://example.com/api/documentation/{rel}", "templated": true},
{"name": "usage", "href": "http://help.example.com/articles#orders/{rel}", "templated": true}
]
},
"currentlyProcessing": 14,
"shippedToday": 20
}
- self can have documentation
- multiple documentations per link
- custom value for curie template
- doesn't interfere with prefixing
- prefixing can now belong to business side of logic, instead of being used for curies only
- current implementations will not work due to prefix being explicitly added to link name
Yep, that's true. Still I think there will be times this kind of flexibility might be appropriate, but I guess I can add the complexity when the time comes. Thanks for the input!