At a major telco company in Belgium we have designed and implemented a cutting-edge architecture using microservices and hypermedia (REST level 3/hateoas) for the entire customer- and business-facing Web portfolio. Throughout this session you will learn what the microservices hype is all about, including its benefits and pitfalls based on our experiences of running microservices (including the Netflix OSS) in production at a major company in Belgium. To manage hundreds of microservices you need to apply certain patterns such as circuit breakers, gateways, service registries and so on. You will learn how these patterns work, how they are applied through the Netflix stack and how easy it is to use them in your architecture through code examples and demos. The contracts between these microservices should be well defined and loosely coupled. Using hypermedia as the engine of application state (hateoas), we can benefit from independent evolution and decoupled implementation. How we can implement these using Spring Hateoas, correctly document using Spring REST Docs, integrate with the HAL browser and version using JsonViews will become clear in the second part of this session.

1. @andreasevers
Netflix OSS and HATEOAS
deployed on production

2. @andreasevers
WHOAMI
• Work for Ordina Belgium
• Open source enthusiast
• Spring contributor
• Speaker
• Technical lead & coding architect @ Proximus
• Marathon runner

3. @andreasevers

4. @andreasevers
Benefits
• Small, easy to understand code base
• Easy to scale
• Easy to throw away
• Easy to deploy
• Ability to use a different technology stack
• Smaller teams
• System resilience

5. @andreasevers
Pitfalls
“If you can't build a monolith, what makes you
think microservices are the answer?”
Simon Brown

6. @andreasevers
Pitfalls
• Failing to adopt a contract-first approach
• Assuming the wrong communication protocol
• Introducing a shared domain model
• Defining inappropriate service boundaries
• Neglecting DevOps and testing concerns
• Disregarding the human factor
• Operational complexity not under control
• Failing to embrace eventual consistency

7. @andreasevers
Netflix OSS

8. @andreasevers
Gateway

9. @andreasevers
Gateway – What’s the use?

10. @andreasevers
Gateway
µS µS µS µS µSµS

11. @andreasevers

12. @andreasevers

13. @andreasevers

14. @andreasevers
“API Gateways are fast becoming the Enterprise
Service Bus of the microservices era”
Sam Newman
Gateway

15. @andreasevers
Service Registry
Service Registry
loyalty
user billing
billing’
loyalty
user user origin
Origin
1
Origin
2billing
loyalty origin

16. @andreasevers
Service Registry
Service Registry
loyalty
user billing
billing’
loyalty
user
billing
user origin
Origin
1
Origin
2
loyalty origin

17. @andreasevers
billing
Service Registry
Service Registry
loyalty
billing
billing’
loyalty
user user origin
loyalty origin
Origin
1
user
billing’
billing
Origin
2

18. @andreasevers
Service Registry
Service Registry
loyalty
user user origin
loyalty origin
Origin
1billing
Origin
2
Service Registry
loyalty
user user origin
loyalty origin
Origin
1billing
Origin
2
loyalty
Cached
Registry

19. @andreasevers
Service Registry

20. @andreasevers

21. @andreasevers

22. @andreasevers
Circuit Breaker
BackendµS

23. @andreasevers
Circuit Breaker
BackendµS

24. @andreasevers
Circuit Breaker
µS
stream
information
Backend

25. @andreasevers
Circuit Breaker - Dashboard

26. @andreasevers
Circuit Breaker - Dashboard

27. @andreasevers
Config
µS customer
µS user
µS loyalty
Config
Server

28. @andreasevers
Metrics & Admin

29. @andreasevers
Metrics & Admin

30. @andreasevers
Metrics & Admin

31. @andreasevers
Metrics & Admin

32. @andreasevers
Metrics & Admin

33. @andreasevers
Metrics & Admin

34. @andreasevers
Metrics & Admin

35. @andreasevers
Metrics & Admin

36. @andreasevers
Contracts & loose coupling
We can achieve this by using Hypermedia

37. @andreasevers
Hypermedia
Hypermedia
As
The
Engine
Of
Application
State

38. @andreasevers
Hypermedia
h8ps://vimeo.com/20781278
Sub-constraints:
• IdenDficaDon of resources (URIs)
• ManipulaDon via representaDons (request &
response bodies)
• Self-descripDve messages (headers)
• Hypermedia as the engine of applicaDon
state
HTTP as applica+on protocol

39. @andreasevers
Hypermedia
h8ps://vimeo.com/20781278
Sub-constraints:
• IdenDficaDon of resources (URIs)
• ManipulaDon via representaDons (request &
response bodies)
• Self-descripDve messages (headers)
• Hypermedia as the engine of applicaDon
state
If you don’t do
this
Then you don’t adhere to
this
And you are missing out
on these

40. @andreasevers
Concretely?

41. @andreasevers
Hateoas In Action

42. @andreasevers

43. @andreasevers

44. @andreasevers

45. @andreasevers

46. @andreasevers

