-
Notifications
You must be signed in to change notification settings - Fork 0
Hypermedia Workshop
This workshop is to look at creating, consuming and documenting hypermedia APIs. We will walk through fully working examples of the API and various types of clients. The session is based on the material in How to Hypermedia and the working example at todo.semanticlink.io.
The essence of the workshop is to present and given people experience in hypermedia API and client implementations where there is:
- a single API: all clients walk its network of data
- multiple (actually, three) clients:
- general-purpose client to navigate the API (for development teams);
- rich-client user interface (for customers);
- machine-to-machine provisioning client (for business that require batching processes)
How much material is covered depends on the participants. Participants with more experience will be encouraged to share their expertise but will also be able to work at a faster pace and to a greater depth if they desire.
It has become increasingly common to use HTTP for applications as well just browsing the Internet. There have been various incarnations of using "HTTP APIs" to integrate processes on disparate systems to make information available across machines. Early versions used HTTP as transport protocol (eg SOAP) whereas later ones layer across HTTP as an application protocol. By using HTTP as an application protocol, these applications realise a number of benefits, including caching, message framing, and in practice a well-defined semantics that are approachable, easy to understand and easy to use.
In the first attempts of these applications, a set of known URIs were set up as the contract between clients and servers. This approach is still dominant and creates an early binding between clients and servers that makes certain types of changes difficult because both sides must change at the same time. It is made all the more difficult when APIs are built for certain types of clients or client environments. So in practice, we need ways to remain stable as APIs evolve and change whether through extension or drift.
In looking for solutions, the Web itself offers one way to address these issues, using links to navigate between states. A link-driven application discovers relevant resources at run time, using a shared vocabulary of link relations and internet media types to support a “follow your nose” style of interaction–just as a Web browser does to navigate the Web. This can be understood as an approach to hypermedia.
Later approaches to applications using HTTP have followed this hypermedia approach. One key difference to earlier approaches is that the client does not know in advance what a URI will be. In fact, the client should never care. Rather a client can decide which resources to interact with "on the fly" based upon its own capabilities (that is, the link relations that it understands). In this way, the server can safely add new resources or extend current resources without disturbing clients that are not yet aware of them.
Building HTTP applications based on hypermedia is building on the way the Web works
From Introduction How to Hypermedia
The session caters for multiple audiences from:
- beginners (who can run the examples and start to understand the interactions of hypermedia at the API level);
- through to the experienced (who can pull apart the assumptions and implementations)
- Introduction: hypermedia applications (45 mins)
- warm up and getting know who is in the room
- Hypermedia application as a three layers
- Exploring the network of data-follow the links and using forms (client one: developer friendly) (30 mins)
- BREAK (10.15-10.30)
- Documenting the network of data in practice (20 mins)
- exercise: time now to draw your API
- demo: sample uml
- Making it a business application coupled on link relations (client two: user friendly)
- exercise: load up the app and explore
- debrief to questions
- Replicating state and client-side application caches (client three: business friendly)
- exercise: load up the admin app and explore
- debrief to questions
- continue looking at client implementations not covered in the morning
- work through some of the tutorials on How to Hypermedia
- extend the API (add comments)
- implement a basic API in another language/framework (ie collection-based)
- implement content negotiation for another microformat supporting collections
- implement any of the clients in another language/framework
- grok the client cache and link relation bindings
- grok the resource-based authorisation over role-based
- design your own query language for client queries ;-)
- write a spider across the API and output dot notation documentation