Creating an API story with Mike Amundsen

Kevin Montalbo

Joining us from Australia is Toro Cloud CEO and founder and Cocktail’s co-host David Brown. Good morning, David.

David Brown

Good morning.

Kevin Montalbo

Also today we're joined by an internationally known author and speaker who consults with organizations worldwide on network architecture, web development, and the intersection of technology and society. He works with companies large and small to help them capitalize on the opportunities provided by API APIs, microservices, and digital transformation. He has authored numerous papers and books, and his most recent one is “Design and Build great web APIs: Robust, Reliable, and Resilient.” Our guest for today is Mike Amundsen. Hi, Mike, welcome to the podcast.

Mike Amundsen

Hi, Kevin. It's great to be here. Hi David.

David Brown

Good day Mike.

Kevin Montalbo

All right. So the starting point for most API development projects is to gather requirements from the stakeholders of the API. So how does creating an API story facilitate the documentation of these requirements?

Mike Amundsen

Yeah. So, one of the challenges of creating any API or even any platform microservices, anything is sort of getting your facts right in the beginning. And one of the things I talk about in this latest book, and then a lot of the material I have, is it's really important to think of your API or your services solving a business problem. So, getting the story right, understanding what the problem is, who the target audience is, what their challenges are and how you can measure success. How, you know, if you're solving that problem is really the first step. I was just talking to someone online about it today.

Sometimes that's seen as kind of like a bubble, a bummer. If you're an architect or a designer you want to get right into the code or whatever, but starting out with a good story, collecting the feedback, what is it you're trying to do? What are the actions you're taking? What is, what's the data you're working with? What are any rules or processes or tasks you need to perform, collecting all that stuff together. First in a coherent narrative that you can explain to anyone. It doesn't mean it's a technical story. It's really literally a story, really is the first step to creating those great APIs or great services that are really going to make a difference for your organization.

David Brown

Mike it sounds to me, it's a very similar concept to a user story and our task management approach. Is that right?

Mike Amundsen

Yes, it's very, very similar. I borrow a lot from the user story space and a lot from a behavior driven design in general, a lot of the same spaces. There are lots of other tools that collect the same information. Domain driven design has lots of processes or models, events storming by Antonio Brandolini is another way to kind of collect these things and capture them. Long time ago, I'm kind of dating myself, but we used to literally refer to it as ethnography going in and asking questions and interviewing, I use a kind of a combination of interviews and reflection and so on and so forth. But yes, it's the same general idea and all of these things are attempting to do the same basic task, which is to get a good sense of the domain of the language, of the challenge of the people you're working with. And that gives you a great story to start from.

David Brown

From what I read on your book and YouTube videos, it seems that the narrative though goes beyond storytelling and it actually seems like it's part documentation as well. You're defining entities and schemers and the like, so how far does the story go and where do you draw the line at technical documentation?

Mike Amundsen

Yeah, that always comes up. That's exactly right. So that story is just one of the pillars that I talk about. I talk about, modeling and then, designing and then describing as the three keys in the design phase. So getting that story writing and being able to reflect back to your target audience, whoever it is, whether it's general customers or someone internally is the first step that you're on the right path when they say yes, that's exactly what our problem is, then you're real close. The next step then is to take that narrative and turn it into a model. And those of us who work in user interfaces or APIs or code, we know those models. So we have to turn this problem into the model that matches our space. So, an API is I do things like, collect up the action names and, all of the data points and I create a vocabulary.

So, now I have a model that actually says you need a given name and family name and SMS number and all these other details. So, you collect all that up and then you actually do the design work of the interactions when you do this thing, you're going to actually carry this information in to get this information back. So, one of the key elements is to create a visual. So, I talk about diagramming. I use sequence diagrams, but you could use lots of other diagrams. So, this goes beyond sort of the lines and boxes that you did when you were first doing your domain exploration. This is actually writing out the sequence diagrams of the class diagrams. You could use UML there are lots and lots of other diagrams you can use, but creating a diagram is really important. That's a bit more technical and that moves us closer.

And then converting the diagram, the vocabulary and that narrative story into a machine readable form is what I call creating an API description in the API book. You could also do it as a canvas in services and that collects all that information and puts it in a real machine readable form that prepares to give to technologists and technologists can then do things like use OpenAPI or RAML, or, Async API or other sort of technological languages that match the implementation style of the actual technology. But by doing the modeling, designing and describing in that design phase, you've come up with a series of key assets that everybody can use at some point along the way.

