Post on 10-Feb-2017
COMMUNICATEHOW TO
OR… “HOW WE CAN CREATE MORE MEANINGFUL, EXPRESSIVE INTERFACES, BUILD DYNAMIC CLIENT LIBRARIES & POWERFUL CLIENT TOOLING,
& MOVE TOWARDS REALTIME HYPERMEDIA APIS.”
HOW TO COMMUNICATE
LIMITATIONS OF OUR CURRENT APIS
▸ Not self-descriptive.
▸ Complexity as APIs grow. Ad-hoc endpoints.
▸ Can be inefficient. Multiple round-trips & overfetch.
▸ What about realtime?
HOW TO COMMUNICATE
TACKLING API COMPLEXITY
▸ Schemas - API description, typically for documentation.
▸ Hypermedia - Modest uptake, no killer tooling.
▸ Graph QL - Motived by inefficiency & complexity.
THE FUNDAMENTALSWhat interface does the service present?
▸ Define a DOM that clients interact with.
▸ Decouple the encoding and transport concerns.
HOW TO COMMUNICATE
THE DOCUMENT MODEL
▸ Data: {…}, […],123, 123.456, “String”, true, false, null.
▸ Documents: Some content with an associated URL.
▸ Links: A URL, an action, and optionally some parameters.
HOW TO COMMUNICATE
THE DOCUMENT MODEL▸ Documents can be nested.
▸ Contain both links and data.
▸ Support either schemas or hypermedia.
HOW TO COMMUNICATE
INTERACTING USING CORE API▸ Client only interfaces at the document layer.
▸ Not concerned with network details in any way.
▸ Multiple encodings & transports supported.
1.
HOW TO COMMUNICATE
4.
2.
3.
▸ Provide the document to act on.
▸ Index to a link in the document.
▸ Possibly some named parameters.
HOW TO COMMUNICATE
INTERACTING WITH OUR API
HOW TO COMMUNICATE
MEANINGFUL INTERACTIONS
▸ Building network requests…
▸ Performing interactions…
HOW TO COMMUNICATE
INTERACTING WITH EXISTING SERVICES
HOW TO COMMUNICATE
INTERACTING WITH EXISTING SERVICES
HOW TO COMMUNICATE
CLIENT TOOLING
HOW TO COMMUNICATE
MULTIPLE ENCODINGS▸ Core API servers can respond with a range of encodings.
HOW TO COMMUNICATE
PARTIAL TRANSITIONS▸ Interact with nested documents.
▸ Replace only the relevant part of the document tree.
HOW TO COMMUNICATE
RICH INTERFACES
HOW TO COMMUNICATE
RICH INTERFACES▸ Not constrained to CRUD style APIs.
HOW TO COMMUNICATE
REALTIME HYPERMEDIA APIS
1.
4.
2.
3.
5.
HOW TO COMMUNICATE
REALTIME HYPERMEDIA APIS▸ WebSockets support for realtime APIs.
HOW TO COMMUNICATE
SUMMARY
▸ Meaningful, self-descriptive interfaces.
▸ Able to interact with existing schema/hypermedia formats.
▸ Schemas for an easy win. Hypermedia for rich interfaces.
▸ Encourages an interface-first API design style.
▸ Allows for powerful client tooling.
▸ Realtime Hypermedia APIs.