Optimize your software with API first @maxbbeckers #SymfonyOnline

About me … • Max Beckers • Solutions Architect • Working for / • Symfony is part of my life since 2012 • Living in the north of Germany (near Kiel) [email protected] @maxbbeckers linkedin.com/in/maximilianbeckers @maxbbeckers #SymfonyOnline

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

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

API „first“ means it has not always been so … @maxbbeckers #SymfonyOnline

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

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

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

Top factors for a great API • Performance • Security • Reliability • Documentation • Usability @maxbbeckers #SymfonyOnline

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

API first: the path to success @maxbbeckers #SymfonyOnline

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

Understand the domain and the use cases @maxbbeckers #SymfonyOnline

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

Brainstorming @maxbbeckers #SymfonyOnline

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

Design an API with OpenAPI @maxbbeckers #SymfonyOnline

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

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

Swagger UI @maxbbeckers #SymfonyOnline

Redoc @maxbbeckers #SymfonyOnline

OpenAPI linter vacuum @maxbbeckers #SymfonyOnline

OpenAPI linter vacuum @maxbbeckers #SymfonyOnline

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

There are always pros and cons! @maxbbeckers #SymfonyOnline

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

Is it worth going the extra mile? @maxbbeckers #SymfonyOnline

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

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

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

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

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

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

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

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

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

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

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

Next time you are implementing a feature, think about the API first ☺ @maxbbeckers #SymfonyOnline

Contact: Max Beckers Solutions Architect at PAYONE, a Worldline company [email protected] @maxbbeckers linkedin.com/in/maximilianbeckers Thanks for your attention!