The document discusses hypermedia and HATEOAS (Hypermedia as the Engine of Application State) as it relates to REST APIs. It defines hypermedia as a nonlinear medium including graphics, audio, video, text and hyperlinks. HATEOAS means that the client interacts with hypermedia controls exclusively, without relying on out-of-band information. The document outlines the typical REST flow and how it can be improved by following HATEOAS principles and including hypermedia links in responses to guide the client. It also discusses standards like HAL (Hypertext Application Language) and efforts in the PHP community to automate and standardize the use of HATEOAS and HAL.

1. Hypermedia!
By:
Adam Culp
Twitter: @adamculp

2. 2
Hypermedia!
●
About me
– DevRel and Tech Lead at Nexmo
– OSS Contributor
– PHP-Fig member project (IBM i Toolkit)
– Organizer SoFloPHP (South Florida)
– Organizer SunshinePHP (Miami)
– Long distance (ultra) runner
– Judo Black Belt Instructor

3. 3
Hypermedia!
●
About me
– DevRel and Tech Lead at Nexmo
– OSS Contributor
– PHP-Fig member project (IBM i Toolkit)
– Organizer SoFloPHP (South Florida)
– Organizer SunshinePHP (Miami)
– Long distance (ultra) runner
– Judo Black Belt Instructor
I am the
PHP Ninja!!!

4. 4
Hypermedia!
●
Fan of iteration
– Pretty much everything requires iteration to do well:
●
Long distance running
●
Judo
●
Development
●
Evading project managers
●
Hypermedia!

5. 5
Hypermedia!
●
Who avoids creating static applications?

6. 6
Hypermedia!
●
Most API clients are static versus dynamic

7. 7
Hypermedia!
●
What is “Hypermedia”?
– "...a nonlinear medium of information that includes graphics, audio,
video, plain text and hyperlinks." - wikipedia
https://en.wikipedia.org/wiki/Hypermedia

8. 8
Hypermedia!
●
What is “Hypermedia”?

9. 9
Hypermedia!
●
What is “Hypermedia”?
"...a nonlinear medium of information that includes graphics, audio,
video, plain text and hyperlinks." - wikipedia
It’s the WEB!

10. 10
Hypermedia!
●
What is “Hypermedia”?
But what about APIs?

11. 11
Hypermedia!
●
Typical REST Flow
– Consult documentation

12. 12
Hypermedia!
●
Typical REST Flow
– Consult documentation
– Make HTTP call

13. 13
Hypermedia!
●
Typical REST Flow
– Consult documentation
– Make HTTP call
– Get back result

14. 14
Hypermedia!
●
Typical REST Flow
– Consult documentation
– Make HTTP call
– Get back result
– On success, hard-code for future

15. 15
Hypermedia!
●
Typical REST Flow
– Consult documentation
– Make HTTP call
– Get back result
– On success, hard-code for future
HYPERMEDIA IGNORED!
HYPERMEDIA IGNORED!

16. 16
Hypermedia!
●
HATEOAS!

17. 17
Hypermedia!
●
HATEOAS!
– Hypermedia as the Engine of Application State
https://en.wikipedia.org/wiki/HATEOAS

18. 18
Hypermedia!
●
HATEOAS!
– Hypermedia as the Engine of Application State
– “Used as a medium and constraint for REST APIs” - wikipedia
https://en.wikipedia.org/wiki/HATEOAS

19. 19
Hypermedia!
●
HATEOAS!
– Hypermedia as the Engine of Application State
– “Used as a medium and constraint for REST APIs” - wikipedia
– “Client needs little to no prior knowledge about how to interact with an
application...beyond a generic understanding of hypermedia.” - also
wikipedia
https://en.wikipedia.org/wiki/HATEOAS

20. 20
Hypermedia!
●
HATEOAS!
– Hypermedia as the Engine of Application State
– “Used as a medium and constraint for REST APIs” - wikipedia
– “Client needs little to no prior knowledge about how to interact with an
application...beyond a generic understanding of hypermedia.” - also
wikipedia
– Enables server to evolve independently
https://en.wikipedia.org/wiki/HATEOAS

21. 21
Hypermedia!
●
HATEOAS and Versioning
– Enables server to evolve independently
●
Versioning, what?

22. 22
Hypermedia!
●
HATEOAS and Versioning
– Enables server to evolve independently
●
Versioning, what?
– Websites don’t have a v1 or v2?
●
Why do APIs?

