Simplifying application development through API-first design methodology

Kevin Montalbo

Hello, internet friends. My name is Kevin Montalbo, and I'd like to welcome you all to another episode of Coding Over Cocktails.

In this episode, we will talk about the API-first design approach and its advantages, such as how it helps achieve a more efficient method of software design and how it helps developers quickly and easily understand how your API works and how it integrates with other applications. After listening to this podcast, make sure to visit our website at www.torocloud.com for after-discussion notes and blog posts related to this topic. 

Joining us today is Toro Cloud CEO and founder, David Brown. Hey David! Good to have you on. 

David Brown

Hi, Kevin! 

Kevin Montalbo

Hello! And also with us in this episode is Vivien Jovet, a Product Architect for Toro Cloud,  Martini Desktop, and Martini Workspaces. Hello, Vivien! Good to have you with us today. 

Vivien Jovet

Hi, Kevin!

Kevin Montalbo

All right. So first things first. Vivien, before we talk about the API-first design approach, let's describe the traditional process of software design. How does it typically go? You've been developing software for how many years now, so you probably have more background on this. So, can you describe it to us?

Vivien Jovet

Yeah, usually to design, to develop an API,  you can have a global goal for the API,  like what the API does.  So for example, you're doing, let's say, an API for contacts. So you're going to say, “Are we going to have contacts?” You can add them, remove them, modify them, query them, et cetera. And so, you're going to hand that over, that task, to a backend developer. And the backend developers are going to start working on it. So, they’re going to start coding. They’re going to start writing the classes, they’re going to start working on maybe the database schema. 

Then he's going to start writing the service layer. How does it communicate with the database? Then it's going to expose that on the server with the IRS controller. And then once it's done with that, maybe it's going to write some unit tests, some integration tests that are going to present the final output. And then, they're going to do some more tests, maybe by QA, and then if they're not happy with it, they're going to restart that process. And then basically do that until they get, they actually have something that they are satisfied with.

Kevin Montalbo

So, this is before the API first design approach, right? 

Vivien Jovet

Yeah, that's right. 

Kevin Montalbo

So, what were the problems that you were usually encountering? What would you say were the problems that you would usually encounter when you're following this process?

Vivien Jovet

Well, I would say that the main issue is the length of the iteration process, to get to the perfect API that you want, because every time you have to do changes, even just small changes, it's cascading until you have basically too many changes. Like, if you just want to change a field in your contact model, for example, you’re going to have to update the  database schema, you’re going to have to update your code, update your request, update your tests, et cetera. So, every time you want to make small changes, it involves a lot of side effects.

Kevin Montalbo

The traditional process has its benefits, sure, but it has some flaws as well. It prolongs the iteration process in making changes with the software and it takes a lot of time in going through each phase.

And for you, David, for someone who heads an organisation, how does this affect the productivity of your entire organisation? How does not having an API-first design approach affect your productivity?

David Brown

Well look, it's a totally different approach to not only API design, but services design as well. So, the transition towards services-orientated architecture and application design has meant that you break down applications into the components and each component performs a specific function or service. And like Vivien was explaining, the traditional way of building those services has been from that application layer up. This turns all of that on its head, and instead thinks about the user experience first. And when I say the user experience, I'm talking about the user who's going to consume this service, and then they use it. Maybe a person, or it may be another process and another piece of software and another system. Alright? 

But we now can think about, how does that user want to consume that service first? And you start working on that design philosophy first, before you do any implementation of the service. You then end up with a contract, a contract between you and the consumer of that service. And so you're bound by that contract and you both parties agree to how that contract should look, feel, and operate. 

And once you've got that contract, the implementation team can go away and build to their heart's content, using any system, methodology, programming, language, whatever they like. They know, so long as they're compliant with the contract, their implementation is entirely up to them, and they have the freedom to implement it according to their best practice, to their best knowledge, to the best of their ability, to what they're familiar with, whatever it might be. 

So, it totally reverses the traditional psychology around application development and API development. So, you know, from an organisational perspective, it's completely different and fundamentally different. And there are obviously major benefits to this approach.

Kevin Montalbo

Okay. So this approach, the API-first design approach, how does it make software design more efficient? What are its advantages? 

Vivien Jovet

So, the interesting thing in API-first design approach is you're gonna put a lot of thoughts on how you shape your data. So, the first step would be to define your domain models, and that sounds easy, but that's actually very important to define well from the beginning. And then after that, you're going to be designing how you interact with the API. So, how the user retrieves the data and updates it. And during that step, you're going to basically be defining what part of the data you're gonna expose, what operations you want, maybe what security you're going to use, things like that. 