David Brown

And presumably at that point in time, you start mocking the API so that the stakeholders can start interacting with it and seeing if it's behaving the way they expect it.

Mike Amundsen

Right. So, once you've done that design work, it is time to create that initial mock, that initial description that gets converted. If you're gonna use a RESTful style, you're probably going to use OpenAPI or Swagger. If you're going to use an asynchronous style MQTT, you'll probably use Async API. If you're gonna use SOAP, you'd use WSDL. These are all the actual machine definitions of an implementable version. Just like you can't take a drawing. And actually you know where it is clothing, you have to convert it into a prototype or a mock.

Then you do the same thing with your designs. You turn them into a prototype or a mock, and then that also gives you a chance to start writing tests right away. And now we've talked about now and just, you know, you and I, we've talked about prototypes, mocks and testing before we talk about code, right? We need all of those things before we start digging into the code. That's how we make sure we stay on track.

David Brown

And encapsulating all of this is obviously the API-first approach to development. Just like you said, we haven't written a line of code yet, right? There's no implementation of the services behind this API.

Mike Amundsen

Sketching the API interactions gives you a physical sense.

Yes, exactly. Right. Because that will come later. I often tell people the actual implementation is usually the boring part. The exciting part, the dynamic part, the creative part is all the things we've been talking about. All the design work and the mocking and the setting up the tests and all these other things where we're really exploring the zone. I talk a lot about the importance of both sketches and prototypes. Sketches are just really quick one-offs. I learned sketches from my colleague of mine, Ronnie Mitra, who talked about API sketches, and he in turn learned it from a great, physical architect by the name of Frank Gehry. Frank has designed fantastic museums and, and, concert halls and so on and so forth. And he literally draws on napkins and pizza boxes. He draws the doorway or the entryway or the hallway, or the vaulted ceiling, just to see what it would look like.

So, sketching out the login or sketching out the one of the screens or sketching out the API interaction gives you a sort of a physical sense. “Oh, it's going to look like this.” “Wow, that's too complicated.” “Let's see if we can reduce the arguments or change the URL” or something like that. And then the idea of building a prototype is like building a movie set. So, now you have a very detailed prototype. So, you're actually exploring all the deep details of logging in and errors and, and all sorts of other things. So, prototypes are super important. I really like, in the RESTful side, of using OpenAPI for my prototypes, but there are lots of ways you can do this. and there's a great analogy for prototypes in the garment industry. It's called making toile or a muslin. Toile is French for a canvas.

I've got some expensive gown or suit that I want to wear to, you know, the coming out party of the company. Maybe you're getting listed on the stock exchange. You're gonna have a big deal. Well, you don't test out using this expensive, gold lamé material. You test using cheap materials and you make sure it fits right, and it works all right, and you transfer that pattern into a test. That's what a prototype is. If you're prototyping a car or you're prototyping packaging, sometimes they're super expensive. You want to keep the prototypes cheap and simple. And then once you've explored all those details, then actually building it you can sort of turn it over to a build crew. And most of the excitement is gone out of it. You still have a lot of ownership in building it and building a great thing, but you've discovered most of, most of the dangerous areas. You want to discover all that before you order lots of girders and cement and dig a big hole somewhere in the middle of the city. That's the importance of this API-first and doing all this work before you write code.

David Brown

As you mentioned one word just now as “ownership” which I think is a very important part of this process as well, because when you're engaging stakeholders early, when it gets to that implementation phase, they already have ownership because they were involved from the outset.

Mike Amundsen

Yes. Ownership is super important. Also the lack of surprise, right? You don't want to just go in and walk into your new house and say, well, “How come there are no windows” “Whoa, I'm sorry. Did we forget windows?” Right? So not only do you have ownership, it's your house, it's your design. It's what you have been looking for. But you get to see it all along the way. You get to see it in the mocks. You get to see it in the prototypes. You get to see it in the test. So you've been watching it build over and over.

That's why when we build a house or a building or something, we keep visiting the site every week or two, we get to see the progress along the way. So, yeah, all of that's really important and ownership, not just of the original stakeholders too, but the designers and the developers and the testers and everyone is, you know, as part of that ownership as well because they're all in the process of putting all that together. So having all these assets, having the diagrams and the models and the prototypes and them and the sketches and all that collects up all of that material that everyone owns, that everyone sees as part of the whole process. So ownership is super important.

