Optimize your software with API first

Building software has the purpose of processing data - data flows into systems or must be made available to others. This is why we need APIs and this is at the core of the API first approach. The focus is on the API from the beginning.

In today’s approaches we often think in microservices and headless backend systems - two approaches that pushed the API first thinking.

What changes in the development process? How does the quality of the software increase? And how does API first make all stakeholders happier? I will try to answer these questions in my talk. I also want to show some practical tips and tools for APIs.

Transcript

1. Optimize your software with API first @maxbbeckers #SymfonyOnline
2. About me … • Max Beckers • Solutions Architect • Working for / • Symfony is part of my life since 2012 • Living in the north of Germany (near Kiel) beckers.maximilian@gmail.com @maxbbeckers linkedin.com/in/maximilianbeckers @maxbbeckers #SymfonyOnline
3. The goals of API first • A great API that fits the domain • Define the API as a contract like mockups for the UI/UX • Make the API flexible and modular so you can add or modify functionality without affecting the rest of your application • Service reusability • Headless backends to bring the application to different devices • Microservice Architectures • Scalability optimization • Microservice Architectures @maxbbeckers #SymfonyOnline
4. The different kinds of APIs • The purpose of building software is to process data • Data flows into the application • Data must be made available to others • RESTful & HTTP APIs, message queues, event driven APIs, Web Sockets, File import/export, etc. • dev tools, private / internal services, partner / public APIs @maxbbeckers #SymfonyOnline
5. API „first“ means it has not always been so … @maxbbeckers #SymfonyOnline
6. Coming from Code first • Write code that defines the functionality of the API • API is tightly coupled with the implementation • Creating an application for a specific requirement • Has it‘s limits with the more and more complex architectures like microservices @maxbbeckers #SymfonyOnline
7. The changes with API first • Focus on the data • Define the API • Define a domain model • Understand the use cases of the stakeholders and the domain • User-centered mindset • Agile adding features • Clients and server can be implemented in parallel when the API is specified • Decouple the API from the technology (programming language, framework, etc.) @maxbbeckers #SymfonyOnline
8. The API is a product • Designed to be consumed by developers or other systems • Centrally involve product managers and owners in the process • Especially for public and partner APIs, but also for private APIs • Having a great product can give you an edge over the competitors • Promoted and sold to potential consumers • Decisions for a new service provider are not only made on management level • Developer Experience is an important criterion for a great API • Easy integration of the API reduces the costs and maintenance @maxbbeckers #SymfonyOnline
9. Top factors for a great API • Performance • Security • Reliability • Documentation • Usability @maxbbeckers #SymfonyOnline
10. What makes your API great? • Well documented • Easy to understand • Consistent • Fits with the client‘s business processes • Use standards in your API • Have a look at the different levels for a REST API design • Correct HTTP methods & and status codes (Part of level 3) • RFC 7807 is as an interesting approach to define error responses @maxbbeckers #SymfonyOnline
11. API first: the path to success @maxbbeckers #SymfonyOnline
12. The process changes • Starting at the IDE – needs a rethinking of developers and architects • Start with brainstorming, planning, analysis, talking to stakeholders • Understand the domain • Design an API definition in a partnership with developers and the business • This definition is a contract that must be fulfilled with it‘s implementation • API first allows you to focus on the use cases and features @maxbbeckers #SymfonyOnline
13. Understand the domain and the use cases @maxbbeckers #SymfonyOnline
14. Choose your tool • There are many ways to design an API • There are often a many different and similar tools • Coming only a few examples @maxbbeckers #SymfonyOnline
15. Brainstorming @maxbbeckers #SymfonyOnline
16. Domain Storytelling • Collaborative technique to understand the domain • Learn from stakeholders and domain experts • Analyze the domain concepts, processes and rules • Egon.io is an opensource tool for that • https://domainstorytelling.org/ @maxbbeckers #SymfonyOnline
17. Design an API with OpenAPI @maxbbeckers #SymfonyOnline
18. OpenAPI Specification • An open standard for describing and documenting APIs in JSON or YAML format • Designed for HTTP / RESTful APIs • Define the endpoints with the request / response formats and the authorization methods • Make it easier to understand the API in a standardized way @maxbbeckers #SymfonyOnline
19. Benefits of OpenAPI • Many people are familiar with this specifications • Get a lot of tools around it • There is code generation for server and client • Automation is the key, to make your developer life as easy as possible • The more manual steps, the more errors can slip in • Validation is generated automatically • Less code to maintain • The documentation is always kept up to date when it is part of the process. • Nice possibilities of visualization @maxbbeckers #SymfonyOnline
20. Swagger UI @maxbbeckers #SymfonyOnline
21. Redoc @maxbbeckers #SymfonyOnline
22. OpenAPI linter vacuum @maxbbeckers #SymfonyOnline
23. OpenAPI linter vacuum @maxbbeckers #SymfonyOnline
24. Tools to generate mocks • Prism is an opensource tool to generate a mock directly out of the OpenAPI definition • I often use wiremock to mock endpoints @maxbbeckers #SymfonyOnline
25. There are always pros and cons! @maxbbeckers #SymfonyOnline
26. Challenges with API first • The new process needs a lot of planning and rethinking in a company • Can’t be done by the developers alone, needs IT-Managers pushing it • Train development and product management teams on API first • Define standard processes to build APIs • Can be hard to switch to API first for existing software • More APIs mean more focus on versioning and backward compatibility • Higher technical skills requirement @maxbbeckers #SymfonyOnline
27. Is it worth going the extra mile? @maxbbeckers #SymfonyOnline
28. API first makes happy https://www.postman.com/state-of-api/api-first-strategies/#API-first-strategies @maxbbeckers #SymfonyOnline 0 20 40 60 80 100 120 Are happier Create better code Waste less time in meetings Launch new products faster Integrate with partners faster Eliminate security risks faster Spend less time debugging code Are more productive Onboard faster Postman survey about API first companies Strongly disagree Disagree somewhat Agree somewhat Strongly agree
29. API first makes happy https://www.postman.com/state-of-api/api-first-strategies/#API-first-strategies @maxbbeckers #SymfonyOnline 0 20 40 60 80 100 120 Are happier Create better code Waste less time in meetings Launch new products faster Integrate with partners faster Eliminate security risks faster Spend less time debugging code Are more productive Onboard faster Postman survey about API first companies Strongly disagree Disagree somewhat Agree somewhat Strongly agree
30. API first makes happy https://www.postman.com/state-of-api/api-first-strategies/#API-first-strategies @maxbbeckers #SymfonyOnline 0 20 40 60 80 100 120 Are happier Create better code Waste less time in meetings Launch new products faster Integrate with partners faster Eliminate security risks faster Spend less time debugging code Are more productive Onboard faster Postman survey about API first companies Strongly disagree Disagree somewhat Agree somewhat Strongly agree
31. API first makes happy https://www.postman.com/state-of-api/api-first-strategies/#API-first-strategies @maxbbeckers #SymfonyOnline 0 20 40 60 80 100 120 Are happier Create better code Waste less time in meetings Launch new products faster Integrate with partners faster Eliminate security risks faster Spend less time debugging code Are more productive Onboard faster Postman survey about API first companies Strongly disagree Disagree somewhat Agree somewhat Strongly agree
32. API first makes happy https://www.postman.com/state-of-api/api-first-strategies/#API-first-strategies @maxbbeckers #SymfonyOnline 0 20 40 60 80 100 120 Are happier Create better code Waste less time in meetings Launch new products faster Integrate with partners faster Eliminate security risks faster Spend less time debugging code Are more productive Onboard faster Postman survey about API first companies Strongly disagree Disagree somewhat Agree somewhat Strongly agree
33. API first makes happy https://www.postman.com/state-of-api/api-first-strategies/#API-first-strategies @maxbbeckers #SymfonyOnline 0 20 40 60 80 100 120 Are happier Create better code Waste less time in meetings Launch new products faster Integrate with partners faster Eliminate security risks faster Spend less time debugging code Are more productive Onboard faster Postman survey about API first companies Strongly disagree Disagree somewhat Agree somewhat Strongly agree
34. API first makes happy https://www.postman.com/state-of-api/api-first-strategies/#API-first-strategies @maxbbeckers #SymfonyOnline 0 20 40 60 80 100 120 Are happier Create better code Waste less time in meetings Launch new products faster Integrate with partners faster Eliminate security risks faster Spend less time debugging code Are more productive Onboard faster Postman survey about API first companies Strongly disagree Disagree somewhat Agree somewhat Strongly agree
35. API first makes happy https://www.postman.com/state-of-api/api-first-strategies/#API-first-strategies @maxbbeckers #SymfonyOnline 0 20 40 60 80 100 120 Are happier Create better code Waste less time in meetings Launch new products faster Integrate with partners faster Eliminate security risks faster Spend less time debugging code Are more productive Onboard faster Postman survey about API first companies Strongly disagree Disagree somewhat Agree somewhat Strongly agree
36. API first makes happy https://www.postman.com/state-of-api/api-first-strategies/#API-first-strategies @maxbbeckers #SymfonyOnline 0 20 40 60 80 100 120 Are happier Create better code Waste less time in meetings Launch new products faster Integrate with partners faster Eliminate security risks faster Spend less time debugging code Are more productive Onboard faster Postman survey about API first companies Strongly disagree Disagree somewhat Agree somewhat Strongly agree
37. Aligned and clearly defined API • Makes the implementation smoother • Significantly higher quality of the software • QA has a testing guideline and can find issues faster • Security engineers can be involved earlier • Pays off in terms of maintenance and maintainability • Work in parallel on client and server side of the API • Reduce the time to market for new features @maxbbeckers #SymfonyOnline
38. Flexibility and new features • Understand the domain before the implementation allows us to think like our stakeholders • Easier to implement new use-cases and features • Innovation is supported • Choose programming language and framework for each service • Micro-releases • Trunk based development • Early feedback and early testing – fail fast • Allows non-developers to build apps @maxbbeckers Statuses #SymfonyOnline
39. Next time you are implementing a feature, think about the API first ☺ @maxbbeckers #SymfonyOnline
40. Contact: Max Beckers Solutions Architect at PAYONE, a Worldline company beckers.maximilian@gmail.com @maxbbeckers linkedin.com/in/maximilianbeckers Thanks for your attention!