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.