Sketch out hypermedia interaction pattern (incl caching and service document)

[hlgr360]

I was thinking about the problem described above some more over the weekend. ... the notion that in order to truely do hypermedia you would need to first access the service document of the API (to stay in the terminology of Atom PUB protocol), find the resource _link based on the relationship attribute value, and only then can pull the resource
I send that question to mike Ammundsen and Irakli .. two experts on this from one of my past lifes

will forward their answer (when they respond)

but my engineering self is thinking that you can assume to know the list of relation attributes values a priori .. the list of rel attr values present the semantic dictionary (rel val = resource plus operation) .. and the meaning of each value is fixed and can not be changed in a non-breaking manner

a value of 'user' must always mean an 'user' over the lifetime of the api .. you can add new attr values .. you can add new fields to existing attr values .. but you can't change the meaning of an existing one
so here is the basic idea of a service document (as Atom Pub defined it .. to me still one of the gold standards of XML based API's ..)

http://www.greenbytes.de/tech/webdav/rfc5023.html#rfc.section.8.3.1

The purpose of the service document such that a client has a single place to start 'discovering' the API without having to hard code the exact structure in the client (and thereby creating close syntactical coupling)

I think a most basic solution to deal with the potential costs of 'alwasy having to do 2 calls' is to retrieve the service document only once and cache it on the client side ..

the caching could be expiring based on duration or through a caching header indicating the current version of the service document .. if the version from the server is different from the client .. the client 'rediscovers' the service document and prepares something like a lookup table for resources
so you have an effective cost of one additional transaction at the first time the client connects .. and then only if the service document changes
in between those discovery steps the API interactions flow pretty much the same as if you had a-priori knowledge of the API .. you need a resource, you do a lookup in the hash table for the link (discovered through the service document interaction) you do the call
so based on this .. here are some links I found

https://github.com/hypoport/hal-service-document-consumer
hal-service-document-consumer - A library to consume HAL based service documents of restful services.

on HAL and swagger
http://stackoverflow.com/questions/24389733/document-hal-links-from-spring-hateoas-with-swagger
Document HAL "_links" from Spring Hateoas (with swagger)?

[hlgr360]

dret [11:38 AM]
https://tools.ietf.org/html/draft-nottingham-json-home might be interesting to look at. the idea is that instead of every API crafting their own, it might make sense to have a format to start with when designing service documents. (also see https://mnot.github.io/I-D/json-home/)

[11:39]
like anything generic, it of course is not as pretty as a service document can be for a specific API, but then again you avoid NIH syndrome and who knows, may be tooling will emerge to do something cool across APIs!

[11:40]
https://tools.ietf.org/html/draft-wilde-home-xml takes mark's model and defines an XML representation for it.

[hlgr360]

https://www.infoq.com/news/2012/05/json-home .. pointing to http://blog.stateless.co/post/13296666138/json-linking-with-hal

[hlgr360]

http://dret.typepad.com/dretblog/2016/08/api-maps-hypermedia-api-design.html

[hlgr360]

http://nordicapis.com/designing-a-true-rest-state-machine/

[hlgr360]

https://github.com/otto-de/jsonhome