Hi there, and welcome to my session on API first developments. So my name is Tiago and I'm the head of developer relations at Reli. io, where we're building the next generation internal developer portal. I've been in the industry for more than 15 years and I've worked in very large corporations like Microsoft, AWS, and PagerDuty. I'm passionate about solving problems with code and I love open source. I've been a contributor and a maintainer for many years and I really love it. You have my contacts here so feel free to reach out. I must confess I'm more active these days on LinkedIn, but feel free to reach out in any of them. So in this session, we'll explore API first developments in how it can supercharge your software's potential in unpredicted ways. And I specifically, wrote unpredicted ways because one of the things that I felt like more impressive in following this approach is of course, like there's a bunch of benefits, but the fact that you can easily adapt and build new, capabilities in front ends, is just impressive. So in this session, we will talk about the benefits, real world applications, and some of the best practices and things that I've learned along the way. So first thing. is what is API first development, right? And so there are a lot of, different definitions out there. And depending, who's talking about the topic, you might see some people focusing more on the design side of things. There are others that will focus more on the development. I will try to provide like a more agnostic, perspective to the problem. Man's. maybe a bit higher level, but this is the definition that I feel like resonates with both sides of the thing. So API first development is a strategy that prioritizes the design and development of APIs before building the actual application. So how does this look like, right? And so I'll start with, the approach that we have today, like the traditional code first approach. And this is just an example, right? And it might change depending on how you structure your teams internally. and. Basically, this example covers like a scenario where you have two teams, front end team and a back end team, that will need to work together in order to build this new feature, this new product that you are about to release, right? And how this typically goes, and this is my, of course, my personal experience, is when you have a new product that you want, a new feature that you want to release, you typically Start working on an MVP, right? And if this is like a product that has like a specific front end, if it's like a web application or mobile application or whatever it is, you typically start with the front end, right? And so you have the front end team that goes and builds like the first mockups. So some first, version of the API that eventually like a design team, shared with them. And so they start to write codes. You have all the nice. different components on screen. You can start to experiment with some of these scenarios, but there will be a point in time where, this team will realize that they need access to data, right? and so in order to move forward, they will need to create like a mock request or something similar to simulate the data. that is coming from the API, right? And so this will allow them to move forward, but they know that this is just a temporary thing. And so the typically, if this is a separate team, you'll see like in a very, in most of the organizations, you'll have, the front end team to create a ticket to a backend team, right? So this is something that will go, on the backend teams backlog. they are busy. and so you will need to wait, right? So as a front end, as a front end, developer building this feature, you'll need to wait for the backend team to be available. And this might be just a few hours, a few days. Typically it goes like up to a few weeks or something like that, right? And so the front end team will not be waiting, for them to, for them to build these API. that they have requested, they will continue to work right and add more complexity on their APIs on their front end, the development and basically, simulating these API requests that they will be making. So none of these will actually. call APIs or interact with real data. They will have mock data. They will basically have temporary code that they will need to work on in the future. But there will be a point in time where the front end team and the back end team will get together. to agree on the API contract, right? And one of the things that I've seen happen like most of the time is that the expectations from the front end team will not be met by whatever the back end team will need to build, right? There are typically like challenges in not having access to the data that the front end team wanted because the data just doesn't exist. or, there are some security, limitations. that the front end team didn't take into consideration. So there's. Typically the need to reinvent a little bit, the way that you access these, the data through the APIs, right? it's not necessarily the case like every single time, but it's something that I see very commonly happening. So they will agree on an API contract. And at this point in time, the backend team will start to work, on the specific, on the specific API, right? And the way to unblock the front end team as fast as possible, because at right now they will be waiting, for the API to be ready. so the way to do this is typically is through, the creation of a basically exposing an API mock, to the front end team, right? This takes time because you just agreed on an API contract. You need to create all the like the API specification, potentially provide some documentation. that's what you would ideally do. Provide some documentation as well. but just get something that provides like all the different endpoints that you would provide in the production, ready API, but it's just not connecting to the API still, to the database still, it's just using it. mock data, for the time being, right? But once you get that out, you'll publish that will be available for the front end team. And this is where, typically if there is like a huge difference between, the expectations of the front end team and the API contract that was agreed on. typically this involves a bit of refactoring. So you need to, the front end team will need to refactor. the existing codes to comply with the agreed API contract. And so the backend team will continue to develop because this is still an API mock, they will need to write the API code that interacts with the database, with the different data sources that you might have. They need to write the test. They need to write proper documentation and they will make it once again, available, through the intermediate environments like dev staging and eventually reaching production and the front end team will do exactly the same. and once that happens, it's available to, to, to the end user. or potentially available to the end user, right? So in this approach, you see a lot of back and forth, right? And that some important decisions like agreeing on the API contract are made in the middle or already throughout the process of developing and writing code. Which is not ideal, right? Because there's a lot of time wasted, on, refactoring codes. There's, like additional complexity added, to the process that wasn't, Necessary. So if we think about an API first approach, you'll see some tasks here that are common in common with what I showed you before. So one of the main things that changes in the API first approach is that we introduce collaboration way earlier in the process. And so you will definitely spend a bit more time in this first step where we are all working on the API contract. We all need to agree on what's. are like the use cases that we are tackling so we can get to the API contract. but the next steps will be much faster. There are no like. Waiting times. so the dependencies are reduced a lot. And so this is one of the advantages of API first approach. But let's look into this, this example in more detail. So in this case, I have a backend front end and the products owner, involved in the process. we could have designers and the UX team involved, in many other teams that might be involved in this specific feature. it's not just usually just the front end and the back end. That's why I represented the product owner as well. And so in the first step, they will all need to agree on the API contract. So they will discuss the use cases that the product owner. brings up front, they will discuss like how the developers and end users will interact with these specific APIs. And one of the reasons why I also included the product owner, in this first step is because in an API first approach, the API is actually a product, right? You should approach it as a product. So you would manage it as like your front end application, as your mobile application. it's a product, right? Even if it's not exposed externally for other people to use, should still be approached as, as a product, right? and so in this first step, you would, work together, you probably take a few days or weeks to get into a final API contract. But once that's done, you'll get the back end team already working on creating the API mock, and making it available to the front end team. And so at this point in time, the front end team Is ready and, actively working on writing the code for this application, right? At the same time, the backend is involved in and, basically working on, creating the production ready, API and the front end team is doing the same, right? So you don't have wait times. Since the moment that you start writing code, there are no more wait times, right? And there's, of course, like some back and forth because, when you start working on the front end, you might have some feedback on how, or like this API should return result in slightly different way or something like that. There's always the need for some tweaks, but you are working as a team. You are involved in the process of. Bringing these, product to your customers, right? so there's like less frustration in the process, because the collaboration started earlier. You all agreed on one thing. And so you build towards that. And in the previous example, That's not the case, right? Because you have the front end team asking for something, then the backend team potentially not being able to deliver that because of some limitations that are not even, their responsibility, but then front end team becomes frustrated. The backend team becomes frustrated and the end result is not the same, right? So in this case, basically you see that once the, the teams agree on the API contract, the process is more streamlined. So there's. still, collaboration, but it's more effective collaboration and the end result will be much better. so once they develop the features and everything's production ready, they will push the code to production in that code becomes available for the end users. So I feel like it's. easy to see the benefits of these approaches, right? And in order to get that, there are a few key principles to take in mind, right? I could mention a few others, but for me, these are the three main, principles that you should take into consideration. The first one is design first, second one collaboration, and the third one user centric, right? So for the first one, APIs should be designed thoroughly before implementation begins. And this is like the main ingredients for the success of the, of this process that we are talking about. So if we have some kind of things that weren't figured out during the process, they will show up. Later on, in these will cause entropy and then you need to go back into the design stage, right? So make sure that you invest the time that is necessary in the design stage So you can basically have something to work with and that leaves no questions for any of the teams, right? So this is really important. The second one is around collaboration, right? So cross functional teams can collaborating since the beginning of the process is also key. for the success of this operation, right? If you don't have these teams collaborating since the beginning, they will feel like they were left out and they are just doing tasks for the other team, right? That's not the case. Your API is a product and that API will interact with other products. And so this is really important to, to be clarified. And so that's why you should bring teams, really early in the game and then user centric. This is really important because sometimes, so we've all been there. we feel like we have figured out like the, what the users would like to see in the product, right? That's not always the case. In many cases, that's not the case at all, right? And so focus on the needs of end users, talk to end users, talk to potential customers, and talk to the developers who will consume the API, right? In some cases, if you are talking about like an internal API, these might potentially be the same. But if you are talking about external, an external API, that's not the case. exactly the same. And so you need to talk to people. You need to focus on what they are trying to achieve. Otherwise you will be building something that people don't want. And so they will not use it. That's as, as, as clear as that. but there are some benefits of course, otherwise I wouldn't be, talking about the topic. There are a few benefits that, and I just mentioned five of them here. These are some of the ones that I feel like are, more relevant, in the process. So the first one is on, parallel software development. So as you already, you already saw that collaboration is a big thing here. And I focus a lot on not having teams waiting on others. So teams working concurrently API contract and eliminating sequential dependencies is great benefit from my perspective, it's always challenging when you have people waiting for other teams and what you typically do is that, okay, these guys are really expensive. So you cannot have them just sitting there doing nothing. So you will put them in other projects. You'll put them working on other features. And this causes a lot of context switching for developers, right? And it's really confusing. It takes a lot of time for developers to, to that. So if you If you are able to streamline the process, it's way better, you'll get much better results. Then you have improved developer experience. So since you have standardized these kind of API, you have something that is well documented. you have, something that will, accelerate the developer understanding of your APIs. So this is really important because no developer in the world will use an API that is like not properly documented, that doesn't, that they will need to invest hours to learn how the API works. So that's not a thing. So focus on kind of standardizing, and documenting your APIs. to provide, a better developer experience. Then you have the accelerated development process. And specifying the API up front enables faster prototyping. So it's crucial for the front end teams in this case, to build their own, like their front end. for, for their application building on top of your A. P. I. And it's also a really good way to validate, some systems that you might be building some prod new products that you might be building or some integration with your A. P. I. So let's say you have a web application and you now want to build a mobile application. So you can quickly build a mobile application if you have an API exposed already, that provides you access to the data that you want, right? There's also the reduced risk of failure, right? So early API design catches potential integration issues before they become costly problems, right? So they, this, like identifying the issues. Earlier in the process makes it less expensive, basically requires, less rework. And, that's if you developed, develop some feature on top of an API that is not well designed, there will be like a lot of hacks in your code and that you need to basically, remove that during the rework process. And if the developer that built that feature. doesn't work for the company anymore. It takes a lot of time for other people to learn, what they've done, just, to cover, the limitations of an API. So focus on designing your API properly and making sure that you identify the issues earlier on. And then, of course, the optimized development costs, we already touched on, the rework part of it. so the fact that we focus on, designing the API properly, from earlier on, basically minimizes the rework that is necessary. Reduces communication overhead, right? So if we are building on top of an API that is well documented, we don't need to talk to other, to the other team. So it's time that we are saving. It's time that we are saving the other team as well, right? And it also prevents technical depth. So once again, if we are building acts on our, codes just to cover for, some kind of limitation on the API side, it's always, it's always something that, is not great in technical depth is one of the main problems that we have, these days. that is preventing many companies from moving forward and adapting, more interesting processes and technologies, right? try to avoid that. and now I just wanted to give you some examples. I'll start with some examples from, from, Relia. io, so the company that, I represent. And, so we follow this API first approach, and this actually allowed us to develop further integrations, in a much easier way. and we actually were, able to onboard more customers to our platform because of this. So I'll give you, like five examples of things that we have done or are actively doing. at this point in time, building on top of our API, right? So first one that you see on the left is a Kubernetes operator, right? So we built this Kubernetes operator after identifying that this was a common pattern, for the customers that we were onboarding into our platform, right? So companies using Kubernetes. using GitOps that had everything as code. So we could actually populate with the Kubernetes operator. We could populate our software catalog in a much streamlined way, which allows us to save a lot of time. So instead of have spending weeks, making sure that the software catalog is properly mapped and everything's on boarded and all of that, We could do this in hours now, right? So it's just a matter of making sure that Kubernetes operator is properly deployed in your Kubernetes clusters. You have all the definitions, your, blueprints deployed in your environment. And we are automatically getting this information and it's getting synced. in real time. Another thing that we, started working on is actually a Visual Studio Code integration because one of our values is to be where developers are. And so if you can, do most of the tasks to interact with, with rely directly from Visual Studio Code, things like, for instance, executing a self service action or actually see information from your software catalog, related to your specific, to a specific service that you are managing, it's much, much easier, right? So you don't need to move into, to go into the web browser to actually see information about, your services, right? You also have Terraform, of course, builds on top of our APIs, and we use it to provision, new environments, and. The next one is on Raycast. I don't know if you know about Raycast, but Raycast is basically, it's basically a launcher for macOS and soon available, in iPhone and Windows as well. but basically it's something that allows me just by clicking command space to interact with Many applications integrations that I have in one of them is rely. io. So I can see, information about my services directly from basically any screen. So I'm, I can do it from my, from a desktop. I don't need to open. Visual Studio Code or a browser or anything like that. I can interact with, Reli. io directly from my desktop. And of course, like everyone else in the world these days, we are also investing in AI, in AI agents. And so we are building that on top of our REST APIs. And one thing that I must mention here is that we haven't changed our APIs, to, support any of these integrations. so of course we are adding new features, we are adding new endpoints and all of that, to allow new scenarios and new features that we are building. But we haven't changed our APIs just to support any of these, integrations, which is pretty cool because you can just quickly, in a couple of hours, you want Build a VS code integration, interact with extension and integrate with our APIs and with rely without any problem. So that's pretty cool. and just a couple of examples from our customers as well. So this was before we actually build our Kubernetes operator, but we were onboarding a customer. that already has, like a Kubernetes operator framework running. They had blueprints for things like, teams and systems and domains. And so they had everything that they want in code that they wanted to send to rely. So why reinvent the wheel? So they just made a quick change on the, on their Kubernetes operator. and they started sending this information to rely once again, using Gaur. using our, APIs, they were able to do this in a couple of hours and everything is kept in sync at all times. Right? And the other scenario is another customer that wanted to integrate, a security platform that we didn't provide, a built in, plugin, for yet. And so the option here was, we can either. They could either wait for a few weeks or months, depending on our, prioritization, or they could integrate with our REST API. And so what they did was that this security tool, was, basically, tracking security, security violations, in their, in their platform. They would send this information into Logstash and Logstash would basically parse. That's, that information in send it to rely. io. This was only possible, because we had a well designed REST API that is flexible enough to accept all types of, blueprints in our platform. and because of our extensible data model, right? So this allowed them to just in a couple of days. implement an integration that we would potentially, take weeks to deploy in, in production in our, plugin catalog. So these are two scenarios, real scenarios from customers, and this is actually, something that, we are, using with other customers as well. So as you can see, like the Kubernetes operator, we actually, are using this to onboard other customers to our platform. because we learn from the customer, use case and we are implementing this and using this with our, with other customers. So some of the best practices here, very high level. So the first one is defined, clear, and concise. API specs, right? So it's really important to follow the standards, right? So there's a lot of documentation out there on how you should build APIs. so the naming conventions and using the right methods, giving the right HTTP return status. So all of those things, right? Define clear, Concise API specs. It's really important. Keep API simple and easy to use, right? So don't go, overboard. just once again, focus on the standards. If the API is not simple, people will not use it, right? So just make sure that it's easy to use. It's flexible enough. And, you'll have developers using your API. Otherwise it will get more challenging to get adoption. The third one is on API documentation, right? So API documentation is really important. Even if it's just like the open API spec that you provide to developers, just make sure you have it. Please do and there are a lot of tools out there that allow you to generate these documentation in an automated way, like the open API spec and code snippets for all your specific methods for different programming languages. There are a lot of tools out there that will allow you to provide top notch documentation for developers. prioritize that. Documentation is really important if you are looking to get people to adopt your API. The next point here is around automating API testing and validation. So it's really important to have this information or the APIs tested properly. If you are doing APIs that are just exposed internally, like impact is not that big when compared to having external APIs, but still it's really bad experience if you are providing a product to a customer and the product is not working properly. And so focus on having automated tests for your API and make sure that, you have a lot of tests and good tests actually that test something and test the behavior of the API, right? The last point here is around, monitoring API performance and usage. It's really important. Specifically for external APIs to monitor the performance in the usage is a really bad experience when you have an API endpoint that is taking one or two seconds to return a result, right? So you should keep the latency of your APIs. to the minimum possible, it should be fast. It should be simple to use, but it should be fast as well. And you can only know if they are performing, if you monitor the performance of your APIs. Also, you should monitor the usage of your APIs. Once again, this is important for internal, usage, internal APIs, but also for internal, for external, APIs, because with external APIs, for instance, you will start to see some new trends, some new, some new usage of your APIs, right? So you will see people starting to create integrations with, let's say, DevOps, let's say Azure DevOps integration. They are calling your. endpoint from Azure DevOps to integrate, with, directly the pipelines with, with, with your products, for instance. And so this is something that you will need to monitor the usage on. And so you will learn about new scenarios that you can potentially prioritize during, your, process of deciding where to invest your time next, right? So this is really important. So it's not only the performance, but it's also the usage of these APIs. It will allow you to define where you invest your time to get better returns. And so one thing I want to make clear, I mentioned this a bunch of times already in the presentation, but one thing that I want to make clear is that the focus of building an API as a product is that you must focus on the developer experience and usability of the API at all times. No more APIs that have a bunch of tricks to call them properly. APIs have been designed for many years now. There's a lot of best practices out there, a lot of standards out there. It's just a matter of following them. So it's not like you need to reinvent the wheel at all times. They have already, invented a lot of people have invented this. And of course there, there's always new things coming up, but most of the things I would say like 95 percent of the work is already done, so just, read about it. and, follow the standards and just a quick recap. So we close this, so adopt an API first approach. If you are looking for improved collaboration, faster time to market, greater extensibility in better development experience. So these are. Some of the things that I feel are really, important in the goals of the API first, approach. So if you see, if you follow this approach, you will see, some of these benefits really quickly, right? And just a call to action. so consider API first approach in your next project, something that would like to challenge you on. and. Start small, iterate fast, and you will see the great results in the end. Thank you. you have my contents once again here, feel free to reach out, in social media and, see you next time.