search

t2trg / t2trg-rest-iot

RESTful Design for Internet of Things Systems
Other
3 stars 4 forks source link

Rule of thumb for good hypermedia-driven design #17

Closed mkovatsc closed 6 years ago

mkovatsc commented 7 years ago

I just gave this advice and it might be a good rule of thumb:

Assuming human-readable representation formats (i.e., text-based not binary) and a client supporting the URI scheme used, a good rule of thumb for a good hypermedia-driven design is the following: A developer should only need an entry point URI to drive the application. All further information how to navigate through the application (links) and how to construct more complex requests (forms) are published by the server(s). There must be no need for additional, out-of-band information (e.g., API specification).

For machines, a well-chosen set of information needs to be shared a priori to agree on machine-understandable semantics. (Agreeing on the exact semantics of terms for relation types and data elements will of course also help the developer.)

cabo commented 7 years ago

Yes, except that text-based doesn't mean human-readable (as exemplified by JSON -- in reality you need a formatting tool to look at any instances that aren't entirely trivial). More important is that the format is self-describing (and the tool you need to look at that not too obscure).

mkovatsc commented 7 years ago

Yes, yes, all this is already in the assumptions to get a concise rule of thumb :)

Next iteration:

Assuming self-describing representation formats (i.e., human-readable with carefully chosen terms or processible by a formatting tool) and a client supporting the URI scheme used, a good rule of thumb for a good hypermedia-driven design is the following: A developer should only need an entry point URI to drive the application. All further information how to navigate through the application (links) and how to construct more complex requests (forms) are published by the server(s). There must be no need for additional, out-of-band information (e.g., API specification).

For machines, a well-chosen set of information needs to be shared a priori to agree on machine-understandable semantics. (Agreeing on the exact semantics of terms for relation types and data elements will of course also help the developer.)