API First revisited - where did we take a left turn?

In this talk, we will explore what a modern API-First design workflow could look like and how today’s tools can simplify API contract creation, streamline testing, and boost development efficiency. We’ll cover API-First fundamentals and share a personal journey into this approach. To make concepts more tangible, we’ll include practical code examples in Java, including generated code from OpenAPI specifications for Quarkus and Spring, and comparisons of API specifications in modern Java and OpenAPI (YAML). Alongside a brief history of API documentation from WSDL to Swagger, we’ll have a look at tools like Amazon’s Smithy and Microsoft’s Typespec, followed by a Typespec demo for effective API documentation.

Transcript

2. Do it PERFECT. 2 About me • Lukas • Software Engineer (currently @ Posedio) • Java • Typescript, React, Svelte • Go • PL/SQL • DevOps Engineer • Requirements Engineer / Business Analyst • Software Architect
3. Do it PERFECT. 3 My Career so far… [8]
4. Do it PERFECT. 4 Agenda API-first - Definitions Usage Numbers of API-first Objectives of API-first API Documentation My own API-first Introduction Modern Tools & Demo How to get API- first right Wrap Up
5. Do it PERFECT. 5 API-first – Definitions 1. “[…] develop APIs before writing other code […]” (Postman [1]) 2. “put the development of the API and its eventual consumption model ahead of any other focuses and processes.” (Nordic APIs [2]) 3. “[…] your APIs are treated as ‘first-class citizens.’” (Swagger [3])
6. Do it PERFECT. 6 API-first Definition for Today “[…] develop (and document) APIs before writing other code […]”
7. Do it PERFECT. 7 Why API First @ Java Meetup? DUDE, YOU SHOULD USE API-FIRST!!!
8. Do it PERFECT. 8 Why API First @ Java Meetup? IT’S CALLED URINATION, NOT YOURINATION
9. Do it PERFECT. 9 Feedback “adds extra steps to work” “makes difficult what could be very easy” “does not pay off” “code generation setup is difficult”
10. Do it PERFECT. 10 Disclaimer • I don’t claim to be an API design expert • You might feel very differently about API-first • That’s ok, we can still be friends
11. Do it PERFECT. 11 Adaptation of API-first Postman [4] (2023, developers and non-developers self evaluation) “66% API first” [7]
12. Do it PERFECT. 12 Adaptation of API-first We don’t know… …but we do know, that it will accompany us for a while
13. Do it PERFECT. 13 Objectives of API-first
14. Do it PERFECT. 14 API Design 1. Naming 2. Resource Hierarchy 3. Stick to (HTTP) Standards 4. Use Pagination in a Standardized Way 5. Defaults and Consistent Data Types
15. Do it PERFECT. 15 API Design When it comes to APIs, don’t get creative, be predictable! 58% learn to use APIs through documentation [5] 44% learn to use API through its source code [5] 43% rely on colleagues to explain the API [5]
16. Do it PERFECT. 16 Ground Truth • As documentation • As a legal document • As mediation means when interal issues occur
17. Do it PERFECT. 17 Communication is Hard
18. Do it PERFECT. 18 API Documentation
19. Do it PERFECT. 19 API Documentation - WSDL
20. Do it PERFECT. 20 API Documentation
21. Do it PERFECT. 21 API Documentation - RAML
22. Do it PERFECT. 22 API Documentation - OpenAPI + Swagger UI
23. Do it PERFECT. 23 What can an API Specification do for me? [6] 1. Business Involvement 2. Co-Design 3. Governance 4. Linter 5. Docs 6. Low Code 7. Mocks 8. SDKs 9. Runtime Validation & Tests This is awesome! Where did we take a left turn?
24. Do it PERFECT. 24 We don’t mind this TODO List Model in JAVA (14+)
25. Do it PERFECT. 25 But…
26. Do it PERFECT. 26 It only gets worse from here
27. Do it PERFECT. 27 Convert back to Code
28. Do it PERFECT. 28 My own introduction into “API-first”
29. Do it PERFECT. 29 My own introduction into “API-first”
30. Do it PERFECT. 30 My own introduction into “API-first”
31. Do it PERFECT. 31 My own introduction into “API-first”
32. Do it PERFECT. 32 What did I actually want to achieve?
33. Do it PERFECT. 33 Can I have API-first without OpenAPI Spec? Most likely yes. And even more.
34. Do it PERFECT. 34 Amazon Smithy 1. DSL for Writing SDK and Service definitions 2. Protocol Agnostic 3. Modularized System (not everything in one file) 4. Works well for the Java Ecosystem and has IntelliJ Support
35. Do it PERFECT. 35 Microsoft Typespec • DSL (similar to Typescript) • Modularized • VS (Code) Support • Support by Microsoft for HTTP / REST, gRPC, OpenAPI and JSON Schema • Protocol Agnostic and extensible
36. Do it PERFECT. 36 DEMO
37. Do it PERFECT. 37 Context and Scope “Environment-first” 1. Do you have special constraints or overarching guidelines to consider? 2. Will your decisions impact someone else’s work in your environment? 3. Do you really know your domain? 4. Does your architecture need to scale out? 5. Do you know / control your consumers?
38. Do it PERFECT. 38 All set, how do I get Started? 1. How do you want to communicate your specs? 2. Do I want a review process? Who needs to have access and who can contribute in which way? 3. Which addons (code generation, linting, testing, etc.) do I want to add? 4. Where do I store my specs? 5. How much time am I willing to invest in setting standards?
39. Do it PERFECT. 39 Wrap Up 1. Reduce the number of APIs if possible 2. Consider who you are writing your specs for 3. Use API-first to ensure compliance with standards 4. “Environment First” 5. Modularizing your API specification allows it to scale 6. Be pragmatic – API first will not fit everywhere
40. Do it PERFECT. 40 THANK YOU!
41. Do it PERFECT. 41 Feedback please
42. Do it PERFECT. 42 References 1. https://www.postman.com/api-first/ 2. https://nordicapis.com/what-does-it- mean-to-be-api-first/ 3. https://swagger.io/resources/articles/a dopting-an-api-first-approach/ 4. https://voyager.postman.com/pdf/2023- state-of-the-api-report-postman.pdf 5. https://voyager.postman.com/doc/post man-state-of-the-api-report-2024.pdf 6. https://www.youtube.com/watch?v=EIN evYeNosc 7. https://www.postman.com/state-of- api/2024/ 8. https://www.reddit.com/r/Bossfight/co mments/1ghxtsf/le_minh_thien_toan_d eveloper_of_software/