Design First APIs and Domain-Driven Design - Ljubica Lazarevic - DDD Europe 2022

okay good morning everybody thank you very much for joining me today I'm very glad to be here I'm Lila zarovich I am a developer Advocate at gravity and I would like to talk to you about design first so let's start off with the rise of apis and I'm sure many of you have spotted that we're going through this big proliferation of apis So Gone are the days of many years ago where maybe you'd have a few apis to a system you know your organization have you to manage and we're now switching into this place where a typical organization is looking at tens hundreds thousands plus many of many many apis that they're looking and managing and there's a number of reasons why we're seeing this big explosion of apis and this is not a definitive list but there's lots and lots of things and we can look at some of those so one that popular phrase breaking up the monolith and there is a talk afterwards talking about exactly how to approach that problem but if you think about how historically we'd have these big applications and there you'd have lots of different services that are available to use and you know moving through these Trends so things such as um service orientated architectures microservices or just generally recognizing that it's probably better to not have so much dependency in one application we're starting to see how some of these services are being split apart and there's lots of different reasons for that we get we're looking towards event-driven architectures so that means we're starting to think about asynchronous Connections so that in it turned naturally we're splitting things apart it makes it a lot easier if we can start splitting out obvious functions from each other then we can have separate teams looking after them better maintenance less dependencies decoupling all of those benefits and many many more another big reason is faster Innovation so as we're moving more towards product driven apis so we're starting to look at apis as ways of getting data for various things we're looking to work with companies can start to build out pocs so for example sort of proof of concept so for example let's say you are a taxi booking service maybe you want to get a Google Maps API which they're going to charge you for each time you make a call to go away and find out information about where somebody's requesting a ride or where your drivers might be maybe you buy a subscription to a weather data API where you can get information about if it's going to start raining and therefore maybe you start introducing surge charging and so forth so the idea is that you can start the company can start to bring all of these different things together they can test out a concept see if it works and very quickly iterate through and design things and then bringing these things together this idea of sharing resources is another big one so let's take data as an example so you sort of think about where sort of typically a large organization might have some kind of a centralized data structure so like some sort of business intelligence they've got this big Enterprise data warehouse or some sort of data Lake and if you're a department and you've got some interesting data what do you do well the uh the date the centralized data organization will go hey that data looks amazing by the way it's probably going to take a couple of months for us to go away and figure out how exactly we're going to sort of integrate that in and then you've got another department going hey that data looks amazing can we get that data and then you have the other process which then goes through where you've tried to sort of shoehorn your data model onto this centralized data model and then you go away and make a requested data and now we're in this situation where you know you've got each department each area within the business they've got the data knowledge that domain knowledge they've got the specialized models and they can go hey Department B you would like that data not a problem and I can start thinking about doing things like putting apis in front of slices of data and sharing it so you're getting this nice democratization of data across your organization and there's lots of other reasons why we're seeing an explosion of apis and these are just some of them and with the rise of the number of apis that we're seeing we are also seeing this rise of API first and last year Postman had their state of the API report and of the 28 000 respondents to their survey two-thirds of them said that they were either somewhat API first or they were fully API first so when we say API first what exactly do we mean do we mean we're developing apis before the applications and the Integrations are we saying actually we are defining and designing apis before developments what do we mean I think it's better to think about API first as a mindset or way of thinking and what we're basically saying is we want to treat apis as first class citizens so what do I mean by this if we think about historically how would you go about development you would build a big application of some description great so we've gone off we've built this it's got all the functionality and things that we want and then we're left with that question of okay how are we going to go away and now get this application this system to be able to talk to other things and then you have the challenge there where you're going to go away you build your API after you've built this application and then you're going to be stuck with maybe some hooks with regards to what technology choices you've made or what terminology that you use and what we're saying is that actually if we think about now everything in the project that you're working on will ultimately use apis either internally to different services that are talking to each other it could be business units so calling your apis it could be your external consumers regardless of how you look at look at it everything within that project will ultimately use apis they are the doorway to your services and functions that you're offering and as we're thinking about this maybe what we should be doing is developing our apis ahead of any other components so if we're looking to build some kind of web application mobile app let's think about those apis first to develop those ahead of all the other components and then continue with the rest of the project and this brings in a number of advantages so first one we start thinking about reusability because we're starting to focus our thinking about what is this what is this API helping do what business problem is this solving what pain is this pain is this going to resolve what data is this going to provide from a higher context it's going to start introducing this idea of usability so you have a well-defined well-designed API for your services they don't have the situation where you go well there's one kind of 50 covers it so let's go build another one you're trying to remove that and encouraging the reusability of components it encourages stakeholder collaboration because for you to understand what exactly this API needs to do you need to go and talk to all of your key stakeholders and they could be your product owners your business analysts maybe people within the business themselves potentially even the customers who are going to be consuming this if they're external to your external to your organization and of course your internal customers and also because we're doing this thinking ahead of time and we're thinking about what problems are we trying to solve we are looking at opportunities to lower app development costs because we're going to solve any problems that we might have thinking ahead of time so that when we actually get to the building stage we're less likely to have to rewrite big chunks of code so this talks about design first and design first is not always API for so API first is not always designed first so let's have a look at a couple of different approaches so the first one is code first and something to highlight quickly here so this is a a methodology a process rather than a set in stone thing so you've got one approach which is code first and we have a number of stages so our first stage is to get the business input so this is where we get all of the stakeholders together so we get them sat around the table and this is going to be our domain expert so people in the business who understand what what feature what thing this this API is trying to do as well as our technology stakeholders so I'll developers or Architects for those people involved maybe we're also going to speak to customers as well to come in and provide their input so we go away we get all of that input we get that understanding we do our brainstorming our sessions always required we capture all that information and then that is taken away this this input and we go and build our API and then once we've built our built our API we can then go away and create some documentation so maybe we generate the documentation off the back of our code so maybe we've got some annotations in there and the various supporting libraries that we have for that maybe we go off and write it maybe we've got some kind of hybrid approach where we bring those two together now in a design first approach when we look at API first we have that same stage at the start that business input so this is where we get all of the stakeholders involved to talk about what the requirements of this API is required and then we put together our API design we will Design our schema so design first may also be refer to schema first and this is where we then go away and create our API contract and once we've got our API contract then we go away and build our API so let's go into a little bit more detail here if we think about the design first life cycle so there we go we've got our design and discuss stage so this is where we're going away we're talking about what we're looking to do about this API we've got the stakeholders we're getting the input we're feeding it back maybe we're looking potentially at some wireframes and then once all of that's agreed we then approve our API schema or API model and what we can do because during that design and discuss stage we were also collecting information about things like well what naming convention should we use we've been collecting information as well let's give an example of what this data would look like what would the output look like when somebody makes a request what does a request look like and all of this can be put into your put into your API API schema depending what you use and we're going to talk for a couple of Standards you can then use the API schema that you've created and use that to now go away and generate your API documentation you can use the examples that you've specified in your schema to generate mocks that you can host you can also use that to create code stops and client sdks and what this means is that as a front-end developer you can go refer to the API documentation you can go off and use some hosted mocks mocks if those have been examples where you can go away and start for example building some kind of a front end to call those mocks and get some sample data back to see what that looks like you've got client sdks to help you uh quickly speed up what you're building the back end developer again has an agreed API documentation so they know exactly what they're building for you've got code stops to help build an approach and then we've got the automated testing side as well where because you've got an idea of what this you know what this spec is you've got some examples you can start building that process in as well for both the backend and front-end development side an interesting thing here is that those processes are happening before a single line of code for the API was written so some of the benefits of using this approach improved communication because we're getting everybody in from the get-go because we're thinking this sort of like API as a product API is the doorway to our project we're getting everybody involved who needs to be involved right from the get-go and this means that we're going to have this nice rapid feedback look from business and customers so and our technical developers as well so we're starting to think about what's involved with all of this do we have issues is there going to be an issue from a business perspective is there going to be an issue from an implementation perspective so we've got this nice loopback that we can keep going through and we can use wireframes if need be what are the right approaches and it helps fit in with this idea of product driven apis which is the trend so this idea of what purpose are we trying to solve here what pain is this solving this is the doorway to the service that we've been providing and it provides that better development ex developer experience so the fact that before we need to get started before we start developing we've got our API documentation we've got test data we can work against we can host that we can start thinking about um like Improvement around the any kind of feedback iterations and that in turn helps drive that parallel development so rather than the other teams waiting for the API to be built before they go and start building any front-end applications or that kind of thing you can have all of the developers working in parallel once the API contract has been agreed and we can inform enforce governance and security so if we've got some rules around what our models are supposed to look like if we've got some defined language that we should be using if we've got some thoughts around what security we should be thinking about such as any kind of authorization or any kind of access to the API we can start thinking about how that applies and I'm just going to give you an example of some tooling that maybe you can you can use to help with this and there's many many many tools I've just grabbed a few of them so you've got an example here so this is Swagger Hub so here for example you can imagine you've had all you've worked with all the stakeholders you've got an agree of all the designs that you all the requirements that you want and what the design needs to look like you've done of the work whether it on Paper Bits of Paper whether you're using some modeling tools you've done your collaboration and you can start sort of sketching it out here and what um Swagger Hub will allow you to do is you can start doing things like generating documentation off the back of the back of the schema that you're building it will allow you to host some mocks so that developers can start calling them and getting an idea of what that sort of Engagement with the API is going to look like and so forth and you can do things like enforce a standard naming standards and if you've got naming naming conventions that you're using across your set of apis you can use that as a as a repository and pull them back in so that's one example and that's using open API which is one of the common specifications for rest another example is maybe you want to go something a bit more visual so this is API designer so here this is an example of where you've got a click and drag tool where you can start defining you know what your resource is going to look like what properties what attributes you're going to have you can start putting in example data there and this is a great one where if you've got more non-technical stakeholders if you want to get them engaged and stop talking about what's going on we can start doing that and then with this you can either generate your open API specification or you can go away and publish this into an API Gateway and again you can start using those that generate mocks based off of the example data that you've provided documentation you get feedback like that got another tool here so this is async API studio so async API is a specification for asynchronous apis so think if you're working with things like Kafka and privatemq and so forth and again so this is a text based one again and again as you're working through and you're building out your specification the studio will do things such as validate your schema it will provide visualizations for any of your event flows you can uh preview documentation that kind of thing so you start to get flow over this but again there are many many tools that can help you to do this and help with that sort of wireframe and effort and just making sure that you've got it quite right before you start coding your API and I just want to quickly touch on a little bit on API management as well because I feel that when you're talking about design first and especially when you're talking about having many many apis that API management is a really useful methodology for helping you think about uh think about um aspects that aren't necessarily Core Business logic when it comes to your apis so we've got the Wikipedia definition up there I'm not going to read it out but very quickly what API management does is it's basically that methodology that thinking behind the life cycle of your API from creating it to publishing it to deprecating it and it allows us to think about things such as how do you manage how people are using your API both from a business perspective so if you're monetizing your API and you want to manage how often somebody can access it based on a subscription tier to just looking after how it's accessed from protecting your back ends perspective so preventing somebody from hitting your API too many times managing your identity and access management so how are people accessing your API are they authorized have they been authenticated looking after how developers are using the apis so how do they know to discover what's available where do they find the documentation how do they provide feedback and ultimately understanding how your apis are being used are they being used are they healthy and maybe try to detect some malicious things going on and the reason why I'm talking about API management very quickly in the context of API design is if we think about the anatomy of an API we've got lots of things going on and whilst some of these elements that go around the API so if we think about the APO and middle that's like our Core Business logic that it's serving or it's going to be you know providing the input on the output that we're expecting from our services we've got all of these different things that go around the concerns so things around maybe like security or monitoring and definitely things around protocol mediation so like if we're going from a rest to a rest a Kafka stream or something like that so all of these things aren't necessarily going to be key business concerns when you're thinking about design first and what purpose does this API need to serve but something like API management can say well actually you know what a lot of this stuff we can handle there's a lot of out of the box platforms that can manage this for you so don't worry about that let API management handle that that's something that we can put to one side and think about and then you worry about the core the core focus of what that API is supposed to do and again this is very common if you look at things such as microservices as well where you've got side cars that deal with the actual um you know the the the things about how these things are going to communicate with each other or how you know authenticate them and you just focus about that business logic within the API it's self so okay I've been talking about API first and design first a lot and this is a DDD conference so I'm hoping a lot of you have gone actually a lot of this stuff sounds quite familiar right so we've got this this big stakeholder input including wanting to understand the domain that we're working in so we're trying to think about this from a top-down approach so rather than thinking about how do we go from the application and kind of like glue all these things together we're thinking about what problems what what thing is the business trying to solve this is the purpose of this API and work back work downwards and get all that relevant stakeholder knowledge governance we want to try and think about what kind of language we're using we want to start thinking about how this is being accessed and users sorry insecurity and that kind of thing and we're thinking about ultimately business alignment how does this fit in with different things so I think that design first fits in really well with domain driven design because if we think about all of the approaches that we go through with regards to thinking about what is what are the domains what are the sub domains we're thinking about where do we want to focus our effort on understanding what we're building versus what we're going to bring in and buy and that kind of thing that effectively we can start twisting slightly how we use design first and we can say well okay we've already understand a bit of the logic so we can start to think about when we're splitting at apis where they fit and then continue that conversation down it's encouraging that collaboration with technical experts so we have to have technical experts there as well as a domain experts and again that's something what API first and design first really push for which is making sure you get all of that relevant stakeholder knowledge and experience in there to make sure that you're building something that is fit for purpose and again it's encouraging that common language based on the models being used so again that's something that can come in from that governance piece when we're doing design first to make sure that we are using the right appropriate language for each API that we design so wrapping up got the benefits of design first so improving stakeholder communication and we get rapid feedback from that so that we make sure that the effort that we're investing is right and we're building the right thing that it can support governance and security especially if we bring API management into the picture there as well and it can provide a better developer experience just because we know ahead of time before we write a single line of code what it's supposed to look like what the documentation is and can we test it out as well as encouraging parallel developments and the benefits that that brings with regards to the speed of project delivery and costs and again I believe that design first fits in nicely with domain driven design because again those those key principles of encouraging collaboration with your stakeholders supporting the use of a Common Language and that top-down thinking so focus on the domain not the application so thank you very much if you've got any questions feel free to reach out to me you've got my contact details here as well and otherwise I hope you have a fabulous rest of conference [Applause]

Channel: Domain-Driven Design Europe

Views: 9,277

Keywords: ddd, dddeu, ddd europe, domain-driven design, software, software architecture, cqrs, event sourcing, modelling, microservices, messaging, software design, design patterns, sociotechnical

Id: j0iYJ8X9Di4

Length: 24min 0sec (1440 seconds)

Published: Mon Feb 06 2023