From the March APICraft meetup in San Francisco, we dive into the details of one of the newest features of the Open API Specification (fka Swagger Specification) called links. While not intended as a replacement for Hypermedia, the OAS 3.0 Links feature provides design-time designation for rich traversals between operations

1. OpenAPI 3.0 Links
Tony Tam
@fehguy

2. The Most Powerful Tool in APIs

4. Why present Old News?
• Links are pervasive!
Link!

5. Header Links
https://developer.github.com/guides/traversing-with-pagination/
Link!

6. Content Links
https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md#98-pagination
Link!

7. Web Linking
http://www.rfc-editor.org/rfc/rfc5988.txt
Old Link!

8. What needs improvement?
• What are you linking too?
• Client or server computed?
• Non-intrusive
• Standardization

9. Introducing OpenAPI Links!
• What the heck are they?
• “Open API Links are Client-Computed, Design-Time
Parameterized Traversals between Responses and
Operations”

10. Introducing OpenAPI Links!
What the heck are they?
• “Open API Links are Client-Computed, Design-Time
Parameterized Traversals between Responses and
Operations”
Use input
+ output
to determine a Link
destination

11. Introducing OpenAPI Links!
• What the heck are they?
• “Open API Links are Client-Computed, Design-Time
Parameterized Traversals between Responses and
Operations”
Relationships are
defined in OAS, NOT
Response payload!

12. Introducing OpenAPI Links!
• What the heck are they?
• “Open API Links are Client-Computed, Design-Time
Parameterized Traversals between Responses and
Operations”
Dynamic “Operation
Hopping”

13. Introducing OpenAPI Links!
• What the heck are they?
• “Open API Links are Client-Computed, Design-Time
Parameterized Traversals between Responses and
Operations”
Same Deterministic
behavior as Swagger
2.0 Operations

14. What do OAS Links look like?
Use case:
• Fetch a user object
• Fetch their address
???How are they
related?
What about
dynamic locators?

15. What do OAS Links look like?

16. What do OAS Links look like?

17. What do OAS Links look like?

18. What do OAS Links look like?
• You can have many links!

19. And Best of all…
• You know what you get when you follow
them!

20. Another Example
• Pagination
10 Developers
10 Different solutions

21. Server-Side Pagination Example

22. Server-Side Pagination Example
• requestId sent in response headers
• Passed to operation as query parameter

23. What does that get you?

24. What else?
Re-implement the
API to make this!

25. There’s more?
Compute!
Don’t bloat
the payload!

26. In Summary…
• OAS Links are in the Release Candidate
• As with previous Swagger and now OAS
– Not forcing you to re-implement
– Do it your way!(tm)
• Send your feedback!