The BinSentry API follows the Siren hypermedia specification for representing entities. The Siren specification obeys HATEOAS. There are tools and libraries available in many programming languages that can help you create Siren clients quickly and easily.
Siren (and all HATEOAS compliant APIs for that matter) require developers to think a little differently than they are used to when developing clients for these APIs. Clients of the BinSentry API are encouraged to start at the root (api.binsentry.com) and render all known link relations (rels) on that entity for the user. For instance, suppose you created a website as a client to the BinSentry API. Whenever a user first visits the website, the client would render the rel 'https://api.binsentry.com/rel/login' for the user. Perhaps the website renders the login link in the menu whenever the login option is available. What the client does not need to know is what that URL is or under what circumstances it is available, it only needs to determine how to render that navigational option to the user whenever it is available.
Once a user clicks on the login button, the website would follow the login link to the auth entity that has actions available that the website can render without knowing anything about the API because it follows the Siren specification. The user will know how to use the actions to achieve whatever it is they came here to do. For instance the user may select register, login or request a password reset. The only thing the client needs to do is determine how to render the actions that the user is able to do.
The Content-Type for all Siren entities is `application/vnd.siren+json`.
All Siren APIs are self documenting. We have used this simple API browser tool called Shipwreck to help developers navigate the API. It is also a perfect example of how powerful using a hypermedia based API can be because the API browser has no knowledge of our API, yet it can allow users to do everything that can be done on our web site.