I think a good API and that's why nowadays. Finally, we all agree that API. First design is the way to go is, you don't want to expose your internal data models on your internal logic, too much on your apis, and the more new clients are not under your control, the less you want to do that. Hey everyone. My name is Henry Surya with Robin.
And you're listening to the technology, you know, podcast the show where I'll be bringing you the greatest technical leaders practitioners and thought leaders in the industry to discuss about their Journey ideas and practices that we all can learn and apply to build a highly performing technical team and to make an impact in your personal work.
So let's dive into our Journal. Hello, to all of you, my friends and My listeners, welcome again to the Tecla Journal, podcast, the show where you can learn about technical leadership and Excellence from my compositions with great thought, leaders in the tech industry. If this is your first time listening to technology, you know, subscribe and follow the show on your podcast app and on LinkedIn, Twitter and Instagram.
And for those of you longtime listeners, if you find my podcast helpful and want to show your appreciation and support my work, you can subscribe as a patron at package. You know, that death / Patron or by Coffee at technology. Not deaf /. Tip. My guest for today's episode is Daniel ljubka. Daniel is a software, architect and the co-author of patterns for API design in this episode. Daniel and I discussed some API design patterns and best practices taken from his book.
Daniel first, shared the importance of understanding the main requirements for building apis and several API, and message best practices such as API. First design, how to design Fine, Loosely coupled message exchanges. The trade-off between generic and specialized API operations and the risk of exposing too much internal data model in logic in our apis.
Daniel also introduced the microservices domain-specific languages or M DSL as an alternative to open apis, for specifying apis, independent of the technology implementation towards the end. Daniel explained the importance of defining the API life cycle. How to support backward, compatibility and the different API, versioning strategies, we
can use to evolve our apis. I enjoyed my conversation with Daniel learning about API design pattern and best practices specifically on some strategies, we can use to manage API lifecycle and evolution. If you also enjoy listening to this episode, please share it with others. Either your friends, or colleagues, who can also benefit from listening to this. Also leave this podcast of 5 star rating and review on Apple podcast and Spotify.
It will help me a lot to make this podcast discovered by other people on the platform before we continue to the conversation with Daniel, let's hear a few words from our sponsors. Are you looking for a new cool swag package? You know now offers you some swags that you can purchase online these wax are printed on demand based on your preference and will be delivered safely to you all over the world. We're shipping is available. Check out all the cool swag.
Available by visiting technology. No dot f / shop, and don't forget to break yourself. Once you receive any of those tracks. Hello everyone. Welcome back to another new episode of the technology on our podcast today, I have with me a quarter of one of recently published book title patterns for API design simplifying integration with Loosely coupled message exchanges as pretty long. So, Daniel Luca is here. He's one of the co-authors and
I'm really excited. Excited to talk about this because building API is something really important, especially these days and especially we will talk a lot about the message part of the API. So, Daniel, welcome to the show. Thanks Henry for having me on the show. I'm looking forward to discussing the book, The patterns messages.
So, Daniel in the beginning, I always love to start by asking you about your career Journey. If you have any highlights or turning points that you think will be interesting for us to learn from you. Yeah, sure. So, I mean, I'm now 43 years old. So there have been some positions. I've taken has been actually long journey. So I started programming when I was in fifth grade. So rather, Lisa, I got my first computer when I was 12.
I think back in the days, or compared to what we have now are very lousy Hardware. But nevertheless, start programming, very early, and even in school band, a team of five classmates, and we were developing a game which was released He successfully so you could buy it in the store on a CD-ROM back in the days and I think there was the first interesting point in my career because it was what a great
success was still at school. And everyone said you couldn't do it, but it was then about Team Dynamics was the only release game because the team fell apart after that, a little bit because they were different interests and different recognition of how good everyone is. So that I think was the first Turning Point. When I studied in German is Convergence informati can be translated business informatics, which is a subject which is very
German specific. So it comes close to Information Systems, I think, but it's more computer science plus economics. During that time. I also worked in very database having programming and the trainings and chanted, lots of computer science, lectures was a very great time actually.
Although one thing I learned there was that, Even though the company I did the projects and trainings, have a profit margin of proximity 50%, if you have a bad CEO, can still go bankrupt you to take care of your cash flow, even on private life. There was quite a lesson to see I come from Germany, I studied in Germany, I did my Master's thesis and in Barcelona in Spain, which was very interesting and then I came back and did my PhD back in Hanover my hometown, you to science and
the topic was so bizarre. Talking pictures. So really about, what we nowadays, call Api situation, choreographies back in the days of receiving some very different Tech stack. Again, I learned quite a lot there and then I moved to Switzerland because during my studies I didn't manage to go abroad.
Okay? And was one semester in Barcelona or someone to at least but I really wanted to stay in a different country and originally I wanted to go to England but it came Switzerland was kind for two years and was eight years there. Are so obviously, it's been a great time. Still a great time since I met
my wife. So there I was in large projects, very heavy on financial industry, obviously in Switzerland and too much complexity of In-House it Landscapes. So, the reality shock, which people get missed out and large organizations. And as a consultant, it's nice because move between different organizations, you learn many different ways of Designing systems. Different architectures. Different preferences by different teams so that was great and then I moved back to Germany.
Now I'm the CEO of a small elephant comes. That accompany myself which also interesting because now you need to do more coordination of people doing work, you would like to do, but still I'm interested in the technology, I'm still working in Project, which is important. So I think you can only be good in technology and Technology. Insulting if you still have hands on experience now so that has been my life in three minutes or.
So it's very interesting that you started to share your story about trading, computer games, I think it is almost like every childhood dream to come up with a game and you managed to publish and sell it in CD-ROMs. I still remember during back then I used this, get floppy disk but CD-ROM is like the Next Generation but I think it's still cool to be able to sell games when you are kid. So thanks for sharing that. So let's start. Your book.
So you have had a lot of experience in the industry. You have written thesis work in large financial company. Why specifically writing an API design book because API has been around for many years especially when you said about. So all right SOA and there's so many books already published as well. So is there anything different that you try to convey or try to teach us from your book? Yeah. And definitely thanks so much story. Behind the book is a little bit
longer. I can't go back some years. Ears all have to. My money is the first author and the team leader of the pattern approach. I knew him for quite some years. We met in Hanover, is interestingly, born in city near turnover. We hadn't seen as for a while, and then we met back in Zurich. He was in Switzerland. I moved to Switzerland. He became a professor there. And he was thinking about the case of what's, his line of research. And he was at IBM before. So also the mix of Consulting
with also doing his Ph.D Why is it a can want to have this idea? We are building all these Services we have and then back in the day microservices really the hype a building, all these enough and need to teach this to and I have corporations who needs to build a pi. So I want to something to teach. I at the time was new at a very large scale project where they are connecting land. Registries Banks notaries and some other parties across whole Switzerland.
So it's a system, we have like thousands Different organizations, connected and automating all these business processes. As you can imagine, there are many services meaning apis involved for doing vets Bank places. A request the platform, generate some documents sent them back to the bank so that they can do to the sign this. It goes from 1 to 2 and altering and then two advantages to add whatever you can do that. There were some people of every new to service design and we had
many discussions about things. I would have thought a basic but obviously they weren't. So my motivation was more for my daily work life to just saying, here's a pointer, please read this there and then we can have this discussion again. Yeah. So that was essentially how it started and then other people join Mike mackool to down and who I can't recall. Now exactly in which order but quickly became this team of five people who Vince is, are both
very experienced as patent. Office already will have an eye and mukul as well had some practical. More practical experience, although Olaf and was a professor and Merkel, actually, it's not as well. I'm still in Industry. I think that's the motivation. And then the question is, how do you teach these things? So I mean design architecture, always about decisions and decisions have these nasty aspects of that you get something, but you lose something.
If you go through the right door, you can't go left or but sounds easy. But people always assume there's this perfect solution. You just do some And it's perfect. And you do this every time because works all the time, the silver balloting and we all know, it doesn't work. I think you can feel fresh from University at least after three years, it doesn't work that way.
And patterns Make That explicit. I think that's so great because first, you have a name and I think we all talk about names as well, but you have this section about forces so what are the influences on your design? And some things are better if you use of certain pattern and some things are worse. So, You pay for your decision and patterns make this explicit. And that's why it's so great as both a teaching tool and also
reference to them. So, even nowadays if I'm and projects, it's just nice to go through on the pattern list, and check whether there's something I should have considered, or not, because it's always busy. When you're doing things, it's nice to have checklist, I always loved reading pattern books because it is practical, that's the first thing, right? And also, it kind of like this down the decisions of the Off some people say on why you choose a certain pattern.
So for example, if you opt for scalability, then maybe this pattern might be better, for example microservices, right. But obviously we know that microservices, not silver. Bullet in some cases, it might not work as well. So Fred Brooks have this right up last time. No Silver Bullet. So I guess it has been mentioned. Many times in any kind of architecture kind of discussion. I had in this technological episode, your subtitle of the book.
Also mentioned specifically about Loosely coupled message. Exchanges. So tell us more why you choose specifically Loosely coupled message exchanges as your
subtitle. Well actually the subtitle was one of the last things we decided and if we look at the book, what's special about this and closes the gap between high level books, like Enterprise Integration patterns which are not high level or very abstract, but they're certainly on a higher level of abstraction and then you have these books while technology. So how do I use the restaurant? Obviously graphql, whatever and what verbs to use and which circumstances, how do I build good?
You are wise and all these things in between there is something. So you have a conceptual API design. Something they decide. Okay, I need these kinds of operations, I need these quality attributes, and because of this, I perhaps to pagination a chunk things and not transfer whole message and that's independent integration technology, protocols use. The bike and my first project was a banking system or banking platform and they use Kaaba on the way was all Kaaba already.
There there were many patterns between still used today and more rest HTTP API is because it's a really long living and even now, whatever comes up next, you will have these problems. And people have these patterns, hopefully, addressing those problems. So it's not tied to any specific technology, first of all, so, You can make your API design on the conceptual level using this pageant and then shoot your technology.
So that's one aspect. The patient's themselves are not coupled to any technology themselves, but obviously, it's probably more about the coupling between API clients and API providers. I think a good API and why, nowadays? Finally, we all agree that API. First design is the way to go is, you don't want to expose your internal data models on your end. Internal logic too much on your apis and the more your clients are not under your control, the less you want to do that.
I think most patterns here will allow you to deal with this problem. So, how do I build apis, which? Well, if I do them by the pattern book, so to say, although it's not your goal shouldn't be to use as many pageants, but if you just follow these forces and things, then you will hopefully have a design which allows you to have these skills. Because Exchanges which are not dependent on the internal models.
So you mentioned something API. First design, I think this is mentioned, many times in fact, I think I have one episode James higginbottom. Also talking about that and in the book you also mentioned a couple more good practices for API design. So I think these days almost all back end developers will create a pi especially rest API or maybe gr b, c or graphql. Are there any other things that you would advocate for all these engineers? What kind of good practices they should do?
Or they should consider when building a pi or first of all you should think about how to express line. If you start with any software developments, just not only apis, but it's in general. You need to understand you two main thing, that's important. The problem with API is let's go back to this project. You have a team of people who, if you want to build a good solution or very good solution. Need to understand what the banks are doing with no to
recent doing what land registry. Join the interesting part is the last couple of hundred years. I mean, this domain is very old houses and government management of houses. Have a long time to land registry is around like forever. And banks are very old concept and notaries I think as well and over these couple of hundred years, these three parties still haven't learned what they are doing.
So that was very interesting, but bank doesn't know data model of Lent register, which is very interesting. It's surprising. So if you want to build apis for domain or for clients where you don't know exactly their requirements, it's the first thing we need to reach out to clarify this and that's easier said than done. There are a couple of approaches soon. First of all, you're doing workshops following first API version releases, try to evolve it but then you need to deal
with life cycle issues. So one part of this Loosely coupled is also you need to decouple the life cycle of your client and your Because you won't deploy a new version, similar tenuously. So he will have points in time, many points in time where they're different versions. So kind normally supports an older version and the provider role to new API version, which should be Backward Compatible.
So client, doesn't break. So let's kind of the ideal scenario while many people say okay, just built backwards, compatible apis. Yeah but it's not always possible. Sometimes you have breaking changes if You say okay, I don't know my clients. Well enough. I want to iterate and I want to improve things. It's more likely that you will
have breaking changes. For instance, Banks usually had one to many relationships where the land registry internally managed has many to many relationship these kinds of things. If you know them later on. So you have your API Define with one too many and now you need to support many-to-many, likely going to be a breaking change. Also, in your environment, that might be breaking. Changes. So Europe.
We have the Euro as its currency which before were multiple National currencies and if you had online banking back then to money transfer, there's no way of doing that. Now, I also was a breaking change that there's a Euro. I'm not on this local currencies, the same goes for count numbers, only have been local national account numbers and now we have the islands and international banking account number. So there will be changes new
environment, which will break. Can't do anything and there will be changes where you learn your domain better and where you can say, okay, in theory I should have known this already but you didn't the more you train to get to requirements and more, you need to think about your life cycle. Some patterns, we have there is, for example, we have an
experimental preview pattern. So you say, okay, let's say we roll this out and count, the I don't give you any guarantees, you can check this out, you can give us feedback, but it will break without us telling you. So that's not nice for the client. Declined also has some benefits
because you get a preview. So better version where they can use the API preview, it use it, give feedback and perhaps hopefully getting a better IPI down the road due to this feedback, even if it has breaking changes. And obviously some organizations are some developers will say, okay, no under these circumstances having only an experiment to preview, I don't integrate, I don't use this API which is fair because it's known. What's unfair is. If you say Say okay.
Here's an API and then you just say, I don't support it anymore, I break it in some way or another so being clear about your Evolution process, I think that's important so I have your own requirements, know how could you know them and then plan ahead because in the beginning you can. So if you just had a guarantee like we support this for three years and then you just try to alter this later on. People just come to your office and pick.
You probably these are decisions, which you need to do, as a As possible. And then obviously, you need to flush out all the domain knowledge in your API payloads. So yeah, it's always wise to start with the domain understanding first and in fact, things like DDD or domain driven design, is also something that Advocates you to actually understand the problem. First, rather than coming up with just the technology of the solutions people. These days whenever they build API.
The first question that they have in mind is definitely which technology that HTTP rest job, PC graphql and things like that. But Actually specifically in your book. You also cover the other important parts, which is the payload itself. You mentioned the messages may be for us Engineers here. Can you give an overview? What aspects that we should consider from the messages point of view? The payload point of view in order for us to design our API better?
Well, I think the most important part is how many requests to you have and how large your message payload is. So, if we look at that, obviously, you could make An API operation, which might be an HTTP resource. When you say get me on, give me our customers and then you get back our customers and everyone's happy. You can do with the data whenever you like this approach. Obviously has some drawbacks so much load on the API provider because needs to fetch all these customer.
If much load on the network gives you need to transmit all these customers. So we don't do this design. What we usually do is get a certain customer or search for customers - let everything we need to consider. No usually not. So if we look at the search even a search might return to many records. That depends a little bit on your domain on how many objects you have one domain objects. You have.
So if we have a service which would return a list of currencies, we know how many they are harmed. It's quite manageable. If we are fetching customers from any large organization, Apple Microsoft on the whole Salesforce data base, whatever you like, let's too much. So we need to have some Isms if we are running into this problem, to limit our spawn sizes so you can either say okay I only returned the first 100 hits.
I am might be a good strategy we could have pagination so I give you the first hundred and isn't sufficient. You can carry the next Sunday. We could also say, Okay, perhaps you need, not all customers, but very own sessions in the conference and that's a very huge conference. Like six hundred sessions to each session. You have some information like Like the title. Okay, just a string. Who's giving the presentation, like just a string, the image of the present.
So, that's obviously some large payload part. When I put this in my message, it depends on the use case but most likely not. I would just put a link to this image and whenever the client probably pops into the detail view, then it can attach this data is required. So we have these decision on whether we need to include data or whatever your reference data. Pending on your use case, you'll often have things which you don't need coming back to the Spurs line. Registries yeah, hundreds of
years of historical data. And for most use cases, you don't need historical data as so, it makes sense and one way or another, and there are multiple options address, what data the client needs and do many operations you could do some parameters, which there's a pattern called wish list. So I say, I want this in storage data or not, so such as a Boolean flag. And if you said it, you just get
back, 20 times. The data like would have, if you have known historical data and if it gets more complex, then you might have not only wish list but it was template where you can Define in your whole data structure and all the nested things, what data you want to have or not which thanklessly or easily gets you to graphql all purposes. Just to specify a request with exactly the data you need and so then many things you can do to adjust or trade off.
The number of requests and requests eyes on the response size especially and I think that's the point where we need to make more conscious decisions on average. I think most people just dumped on everything which they have and then it is certain point they just see, okay, well it doesn't scale, the database load gets too heavy and things are getting so slow, definitely creating an API and designing it. Well, the first point that you
mentioned is about data size. The payload size, do you return everything? Or do you include the large payload? As part of their first response, I think that's always tricky. The other trade-offs that I normally see in day-to-day experiences that some people don't know whether they should create specialized API, you know, things that work for certain use cases only or for certain customers only, or they should create something more
generic API. So, is there any kind of consideration that you would do to decide such thing? And when I do, it's has to interface segregation. Principal and it's hard. I mean if you look at graphql one extreme answer obviously. So just tells you I have a very generic API and u.s. client can specify what I returned and that's nice and sense because the client just fetches the data it needs can specify. But on the other hand it's kind of really key thing. Is you as a provider, you can't
optimize for certain operations. So if you don't have an index on certain database, Columns graphical request might be painfully slow and you cannot anticipate it on the other side. If you have many specialized operations you can very well optimize your database access patterns for those or caching
strategies and all things. So you can better optimize but obviously you have much more complexity different kind of complexity one is you need to implement a management different operations and on the other hand, you need to implement and deal with complexity of graphical and the Imitation behind this. So, again, this seems to be some Middle Ground. What I would recommend is to look at what use cases, you have in general, which anticipate.
And then to check, whether there is a certain amount of like 23 operations which would more or less cover these. Well, but you have to have like 20 different ones, then you probably should move on to graphql blowing something similar. And if you have just only one, then it's fine. As a rule of thumb, I would probably just after having three different specialized operation.
I would rather check whether it's an approach, where it leads me down the rabbit hole of having 20 in specialized operations in the future, but it really depends on the system. All right, thanks for sharing that because, yeah, definitely. It is based on the context that we have, but it's one of the struggle that we have. Another one that is struggle is actually to expose how much from our internal you mentioned
earlier in our conversation. That We should be conscious not to expose too much of the internal representation of our data model, for example, database schema. So how can we come up with a better exposure of our domain model as part of the API request and response. So maybe a little bit of advice here as well because I can see so many pitfalls people have gone into simply because they decide exposing data model unnecessarily. So maybe a little bit advice here.
Daniel. Well, I think really it's what you would call a pi first nowadays or put it differently. Should have a separate API interface, whether it's open API or something else. Well, in the end doesn't matter, but you should do that. You should work on this interface without working in parallel on your count.
I think it's one of the pragmatic things because if you're just working on your code and you have just pulled your database tables and you're building on your persistence land on these things, then your mind is Thinking in all these data structures well you need to be in very good developer to then switch over and say okay my API I want to have a more conceptual view so it's much easier if your brain is working in the conceptual mode, when you're doing your duty design,
new more involve counseling requirements discussions and the state of mind, it's much easier to build an API, which doesn't leak your technical information. And I think that's very simple trick, but it works. And you my experience. Yeah, I feel. It's a very good advice because I can still remember those days when I used to code a lot. So every time as a developer, if we start from the code, definitely it's very hard to still think about good API
design practices. Right because normally of course we always start with the data. We create a schema and easily or can just expose everything up to the API layers. So I think this is definitely not a good practice. So what you are saying API first definitely makes sense. Well it should. And that's also a thing State of Mind thing you should and it goes hand and hand. You should think from a client perspective and that's also something, which developers often do is you're building your
back-end code. You're just putting an API on top and you're doing what's easy for you because you have the service class there or this repository is already there. And you don't think about whether those operations placed in a logical sensible place or whether the data structures with emoji. You need to have here or whether the interaction from the client side. Makes sense or client needs to know too much.
I think if you look from more formal requirements or gt perspective, those three resembles looking from the client perspective and that's also state of mind. So again in your provider implementation, probably think about what you have there, what's easy for you but what you should really think about it. What's easy for the client because in the normal case you have like hundreds of your successful thousands of clients And only one providers.
You should optimize the development of clients and lot of yourself. I think that's really good advice. So always think from that API clients point of view not as a provider, right? So thanks for reminding that I also notice in your book that you came up with this thing called, microservice domain-specific language. Maybe you can elaborate a little bit more. What is this DSL, specifically and why do you create it? What kind of problems that it
tries to solve? Well essentially, you should do a podcast with Olaf about that because it's his baby. Probably I might be wrong. So, that's my trick knee in some blog posts or so, but I think there were two motivations for him. The first one is to have or to make patterns explicit in your API contract. So a pattern language, if we go back to this gang of four book that's probably one of the most successful books and
programming. Not because people nowadays by these books because they do Don't anymore, I think. But because the language is now deeply embedded into all of our programming, languages and Frameworks and things. And so that's why they're successful as a language and these names convey while whole Design Concepts in single name. So if we have Observer or listener, we know. Okay. Let's that and probably if we now talk about Pitch Nation, people know, okay.
I have an idea of what this means. And so one motivation was to entertain. Apis in the contract with okay. Yeah, I use pagination and that's a public API and we require an API key just as keyword of this interface language, the other motivation was to specify an API more independently of the technology. So from MDS Elna generators which will generate open API and they're also bindings for soap services and things. So it's independent of the technology.
I think. Probably all of my dick and correct me. It's much more concise. Less than let's say open API. Because if you look at open API is really, there are many, many lines you need to express things because every attribute goes into a new line. So, you have your data time, has a name, you know, it has some occurrences new line and test type new line. So, these cars are getting their long. Interestingly, XML, schema was much more concise in terms of
line numbers. I mean, both formats are probably shouldn't change in a text editor but you something we can deal with these formats but line one. XML schema was much more Compact and yes, L it has the least compactness, it's not XML, it's not Jason, it's more or less human readable language which is very compact. Very can also insert all these pageants and they can then generate code and your API interfaces.
And for the book it was nice because if we print it open API just have probably 500 pages more. Thanks for giving a summary of that, I'm sure if we get confused with the MDS L, I will have a special episode. To discuss about this. So that didn't I want to go through to the last section of API design patterns? Do you have any favorites that you want to cover?
Firstly, I will still very involved in the evolution section as we can assume please General remarks there because I think it's a section which is a little bit special and because all other patterns are very involved in the message, contents itself and evolution is a bit more out of the message. And I also have seen this many times at some companies, back in the day, they said, Account was done, our service oriented architecture and the only thing missing is all versioning
scheme. First of all, versioning isn't the important part in that sense? So let's just buy product, what you haven't considered as your life cycle strategy? And that's probably one of the most important parts you have thought. Of first, people are always good at bringing new apis and services into the landscape, but they are very bad on getting them out of the landscape. So, decommissioning apis. Or changing apis and managing the clients and the impact to
the clients. So there was quite interesting that a large insurance companies that are. And while we are more or less done with that, we haven't thought about the life cycle. Yeah, well, go back to square one. And that's why I'm thinking Belushi is important. And there are not that many things, you can consider, essentially, I have a question of how Backward Compatible, do you want to stay, which involves certain costs from you as a provider, which might make the API dirty? The time.
So, we refactor our source code on the time to make the structure better to make names better. Stay in backwards compatible means that I can't reflector many aspects of my API, because it would break. So many people just price in there for instance, or some attribute names without the unit that works. If you don't have a single unit, like what's your length, somewhere in the comment you see it's lengthen meters meters or feet price usually means the price and the car.
And see the main currency of your organization and that works. Well unless you have the software going internationally. So then you need to change that and then you cannot simply add a currency field. Is that would change the semantics of price, so there will be a breaking change because some let's say implicitly was priced in u.s. dollars. Now you have currency feel and all client reading price and doesn't know currency, then it will interpret this field.
Tell us which might not at all. So if you want to do this you need to keep price and then you define property price with currency. And you need to support both of these elements which makes you provide a code. Much harder more difficult to maintain over time because you have all these different things. When you have multiple ways of expressing the same logic, are transferring the same thing? Most real life cases, you just don't. To guarantee and less backwards compatibility.
And then the question is, how do you manage to your deprecated things and occasionally to? This would be one strategy for announced applications and also 42mm production things? You know, the strength to API versions active and you can then migrate over and then the older one will be gone in and outs timeframe or you just say from the beginning. Okay, maybe I guarantee you that for next two years.
But stable real time based guarantee and then Obviously, you can just pretend to be backwards compatible forever, which will lead to probably down the way to the deprecation approach anyway because at some point you will realize, okay, I need to do something breaking and then I just announced how this works. So basically these are the strategies and you can combine them.
Obviously plus the remainder previously talked about me say again I'm not really in production, just don't give you any guarantees and then you have covered everything and then you need to choose and pick one or a combination of these but you should do. This because it's not a question of versioning. It's a question of life cycle. You want to force the clients into certain life cycle? I think it's pretty insightful because for those Engineers who have developed their API for long.
There will be multiple versions, multiple iterations of your apis and this is where it gets tricky, right? How do you support backward, compatibility how far do you want to support it. So you mentioned a couple of patterns here things like for example 2 in production limited lifetime guarantee just like, how long do you want to support the API? And you also mentioned experimental, preview earlier, and one more is about aggressive obsolescence. So tell us more about this
aggressive obsolescence. Is it something that you force the client to actually just break? Actually, let's the deprecation approach. As long as it works. I stay backwards compatible and make it work for you. But I also have this mechanism of telling you, okay, we deprecate something.
And from on provider perspective, we will try to do this in an aggressive way because we want to reduce our technical debt at some point, we would say, okay this operation, or this data element is deprecated and And you have more like, say two months or a year, depends on office, your clients and power clients have over you or you have over your clients. We give a certain time span until they have to migrate, and if they don't migrate well, they will break, you will discontinue
this feature. So, let's put this aggressive as a bone. Obviously, we have other deprecation approaches if you look at the Java class library is things in there which are deprecated, like 20 years, or so, I don't know. So they obviously see. Okay, you shouldn't use that but we place a high emphasis on backwards compatibility which cost them for API, provide a perspective you want or you sometimes must be talk about the currency and count numbers and so there you must make breaking
changes. Sometimes you want to do breaking changes because you want to refactor things. That's what's placed on the aggressive, you know, want to give a sensible timeframe but you have a certain time frame when you will definitely face out some feature a little it of question about maintaining all these versions. First of all, obviously there's this Paradigm, how should we version it? Is it like version one version
to version 3? Or is there any other strategy things like semantic versioning and how do you actually test? If you have multiple versions that you have as an API provided? Is there anything special that you have learned throughout your journey to test all these different permutations of apis that you have? And, you know, we'll have a flame war on the comment
section. So, you know, that just by placing this topic, well, let's say there are two schools, one, laughs versioning, or having some kind of version. Identifier visible. In either your endpoints, are your URLs or in the messages being transferred. Perhaps, also the content type HTTP. And some people say, it's just the most evil thing you can do for my experience. I like to have some version
indication. However, Yeah, that you shouldn't place any logic so any business logic so if it's version to this field, prize means this and it's version. One of the sphere price is definitely and dollars or so let you shouldn't do. But you should be able to Signal some kind of compatibility. So let's say you have a mobile app and the user has an upgraded it or has an old operating system on its mobile and can't use your news app version.
You want to make an ism? You can say, probably this doesn't work and And just saying okay no you can't use this API if you know that semantic versioning has the advantage of indicating, what kind of changes you make, social these three versions major minor patch or fix pending on, who tells you
what this last digit is name. But it's very clear if you have a major changes breaking and it's clear that if you have a fixed version changes, just a minor cosmetic thing which shouldn't break anything on the client side. I think that's worthwhile to see So you have some possibility and estimating the impact of these changes. Now I think that's more or less answers your question.
So you have these two parties in the API Community, favoring or disfavoring explicit versioning and if you version, many people use semantic versioning to indicate at least some kind of compatibility. And how about testing those different versions that you have the you especially need to provide test cases for all Yeah, you should have test cases for all. What we did just referring back to this project is named very open and transparent and can very openly talk about what we've done there.
So that policy was yeah, maximum up to three versions. So when a new version is released might be 3 and the oldest one will then be taken down two years later. You see, it's a very not a jowl environment. Very highly times. So it means you have possibly three banking. API, version 3 land registry API versions and three notary API versions and the same process might be under the nine different API version combinations. So, that's pretty bad.
Actually, what we did, there was, we generated test cases. So, we went way of specifying the data, so on more business level, more specification level. And then we are generators on for creating messages, conforming to this different API versions. And See that's one extreme side of things not in all projects you benefit from the generation
because generation itself. Also cause something we have a different cost structures and you have more upfront effort and then things get easier if you just have two apis at saying version 1 and 2 when you release be you always have your test cases for a already there when you get them to cover version B, and if you find some point in time take down version a by whatever means for the Occasionally because you have to in production or reach the lifetime guarantee, then you
will also do the test cases and that also works for if you're saying we're keeping backwards compatibility and so going back to this currency example, and you have a test case for version a which checks. The price is working. If I don't send the currency with the price correctly as US Dollars and a test case which sends a different currency which could present the vision being so doesn't mean that I need to explicitly version things, but I should also have test cases.
It's just evolved my Pi without person identifies, so for people who are not producing API as like they sell the apis. Right. Sometimes Engineers tend to forget about this testing part, they always keep evolving for the new one, new versions but they don't realize that actually their old API or the older version of the IDE guide. There are still some people using it and whenever we make
these new changes it will break. So I think what you mentioned definitely makes sense rights for people to always have test cases for all the aps. Is that you still support? That is still life as part of your API provider. So, Daniel is been a pleasant conversation. There are so many things wrap up in the book. That thing is pretty thick, the way that I see it. So many patterns starting from the basic one, the fundamentals, what is API? What is the structure protocol?
And things like that up to the patterns? I think for people who want to build a better, if you guys, I would definitely recommend reading Daniels book but unfortunately we need to wrap up this episode. But before I let you go, I have one last question that I Many ask for all my guests which is for you to share what I call three technical leadership wisdom, you can think of it like an advice that you want to import for the listeners here to learn from your experience or Journey now.
So I think first is lead by competence. So if you take these by definition you're leading a team of Junior and perhaps in your people and you have people who are trying to say okay I'm higher in the hierarchy. So therefore my argument went that's not true in multiple They suspect behaviors one is, you're not really respected the team, so you're respected. Usually the development Community because you're good at something.
So let's one thing. So if you can persuade by bringing good designs and good suggestions and you're able to say why they are good well I've done this for 20 years, it's bad explanation. What if you can say okay we should do this here because otherwise I'll database a little too high. For example it's much better so lead by The other side of the coin is you also learn.
There's so many new things going on there and two new developers are very often much better and knowing the new stream versions deep in the technical detail. They're not as good and conceptual thinking hopefully but you can still learn things should be open to that as well. And if you just say, well, I'm the boss here and then you won't learn. Number two is keep on thinking. Well, people often just to not think enough about their decisions and And why they make
this decision? So we have like architectural decision records, or we can document, why we do something you can say, Okay pageants, make explicit what we want to achieve. And what we lose, it's really making conscious decisions about things and not just going along. And all the third is also hard for me to translate it seems probably will laugh. But anyway, so make the world a better place. So within your project within your team, within your company and probably will Product.
You were nice. It's so incredible. What you can do with software, what we can really achieve in this world, like I said, like in our team up to when things are released. So imagine you an engineer Tesla and at some point in time, you're the greatest auto pilot cars are moving by themselves. So how great is that? Obviously they are more boring projects but still even Whispers language, history thing is now moved back to Germany.
We bought a house last year and it was It's all on paper because my software there is no paperwork and here. Now I got tired of paper and then I realized it was not just boring administrative product, it really made people's lives better. And that's very satisfying as well. That's a very beautiful message. So make the world a better place. So yeah, a lot of Engineers when they do work.
Sometimes they don't think about what impact, or what values, they bring to the larger society, not just for the company or to the human, the people, the customers. Use the product. So I think that's a pretty good reminder for us to actually know and align. What, exactly the value, we bring to the users and the customers out there and best if we could bring it to the world, right? I think that's pretty impactful.
So, Daniel if people want to connect with you or learn more from you, is there a place where they can find you online insurance own Linton? Then you can so I know it's very International first name and painful moan Jim's because last time. So if you search within Huey, you'll find me on LinkedIn and on Twitter. Just t, look, if you want to read my blog gets on digital dash solution, Dash, architecture.com. I'll put those in the show notes, so thank you so much for
your time today. I really learned a lot about API design pattern and hopefully all the listeners here. Also learn a lot from you. So, thanks again for that. And thank you for having me was a pleasant discussion. Thank you for listening to this episode and for staying, right until the end, if you're highly enjoyed it, I would appreciate if you share it with your friends and colleagues who you think would also benefit from listening to this episode.
And if you're new to the podcast, make sure to subscribe and leave me your valuable review and feedback. It helps me a lot. In order to grow this podcast better. You can also find the full show notes of this conversation on the episode page, at Tech Legion o.f website, including the full transcript interesting. It's and links to the resources mention from the conversation. And lastly, make sure to subscribe to the show's mailing list on technology. Not deaf to get notified for any
future episodes. Stay tuned for the next technology, no episode. And until then goodbye.