47. @andreasevers
Hateoas in action
How would you explain to a client to get to the Nerd in the
Basement painting?
A. Go to Amazon.com, in the categories go to fine arts, follow
paintings, more specifically oil paintings, and click on the one
with the title Nerd in the Basement
B. Type
http://www.amazon.com/Nerd-in-the-Basement/dp/
B00L849CSS/ref=lp_6685279011_1_2?
s=art&ie=UTF8&qid=1431864368&sr=1-2 in your browser

48. @andreasevers
Hateoas in action
HTML is a hypermedia format
<a> is a link with method GET
<form> is a link with method POST (or other if specified)
The browser understands this syntax and shows a link or a form if
the server response contains these tags

49. @andreasevers
Hateoas Requirements
Communication between Client and Server depends on:
• Where does the client have to start?
• Root API
• In regular websites: the homepage
• Where am I?
• How do I interpret the current API response?
• In regular websites: the syntax of HTML is interpreted by the browser
• Where can I go?
• What does a link or form with a certain relation or class mean?
• In regular websites: link with relation “stylesheet”, form with action “login”

50. @andreasevers
Hateoas in action
Amazon.com (and any other website in the whole world wide web)
applies Hateoas.
Why wouldn’t your API do the same?

51. @andreasevers
Hateoas Benefit: Runtime action
discovery
GET /account/12345 HTTP/1.1
HTTP/1.1 200 OK
<?xml version="1.0"?>
<account>
<account_number>12345</account_number>
<balance currency="usd">100.00</balance>
<link rel="deposit" href="/account/12345/deposit" />
<link rel="withdraw" href="/account/12345/withdraw" />
<link rel="transfer" href="/account/12345/transfer" />
<link rel="close" href="/account/12345/close" />
</account>

52. @andreasevers
Hateoas Benefit: Runtime operation
discovery
GET /account/12345 HTTP/1.1
HTTP/1.1 200 OK
<?xml version="1.0"?>
<account>
<account_number>12345</account_number>
<balance currency="usd">-25.00</balance>
<link rel="deposit" href="/account/12345/
deposit" />
</account>

53. @andreasevers
Hateoas Concern: Scope
In case of one or two clients built in the same team, it is arguable
whether auto-discoverability is really a necessity

54. @andreasevers
Hateoas Benefit: Non-structural Changes
“categories/1/oil-paintings/1234”
auto-discoverable through HATEOAS as
“categories[1].oil-paintings[1234]”
will not break when 1234 as id is changed to “basementNerd”

55. @andreasevers
Hateoas Benefit: Changing the URI of a
resource
“categories/1/oil-paitings/1234”
being returned as part as the response body of
“categories/1”
will not break the client

56. @andreasevers
Content Types
• JSON
• NOT hypermedia-aware by default
• Needs a fixed format to support links and forms
• Many formats available
• XHTML
• IS hypermedia-aware by default
• Harder to process XHTML responses using javascript (xpath is required)
• The API responses can also be read by a human as regular HTML pages
• SVG, Atom, HTML
• Similar as XHTML but not preferred

57. @andreasevers
JSON Formats
• JSON-LD
• Augmenting existing APIs without introducing breaking changes
• Needs HYDRA as a vocabulary for communicating operations
• Decoupling of API serialization format & communication format
• HAL
• Minimal, light weight syntax and semantics
• Offers most of the benefits of using a hypermedia type
• Easy to convert existing API to HATEOAS
• Chosen and supported by Spring
• No support for specifying operations
• Collection+JSON
• Can list queries that your collection supports and templates that clients can use to alter your collection
• Great for publishing user editable data
• SIREN
• Represents generic classes of items
• Supports operations
• Concept of classes, bringing a sense of type information to your API responses

58. @andreasevers
Considerations
Maturity
Client implementation
Caching
Versioning

59. @andreasevers
h8ps://speakerdeck.com/ankinson/documenDng-resTul-apis-webinar

60. @andreasevers
What should you document
Resources
Links
Cross-cutting concerns

61. @andreasevers
What shouldn’t you document
URIs

62. @andreasevers
What does it look like when you get it
wrong?

63. @andreasevers
What does it look like when you get it
right?

64. @andreasevers
Swagger
Doesn’t support Hypermedia

65. @andreasevers
Swagger
It’s URI centric

66. @andreasevers
Swagger
It’s leaky

67. @andreasevers
Swagger
It’s huge

68. @andreasevers
Best practices for documentation
Write as much as possible in a format which is designed for writing
Don’t use the implementation to provide the documentation
Provide some guarantees that the documentation is accurate
h8ps://github.com/spring-projects/spring-restdocs

69. @andreasevers
Thank you for your attention
@andreasevers
https://github.com/oraj-360
http://registry.oraj360.cfapps.io/
https://netflix.github.io/
http://projects.spring.io/spring-cloud/
http://projects.spring.io/spring-hateoas/
https://github.com/spring-projects/spring-restdocs