And so you're going to be iterating over how your models are, maybe you will add operations, remove some, add some limitations to it, et cetera. And that's very efficient because that doesn't require any coding and that doesn't even need to involve a programmer. It can be done by a product owner and things like that. And it's very efficient because everyone can participate in that process, not only the developer.

Kevin Montalbo

All right. So, I've been reading a lot about this API-first, and it’s saying that it's prioritising the API first by making it a first-class citizen. Yeah. So what are your thoughts on that, or how does it become that first-class citizen?

Vivien Jovet

By making the API a first-class citizen, you're making sure that the user experience is going to be great.

I would say that the API itself is what's going to be used by your customers, by your users. So, by making it a first-class citizen, basically you make sure that the user experience is going to be great because that's going to be the first and most important thing that you're going to design. Because, the way it is designed behind the API, other than the performance, doesn't really matter to your users. But what really matters is the API and how great and easy it is to use

Kevin Montalbo

APIs as first-class citizens allow enterprises to build APIs that serve all the applications for which stakeholders have intended for the API. Developers will be better placed to create and maintain applications efficiently for all devices, platforms, and operating systems.

So, since we're looking at this at an API-first approach, an API as a first-class citizen, what are the characteristics of a good API?

Vivien Jovet

An API needs to be intuitive, meaning that when you're looking at the specs of the API, you can look at an operation and you understand instantly...

All right. So for me, first an API needs to be intuitive, meaning that when you're looking at the specs of the API, you can look at an operation and you understand instantly, “Okay, that operation is going to create a contact record,” and there should be no surprise, meaning that the operation does what it does. If you are creating a contact record with an operation, it should not  update anything or have side effects. It should be very intuitive. The second thing that I think is important is for your API to be familiar, meaning you don't try to innovate too much with it. Follow the standards, for example, RESTful standards. So, when developers are using your API, they’re already familiar with the way it works and the way it’s organised so it makes it easier for everyone. 

Also, it should be testable. So you should provide a way to be able to test the API in different stages other than production. As much as possible, it should be stateless, meaning that if you make a request to the API, the same request to the API should get you the same answer. You should have good error reporting, meaning that when things go wrong, you should have an easy way to know why. So, it should have a clear error report with it. 

And the last thing that's also very important for people to discover your API is that it should have really good documentation. So the entire spec of the API should be well-documented.

Kevin Montalbo

: All right. So David, now that we know these characteristics of what a good API means or what a good API is, we can probably implement a good API strategy. So, how does an API strategy or a good API strategy improve application integration?

David Brown

Well, application integration can take many forms. So you know, these days with the proliferation of RESTful API, as it is often consuming APIs themselves in application integration, but often it's not. Often you're integrating data files, which are written to disk. Or it might be databases, or it could be content sent through an email, or a different form of transport; FTP, or even chat. 

So, application integration takes many forms. The API contract is a nice way to facilitate application integration, because once you've done an integration, if you can wrap that integration up in an API, then you now have a contract on how to initiate that integration. So, it becomes reusable and it becomes discoverable, and it becomes something which you can embed in other integrations or services or workflows. 

Whereas integration itself can become part of a monolithic application design, or, you know, integration itself or workflow, and it can just grow and grow and grow and become a monster in itself if it's allowed to. By wrapping it up in an API, you've actually created a service out of that integration. And that service is isolated. You know how to talk to it, you know what response you're going to get from it, and you can embed it in other integrations.

It also means that you can change those other integrations, knowing what impact it's going to have on these dependencies, because they're all contracts or APIs. So that integration itself can change. And you know, what impact you're going to have on other services consuming it, if you change the API. 

So, so long as you don't change the API, then you know, you're not going to have any impact on it, but you might change to a different database behind that integration. For example, you migrate from a small database to a large clustered solution, different vendor, different brand. You might incorporate message queues, and the like, because your system requirements have grown significantly. 

You can do all of that behind your integration when you've exposed it as an API, because you're not changing the API - people interacting with the integration are still doing it the same way. Just your implementation of it has changed.

Kevin Montalbo

All right. So we have listeners in this podcast who are all handling the business side of the organisation. How does the API-first design approach benefit their enterprise or operations in the long run?

David Brown

How does it benefit the organisation taking an API-first approach? 

Kevin Montalbo

Yeah. 

David Brown

Well, I guess it benefits your organisation because with an API-first approach, you're going to get stakeholders involved early in the process. So, that is the consumers of the API are going to get involved from the outset of the project. So you get them all in a room, literally around a whiteboard, and you start mocking up the requirements of the consumers of these APIs and how they wanna interact with it. You know, what sort of request do they want to make from it and what sort of response do they expect from it. 