23. 23
Hypermedia!
●
The 6 Primary Constraints of REST
– Client/Server
●
Separation of concerns
– Such as:
●
Clients = no data storage concerns
●
Servers = no concern with UI
●
Allows independent evolution
https://en.wikipedia.org/wiki/Representational_state_transfer

24. 24
Hypermedia!
●
The 6 Primary Constraints of REST
– Client/Server
– Stateless
●
No client context being stored on server between requests
●
Each request must be independent (containing all info)
●
Information of client state must stay with client
https://en.wikipedia.org/wiki/Representational_state_transfer

25. 25
Hypermedia!
●
The 6 Primary Constraints of REST
– Client/Server
– Stateless
– Cacheable
●
Responses must, implicitly or explicitly, define themselves as
cacheable or not...to prevent client from getting stale data.
https://en.wikipedia.org/wiki/Representational_state_transfer

26. 26
Hypermedia!
●
The 6 Primary Constraints of REST
– Client/Server
– Stateless
– Cacheable
– Uniform Interface
●
Simplifies and decouples architecture, includes:
– Resource identification in request
– Self-descriptive messages
– HTTP verbs (GET, POST, PUT, DELETE)
– HATEOAS
https://en.wikipedia.org/wiki/Representational_state_transfer

27. 27
Hypermedia!
●
The 6 Primary Constraints of REST
– Client/Server
– Stateless
– Cacheable
– Uniform Interface
– Layered System
●
Client not aware of being connected directly to server, or
intermediary.
– Load balancer, etc.
https://en.wikipedia.org/wiki/Representational_state_transfer

28. 28
Hypermedia!
●
The 6 Primary Constraints of REST
– Client/Server
– Stateless
– Cacheable
– Uniform Interface
– Layered System
– Code on Demand (optional, avoid)
●
Servers can extend code by transferring executable code. Client side
scripting.
https://en.wikipedia.org/wiki/Representational_state_transfer

29. 29
Hypermedia!
●
The 6 Primary Constraints of REST
– Client/Server
– Stateless
– Cacheable
– Uniform Interface
– Layered System
– Code on Demand
https://en.wikipedia.org/wiki/Representational_state_transfer
Hypermedia present in 4 of the 6

30. 30
Hypermedia!
●
Typical REST Flow – Corrected!
– Consult documentation
– Make HTTP call
●
GET, POST, PUT/PATCH, DELETE
●
Or maybe OPTIONS call!
– Get back result
●
Including potential action links
– Determine needs
– Continue as needed

31. 31
Hypermedia!
●
Standards
Yahapi
Uber
JSON API
HAL
Mason
Collection+JSON
CPHL
Siren
JSON-LD

32. 32
Hypermedia!
●
HAL
– Internet draft by Mike Kelly in 2012
●
https://tools.ietf.org/html/draft-kelly-json-hal-08
– Allows for nesting of links
– Supports both JSON and XML
– Incorporates documentation
– Most popular

33. 33
Hypermedia!
●
HAL
– Part 1

34. 34
Hypermedia!
●
HAL
– Part 2

35. 35
Hypermedia!
●
HAL
– Multi-layer

36. 36
Hypermedia!
●
HAL
– Encourage API sources to include HAL HATEOAS!

37. 37
Hypermedia!
●
PHP-FIG
– Hypermedia Link Definition Interface (PSR-13)

38. 38
Hypermedia!
●
Automating HAL
– Zend Expressive-HAL
●
Works with Doctrine or many other PSR-7 compliant app
●
Uses PSR-11 compliant containers
●
Meets PSR-13 Hypermedia Links
https://github.com/zendframework/zend-expressive-hal

39. 39
Hypermedia!
●
See Zend Expressive-HAL used on Beachcasts
– Episode 7 of Expressive Series on YouTube
●
https://youtu.be/dX6S-pJVUXI

40. 40
Hypermedia!
●
Conclusion!
– Use API versioning carefully
– Love Hypermedia
– Learn HATEOAS
– Use HAL
– Automate!

41. 41
Hypermedia!
●
Go!
– Your Turn!

42. ●
Thank you!
– Code: https://github.com/adamculp/
Adam Culp
https://beachcasts.com
https://geekyboy.com
https://rungeekradio.com
Twitter @adamculp
Questions?