apidays New York 2025 - Designing APIs with OpenAPI by Mike Amundsen (Author, API Strategist & Advisor)

Designing APIs with OpenAPI: Build the Right APIs the Right Way
Mike Amundsen, Author of "Design and Build Great APIs", API Strategist & Advisor at amundsen.com, Inc.

apidays New York 2025
API Management for Surfing the Next Innovation Waves: GenAI and Open Banking
May 14 & 15, 2025

------

Check out our conferences at https://www.apidays.global/

Do you want to sponsor or talk at one of our conferences?
https://apidays.typeform.com/to/ILJeAaV8

Learn more on APIscene, the global media made by the community for the community:
https://www.apiscene.io

Explore the API ecosystem with the API Landscape:
https://apilandscape.apiscene.io/

Transcript

1. Designing APIs with OpenAPI Mike Amundsen @mamund
3. Designing APIs with OpenAPI • API Design Assets • Prototyping Your API Design with OpenAPI • Building with Open OpenAPI • Defining OpenAPI Paths • Modifying Your API in Production
4. Let's get started …
5. API Design Assets
6. Design Assets Design assets are any digital resources that are created or used in the design process. -- Uxcel https://app.uxcel.com/glossary/assets
7. API Design Assets • API Story • API Diagram • API Vocabulary
11. API Design Assets • API Story ◦ Shared, accessible, repeatable • API Diagram ◦ Display the interactions • API Vocabulary ◦ The "magical words" of the API
12. Prototyping Your API Design
13. What is an API Prototype? A first, typical or preliminary model of something, especially a machine, from which other forms are developed or copied. -- Oxford Dictionary
14. Why use prototypes? • Inexpensive experiments • Explore the details • Prototypes are made to be tested
15. Why use prototypes? • Inexpensive experiments • Explore the details • Prototypes are made to be tested
16. Building with OpenAPI
17. OpenAPI Basic Info • Contains the basic shared information about your API • Key elements to include are: ◦ version ◦ title ◦ description • Other elements: ◦ servers ◦ paths ◦ components
18. The OpenAPI Component Parameters • Important properties: ◦ name, in, required, schema/type • Recommend properties: ◦ description, example
19. The OpenAPI Component Schemas • Important properties: ◦ type (object/array) ◦ properties (type, description, example)
20. The OpenAPI Component Responses • Important properties: ◦ content (media type) ◦ schema (use $ref) • Don't forget: ◦ description
21. The OpenAPI Component RequestBodies • Use to support arguments in POST/PUT requests • Important properties: ◦ description, required, content, schema • Note: you can support more than one content element
22. Leveraging OpenAPI Components • The OpenAPI Components Section ◦ Organize your OpenAPI definition ◦ Improve the consistency of your API design • Parameters, Schemas, Responses, & RequestBodies ◦ Parameters for inline queries ◦ Schemas for shared objects (item/collection) ◦ Responses for general use responses (e.g. errors) ◦ RequestBodies for POST/PUT requests (e.g. addItem)
23. Defining OpenAPI Paths
24. The OpenAPI Paths Section • Paths are the 'heart' of OpenAPI documents • One top-level entry for each resource/URL • One or more HTTP methods for each resource • One or more parameters, requestBodies, responses
25. Elements of a Path Definition
26. Elements of a Path Definition
27. Elements of a Path Definition
28. Modifying Your API in Production
29. Modifying Your API in Production • Beyond Versioning • Three Rules for Modifying Production APIs • Testing and Deploying Modified APIs
30. Modifying Your API in Production • Beyond Versioning ◦ First, do no harm • Three Rules for Modifying Production APIs ◦ Take nothing away, don't redefine, additions are optional • Testing and Deploying Modified APIs ◦ Don't replace tests, support reversible releases, salesforce vs AWS
31. Review
32. Designing APIs with OpenAPI : Review • API Design Assets • Prototyping Your API Design with OpenAPI • Leveraging OpenAPI Components • Defining OpenAPI Paths • Modifying Your API in Production
33. One more thing …
34. "Good design is actually a lot harder to notice than poor design, in part because good designs fit our needs so well that the design is invisible,"  — Don Norman The Design of Everyday Things
35. Designing APIs with OpenAPI Mike Amundsen @mamund
36. Designing APIs with OpenAPI Mike Amundsen @mamund