Kevin Montalbo

All right. We were talking about implementation. Let's talk about modification. What factors should developers consider when they're modifying their APIs?

Mike Amundsen

You're going to modify your API quite often... that's usually the sign of a popular or a well-used API.

Yeah. So APIs, especially most of the activity, most of the maintenance, most of the expense is going to happen after you release the API, not before. All of the things we're talking about just leads up to the beginning of usage. So, you're going to modify your API quite often. In fact, that's usually the sign of a popular or a well-used API. People start using it in ways that you hadn't thought of, start using more of it, more people start using it and you have to make some modifications. So, when you've released an API, that application programming interface, which you've really released as a promise, some people call it a contract. They're even tools for testing the contract of the interface. So once you've released that promise, you can't break your promise. So if I would need to make some changes, I need to make sure that I don't break anybody.

Now, if it's just you and I, and David, you know, Kevin as we're working on it, maybe I could sort of convince you to rewrite your code because I need to fix something. But if it's thousands of people across an organization, if it's thousands and tens of thousands of users and developers across the world, you're not going to be able to convince them that they need to change their code every time you do. So, one of the key factors is to make sure all of your changes are non breaking changes. We've been doing this in the computer industry for decades. TCP IP is like that. HTTP is like that. HTML is like that, right? We add all sorts of features or deprecate features without breaking existing implementations.

So that's a key factor in modifying our APIs, it’s following those rules. And I talk a little bit about a small set of rules for both, designing and then, implementing. And then finally, you know, releasing your APIs as well.

David Brown

And presumably versioning comes into this as well. So you can make breaking changes that are major version numbers.

Mike Amundsen

Right. A lot of people talk about versioning as sort of the key way of making a change. I refer to versioning the word I use as a fork, right? If we've worked on open source projects, you know that when you fork a project, you're actually divorcing from the original trunk. We're no longer applying a fix. We're actually going to fork it in some way, and it's not going to be compatible going backwards. Right ? So you can definitely do that. Sometimes you're required to do it. Maybe you're in a regulated space and all of a sudden the rules changed. You can't do what you used to do. You can't expose data or you can't have an operation. So you're going to have to have a breaking change. A lot of times it's unavoidable. So what you do is you fork it and you leave the existing service running for as long as necessary while you build another service.

And that's a real key part of the process. A deployment feature is you do side by side deployments. So the most stable way to modify APIs when you have to fork is to do side-by-side deployments. That way you don't force everyone to change all of their code by Friday, and then flip a big switch and hope the whole world works on Saturday morning. Instead you have multiple versions and you let people decide when they need to move and you need to be ready for the idea that some people will never move. We've got lots of customers who are using an API that solves one problem that API starts to add tons and tons of features that they do not care about. They're not going to invest more of their hard earned dollars to change just because somebody else has a feature.

So you have to be prepared for serving lots and lots of versions. Salesforce learned this years and years ago. Salesforce now releases three times a year. I think they’re in release 40-something. And they support all the way back to release 20-something. They support years and years of backward compatible API, because every transaction for Salesforce is money in their pocket. The last thing they want to do is take money out of their own pocket and cost you money. So they're committed to this thing about non breaking changes in using forks.

David Brown

A lot of people would never consider when they're starting out, they could end up supporting 20 different versions of the same API.

Mike Amundsen

Yup. Yeah. We don't really like to think about, you know, sort of the outcome of what it is, but every single product you can think of is like that of soap products, clothing products, consumer goods, cameras, lighting, computers - there are dozens and dozens and dozens of versions of these products that they have to maintain and support and keep up all the time. So we should be able to do it too. In the virtual world. It's actually easier for us than it is in the manufacturing world, in the physical world. So lots of versions is what we're going to do if we're going to make breaking changes in compatible changes. That's the way it works.

Kevin Montalbo

Okay. Mike, how are microservices breaking down traditional monolithic application design?

Mike Amundsen

Yeah, so, in the past, we can now even say like, at the turn of the century, we can say that because it was 20 years ago, we had mostly monolithic build. We would build an entire app and then mount it, whether it was online or local. But over the last 20 years, we started to break that into smaller and smaller parts, service oriented architecture, sort of broken into major pieces. Now in the last 10 years, microservices are breaking these things into even smaller pieces. One of the advantages of a monolithic system is once I get my request or my data into the perimeter of your system, then everything's nearby. The database is local, all the other functions, all the other classes, all the other modules, they're all local. And I don't have to worry a lot about network traffic until I want to give a response back to the client. That's a good monolithic system.

