The document discusses the Richardson Maturity Model, which categorizes APIs into four levels based on their complexity, ranging from basic HTTP communication to hypermedia-driven interactions. It highlights the characteristics and examples of each maturity level, with OpenAPI primarily supporting levels 2 and some aspects of level 3. The document emphasizes the difference between OpenAPI's static linking and HATEOAS's dynamic linking for API discoverability.

1. Richardson Maturity and OpenAPI 3.0

2. Agenda
• What is Richardson Maturity Model?
• Level 0 - Basic HTTP
• Level 1 - Resources
• Level 2 - HTTP Verbs
• Level 3 - Hypermedia as the Engine of State

3. Richardson Maturity Model
• Mechanism to categorize at what level your
APIs is at
• Categories from simple to complex (e.g.
Level 0 to Level 3)

4. Level 0 Maturity
• Basic HTTP Communication to tunnel to RPC
• Single endpoint
• HTTP POST
• Examples include SOAP, XML-RPC

5. OpenAPI Example

6. Level 1 Maturity
• Creation of Resources
• Utilize URI to route request to proper Resource
• HTTP POST

7. OpenAPI Example

8. Level 2 Maturity
• Utilize HTTP Verbs and Response Codes to
provide further expression
• Idempotent operations
• Standardized list of operations matched to
GET, POST, PUT, DELETE….

9. OpenAPI Example

10. Level 3 Maturity
• Focus is on dynamic discoverability
• Adds Hypermedia controls to allow clients to
explore and interact more intelligently with
Resources and their state

11. Warning!!!!!!
• OpenAPI focuses on static links (known in
advance)
• HATEOAS focuses on dynamic links (identified
at runtime)

12. Follow on GitHub

13. HAL ExampleGET /orders/523 HTTP/1.1
Host: example.org
Accept: application/hal+json
HTTP/1.1 200 OK
Content-Type: application/hal+json
{
"_links": {
"self": { "href": "/orders/523" },
"warehouse": { "href": "/warehouse/56" },
"invoice": { "href": "/invoices/873" }
},
"currency": "USD",
"status": "shipped",
"total": 10.20

14. OpenAPI Example

15. In Practice
• Most clients are at Level 2
• A few advanced clients are approaching
Level 3 and can leverage static links
• True HATEOAS is not currently supported but is
being discussed in the community

16. Summary
• OpenAPI provides a flexible mechanism to
support today’s APIs
• Focuses on Level 2 with some support for 3