And those consumers, those stakeholders often have different requirements. So, the consumer who wants to build a say, for example, a web application and API may have very different requirements to a mobile developer who has to deal with a smaller payload, for example, than a web application.

So by getting them in the room and getting them involved in the design process early, it means that you're going to promote the awareness and use of the API. So once that API is completed, then first of all, the stakeholders are aware it exists, because they are involved. Now that may sound overly obvious, but in an organisation of tens of thousand employees with offices all around the world, you might have a great number of APIs, which can be discovered throughout the organisation. 

So by having the stakeholders involved early in the process, at least they know they exist. They understand how it works because they are involved in the design process. 

Kevin Montalbo

And the developers love that. 

David Brown

Yeah. The developers love it because it gives them a contract which they are bound to, that contract we're talking about before. They know that their service is going to be used. It has been, it's going to be used in the way the consumer wants to use it, and they can just go and build it. And then the consumer of the API will have some form of feeling of ownership as well, because they are involved in the design process. 

So, they're much more likely to use something where they feel some level of ownership as opposed to something that was imposed on them. “Now you've created this, it's going to do wonders for your department or organisation here it is, use it.” As opposed to getting them involved early in the process, giving them some stake in the design process on ownership, much more likely to adopt.

Kevin Montalbo

: Yeah. So I want to hear Vivien’s side about this because he's more in the development side. How does it feel if an organisation or how would you feel personally, if an organisation would prioritise using API-first and recognizing that, “Hey, APIs are actually important to the operations of our business.” So how do you feel about that?

Vivien Jovet

...the productivity with API-first design is just much better.

Yeah, so I agree with David, especially when you have multiple teams working on the same project. We've experienced this at Toro as well. We've done some traditional API development in the past and most of the time, you'd have the backend team doing the API. And then later on my team would be consuming it. And then we realized that it's not quite right, it doesn't do what we wanted it to do, doesn't work exactly the way we expected it or “Can you update it?” 

So, the backend team will update it again and then it might be wrong again. And then it's just going to go on and on and on, and we'd spend three sprints on it instead of having done it in one meeting where we would sit at the table, decide how the API should be, what the model should be, how it should work and get it done, agree on it and then implement it. So the productivity with API-first design is just much better

Kevin Montalbo

: With APIs as the building blocks of an application, adding services and technologies to applications is now possible without having to re-architect the whole system. This method improves productivity and allows more flexibility as developers can work with different APIs, all at the same time.

So, how can developers use the API-first design approach with TORO Cloud’s products? So we now have our ecosystem. I think we're about to launch a new one very, very soon. So David, how can developers take advantage of this API-first design approach with our products?

David Brown

Yeah, well in fact Toro Cloud’s products are entirely API-centric. Everything we do revolves around APIs. And so from day one, everything we've built revolves around services exposed as APIs and consuming APIs and publishing APIs. So, APIs are, obviously as a company, very important to us. And so the concept of designing APIs first as part of that design methodology or application design methodology, was obvious to us the benefits associated with it. So we incorporated API-first design abilities within our product suite, specifically Martini enables you to design an API, iterate through that design, create those services, contracts, supply security, mock responses so that stakeholders can play with the API and make sure that it's operating the way they expect. And you can do all of that without writing a single line of code. 

So, it's a very visual environment. It's a very, I guess business user-friendly development environment. We still expect a developer to be doing this kind of stuff, but it's the kind of thing you can iterate through visually and quickly, which is the idea in this kind of process when you're dealing with stakeholders to be able to iterate over the design quickly. You don't want to be building, for example, you don't need building services for example, to provide responses so that you know, that mobile developer, which is consuming the API can get a sample data set back from it.

You don't want to be building services to feed that data set. So, to have a simple way to be able to give them those contact records or some dummy data, something that they can play with. It's important to be able to do that quickly, easily, and without writing any code. So, we've got some nice tool sets to create APIs visually with no code and a playground for developers to both create it and for consumers to consume the API. So everything you need for API-first design is available within Martini.

Kevin Montalbo

All right. Thank you very much to my guests for today. David Brown, thank you very much as always. Vivien, we hope to see you again soon. 

On the next episode of cocktails, we'll talk about the effects of the COVID-19 pandemic on businesses, remote working, how companies can transition to the new normal and digital transformation. Again, please check out our blog on our website at www.torocloud.com and make sure to subscribe or follow us on whatever podcast platform you're listening to. This has been Kevin Montalbo for Coding Over Cocktails.