The challenge of microservices systems is I can't be sure that all of those tasks I need to do to fulfill your request are living in the same space. They might be on another machine. They might be in another part of the company. They might actually be run by some of the third party that might be hosted in the cloud by a major vendor. So, now I have to design with the assumption that everything is far away, that everything is actually connected by some network requests and that network requests might even go down.

So while I make my services smaller, I'm actually increasing my network traffic, increasing my possible risks. And I have to design in that detail. That's why the subtitle of my book is “as robust, reliable and resilient,” because you have to design your application now as if you've got various features far apart. Michael Nygard's book “Release It!” It's called “Release It!” It's got a great example of how to do these things with patterns he calls capability and stability patterns to deal with these small services loosely connected. So understanding that change from monolith to microservice is really about managing the network and managing all the possible things that can go wrong. And that is something you design in, in your application.

David Brown

And how are microservices tied into APIs for those that are unaware? So we have predominantly been talking about APIs and we've made this transition to talking about microservices. What's the relationship between the two?

Mike Amundsen Yes. So I talk about microservices and APIs in a slightly different way. Microservices typically communicate on what we call the east-west access. They communicate with each other, usually behind the firewall, or they communicate to some other service, and that comes back again. So, that's the first step. And they're usually very domain specific. I've got my account management service, my manufacturing service, my finance service, my customer service, but these individual services have very much a clear boundary and coherent APIs inside them.

But APIs, often you need APIs to solve a customer problem. So API is often run north to south. So, at the north end is the customer request. At the south end is the actual service that's inside the organization. They have a different set of problems. They're going to be a lot more network dependent as we were talking about earlier.

And those APIs need to solve customer problems, not your provider problems, right? So my provider API is mine. Microservices are usually generic data services, workflow services, some kind of internal, intellectual property that I have about the way I manage product management or something like that. That's not the customer's problem. Customer's problem is they need to know how many employees they have or what their sales are today. So often the API is cross domains. I need a little bit of security. I need a little bit of customer service and need a little bit of sales. I need a little bit of marketing. That's the request that I need to fulfill.

So APIs run north and south. They focus on security and often cross individual domain services usually run east and west, and they talk to each other almost in their own internal code, you know, their own object models, their own data models that are not shared by the customer. So making sure that you sorta know the two is super important, because that helps you focus on who the audience is and what their problems really are, and then what your risks really are, because they are different on the inside than they are on the outside.

Kevin Montalbo

All right. A while ago we were talking about the API story, that access, roadmap towards the development of an API. How about for microservices? Is there a roadmap that you would suggest to those looking to adopt microservices?

Mike Amundsen

Yes. Actually there is, and this roadmap that I talk about, it's sort of an evergreen story. I've been giving some version of this roadmap for a long time. And that roadmap is actually what I call the star treat under this, the star model. And the first thing you need to do is whatever your system is, whether it's a monolithic system or a SOA system, or a microservice set of microservices that needs to be updated or something like that. First thing you need to do is sort of stabilize whatever you have. Often that means putting in some stabilizing gateways and patterns. If you think about it again, using our architecture, our construction model, I'm putting in some footings, I'm making sure that everything's going to stay stable at the foundation. The next thing is I want to actually start to transform what I currently have into something else.

So, I'll pick a service, say, maybe I have this customer service, that does search in, customer management, data management, all sorts of things. I want to take out and create a new microservice for search, much more scalable, much more sophisticated. What I'll do is I'll actually just build just the search part and I'll leave everything else as it currently runs. So you'll make requests to the gateway and you'll still get all your regular services. But when you ask for search, you'll actually get a new service and you build each of these pieces along the way. Step-by-step eventually you can transform a lot of your organization. And what you can do is follow the rules we had before about not breaking clients. Clients will never know that what's happening now is they've gone from a monolithic system to talking to seven or eight services behind the firewall in your side, your organization, that's the roadmap.

