Skip to main content

Hypermedia to Reduce Coupling

Context​

Microservices are being adopted. The internals of the microservices are hidden behind its API. There is a need to make changes to a microservice API that are not backward compatible.

Problem​

  • Breaking API changes influence consuming microservices.
    • The system becomes unstable and/or release coordination is required to introduce breaking API changes.

Solution​

Use hypermedia concepts to decouple APIs. Instead of having implicit knowledge where something is located, this knowledge can live in the interface via hypermedia links allowing for evolution.

Example​

Minimal example with an HTTP API. The second endpoint is refactored to be available under a different path.

MethodPathDescription
GET/customers/Get list of customers
GET/customer/$id/addressesGet list of addresses for customer with id

Without hypermedia support, the knowledge to get from the customer to their addresses is provided by the documentation. The consuming services need to be changed if the path to the resource changes.

With hypermedia support, the customers endpoint would include the URL where to fetch the addresses of the specific customer as meta data in the responses. The consuming services do not need to change because they just follow the link to the new endpoint location. This strategy can also mitigate refactoring where certain resources are moved from one microservice to another.

Maturity​

Proposed, evaluation required.

Sources of Evidence​

L7:

  • HATEOAS = Hypertext as the Engine of Application State
  • part of the REST maturity
  • Author rises question: should that be part of the machine-readable service contracts?

L22:

  • Mike: no breaking changes pledge => keep moving quickly
    • message-oriented hypermedia-driven approach
      • first step in migrations: decoupling the interface
    • only pass messages, not RPC function handles
      • message models as HTML, Atom, Collection+JSON, HAL, Siren
      • all embedded hypermedia support designed in
      • => safely deal with changes in Bounded Contexts over time
        • objects change shape and components modify Bounded Contexts
        • services use same standard message models but with new hypermedia controls (e.g. links and forms) to support the inevitable changes in BC
    • include links and forms in all responses
      • support loosely coupled interoperability between service components

Interview B:

  • RESTful calls
    • idea: resource => CRUD over HTTP
  • GraphQL interesting if having dependency graph between model classes
    • can achieve the same with HATEOAS => link to the dependent model
    • Links can easily switch to new version

Interview D:

  • Context: business vs technical communication style between microservices
  • many customers just do REST (acts fictive conversation with customer)
    • Customer: REST because that's how you do microservices
    • Interviewee: Not correct: others do events
    • Customer: but REST is how the internet works
    • Interviewee: so you build a hypermedia application?
    • Customer: No but the internet is hypermedia, REST was developed for it
    • Interviewee: HTTP, not REST; REST is only architecture style, HTTP is only a manifestation of REST => for hypermedia
      • all constraints in REST base on sharing and connecting hypermedia-based documents in a scalable way
      • So that's not what you do..
  • Context: documentation of microservices
    • ideal: in request say that you want HTML instead of JSON => fetch docs to endpoint
      • replaces swagger
      • that is REST maturity level X (I don't know)
        • self-documentation
      • even better: automated navigation thru links to crawl thru the whole thing
        • => hypermedia as the engine of application state and so forth