No content

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 

Do it PERFECT. 3 My Career so far… [8] 

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 

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]) 

Do it PERFECT. 6 API-first Definition for Today “[…] develop (and document) APIs before writing other code […]” 

Do it PERFECT. 7 Why API First @ Java Meetup? DUDE, YOU SHOULD USE API-FIRST!!! 

Do it PERFECT. 8 Why API First @ Java Meetup? IT’S CALLED URINATION, NOT YOURINATION 

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” 

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 

Do it PERFECT. 11 Adaptation of API-first Postman [4] (2023, developers and non-developers self evaluation) “66% API first” [7] 

Do it PERFECT. 12 Adaptation of API-first We don’t know… …but we do know, that it will accompany us for a while 

Do it PERFECT. 13 Objectives of API-first 

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 

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] 

Do it PERFECT. 16 Ground Truth • As documentation • As a legal document • As mediation means when interal issues occur 

Do it PERFECT. 17 Communication is Hard 

Do it PERFECT. 18 API Documentation 

Do it PERFECT. 19 API Documentation - WSDL 

Do it PERFECT. 20 API Documentation 

Do it PERFECT. 21 API Documentation - RAML 

Do it PERFECT. 22 API Documentation - OpenAPI + Swagger UI 

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? 

Do it PERFECT. 24 We don’t mind this TODO List Model in JAVA (14+) 

Do it PERFECT. 25 But… 

Do it PERFECT. 26 It only gets worse from here 

Do it PERFECT. 27 Convert back to Code 

Do it PERFECT. 28 My own introduction into “API-first” 

Do it PERFECT. 29 My own introduction into “API-first” 

Do it PERFECT. 30 My own introduction into “API-first” 

Do it PERFECT. 31 My own introduction into “API-first” 

Do it PERFECT. 32 What did I actually want to achieve? 

Do it PERFECT. 33 Can I have API-first without OpenAPI Spec? Most likely yes. And even more. 

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 

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 

Do it PERFECT. 36 DEMO 

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? 

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? 

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 

Do it PERFECT. 40 THANK YOU! 

Do it PERFECT. 41 Feedback please 

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/