The roadmap is to stabilize, to transform, to add new features when you need to, and then do a repeat cycle again, and you do this over and over and over and good organizations actually make this cycle of renewal, their business. That's what your business is. Your business is to constantly renew the services that you have to keep meeting customer demands, create new products, create new packaging, create new releases, all the things that we do in any product management, that's the whole process. You don't just build it once. And then, now that it's running, walk away and go to the beach for the next 20 years. You're constantly renewing. So that roadmap for adopting microservices is really the roadmap for continuous innovation in organizations. And I think that's really the way to think about any migration that you have is you're just continuously improving what you have.

Kevin Montalbo

All right. That's great. How about the challenges of taking a microservices approach to application design?

Mike Amundsen

Yeah, so I think probably the bigger challenges, we touched on this earlier, the notion of what is your design process, what is your design regimen? So, usually you have to start asking people to tell you all the things they do, and then you start putting boundaries or categories around them in some way, setting up the boundary, deciding what's inside a service and what's not is a real challenge and there's no science to it. So, you know, we have this onboarding experience, right? So maybe I want an onboarding service. Well, that talks to lots of other services. It may be in a bank. I might be talking to credit management or I need to reach outside and check someone's credit history and so on and so forth.

There's all sorts of little pieces. So one of the big challenges in microservices, people get really tied up in where they're going to draw their boundaries. This is inside the domain, that's outside the domain. And the thing is, no matter how well you do it, the first time you do it, you won't do it correctly. You'll come up with your best guess, your best understanding. And that's really important.

David Brown

And you’ll still get it wrong.

Mike Amundsen

One of the biggest challenges for people who are doing this microservice application design is they think they need to get it right the first time.

Yes, exactly. Right. David, you still get it wrong, but that's okay because you just build it and then you work with it and then you change it over time. So that's I think one of the biggest challenges for people who are doing this microservice application design is they think they need to get it right the first time. And of course, because we're going to be doing constant renewal, we're going to use that star method, that cycle of repeat. It's okay. We do the best we can, as we understand today, and then build that and then pay attention.

That really leads to the other thing that I tell people a lot about what changes in the microservice world, what's easier in the microservice world is we want to do lots of monitoring and measuring, you know, our organizations always have KPIs, key performance indicators, right? We think about key performance indicators, but there's also sort of the bigger picture as well. And that is your objective. What are you trying to solve? What are you trying to do? So every service needs to have a set of monitors, not just how much memory you have, or what's your uptime or your error rate is, but how many people are using the service? How much good traffic do we get from the service? How many errors do we get from the service? Because eventually when you're doing all this renewal, you're going to know which services you should invest in and which services nobody really cares about. I can go ahead and leave that alone.

So the monitoring is another key element that you design in, in your applications. So now you've got dashboards everywhere. So I talk a lot about dashboard culture. There's in this long list of checklist culture, for the last 20 years now we're moving to dashboard culture, knowing how long it takes to build a service, to mount the service, to run the service, to manage the services, all part of that culture.

Kevin Montalbo

All right, Mike Amundsen thank you very much. This has been very insightful. Thank you for being with us. Where can our listeners learn more about what you do?

Mike Amundsen

So, probably the best way to find me is my handle. It's M-A-M-U-N-D Mamund, @Mamund. So you can find me there on GitHub, you can find me on Twitter, you can find me on LinkedIn and you can find me on YouTube. I've just relaunched my YouTube channel. And in the last couple of months, we were talking earlier before we started about nowadays, when I don't travel, I used to travel 40 weeks a year. Now that I want to travel, I need to figure out how to reach out. So, looking me up, if you even just type in my name, Mike Amundsen on YouTube, or GitHub or LinkedIn or Twitter, that's the best place to get started. You'll find my books, you'll find my videos and I would love to connect with people, learn what they're working on, what's challenging for them, and then figure out how we can make that better.

Kevin Montalbo

All right. Mike Amundsen, thank you very much. This has been very insightful. Thank you very much for being with us. David, thank you very much for joining us as well.

David Brown

Pleasure.

Kevin Montalbo

Thanks again. You can also listen to our previous episodes which are available for streaming or download on your favorite podcast platform. Speaking of your favorite podcast platforms, what did you think of this podcast? Let us know down in the comments below. Also visit our website at torocloud.com to read up on our blogs and find out more about our products. We're also on social media - Facebook, LinkedIn, YouTube, Twitter, and Instagram. Just look for Toro Cloud. Again, thank you very much for listening to us today. On behalf of Mike Amundsen and David Brown, this has been Kevin Montalbo for Coding Over Cocktails.