 So this talk, why your API should fly first class, let's go ahead and jump into it. So a little bit of an agenda, who I am, what is an API first mentality, how we build APIs first, a build for two concept that I have kind of worked out myself over my engineering career, some tools and tricks for API first mentality, and then we'll finish this up, we'll answer some questions. So who am I, my name is Robert Ross, people like to call me Bobby tables, I am the co-founder and CEO of fire hydrant, we are an instant management platform and tool. I'm Bobby tables on Twitter, Bobby tables on GitHub, Bobby tables, you know, every pretty much everywhere with sometimes a hyphen and sometimes an extra underscore. So before we get into this talk, I think that it's very important that we're all on the same page. So an API in this talk is going to be a rest API access via HTTP, application programming interface, we're not talking about like the low level abstractions within code and how, you know, our software talks to itself. And then we're also going to be using the word actor quite a bit throughout this conversation. And that is going to refer to a person, an integration, or really just anything doing anything in our application performing actions. And finally, a front end is a JavaScript application that is talking to your API. So we live in a world where we have Angular, Ember, React Redux, and you know, a whole bunch of others out there still, that's what we're talking about, we're talking about that JavaScript app that's talking to a back end API. So with the terms all set up here, let's talk about the front end first. The front end matters more than ever actually in many ways. So dynamic front end experiences are extremely valuable and expectation from customers. We think that it comes from experiences with Facebook, Netflix and other large tech firms, the fangs of the world with the resources to really be able to invest in these complex front end architectures. It is not easy to build what Facebook has built and what Google and Netflix have built. It's a single page application in many ways with heavy JavaScript usage talking to these back end APIs, GraphQL, JSON, GRPC, and that's really, really heavy investment that they have made into these technologies. Facebook really react based on these experiences. And a dynamic front end experience gives the same sense of quality that a good thud of a car door gives. If you've ever closed the door of an expensive European car, it has a really nice, like AC thud to it. And it was interesting. This is actually a science. It's actually faked in many ways for a lot of cars. So in the 1980s, cars were built and they had that natural thud and it gave people the sense that that car was safe and high quality. And now a lot of companies actually have audio scientists working on the thud sound of a car door and it gives the perception of a sturdy, valuable car. No, I'm not saying that a front end experience needs to be faked or a front end experience can give the sense of a better experience, but it can in some cases and it can be perceived as a much more valuable and well thought out product. It's kind of a sad reality if you think about it. If your website just doesn't have a particular type of fancy sizzle to it, customers may think that it's cheap. So a website like this may provide a ton of value. Six ways my parents taught me financial independence. That's super valuable. But if we look at this website and like the word art logo, you know, you kind of lose that sense of value of value and quality. A dynamic front end experience, however, is a risk. And fire hydrants, my goals to not speak too much about fire hydrant, but we will use ourselves as an example. We're a young company. We're about two and a half years old. And we, you know, we were thinking, do we move this chess piece early? Do do we go and invest in a dynamic front end experience in the earliest days of our business? And after two and a half years and after working at companies like digital ocean and Namely, I've come to the conclusion that you should move this chess piece early. It is you should always start building an API first with a dynamic front end. So the bet we made, we made a bet in the first days of fire hydrant to build an API for everything. Since then, we've amassed over 130 public API end points in just over two years. That's a lot. That's a lot of API end points. We, we built a React Redux front end from day one. We, we have some, you know, HTML render views. We are a Ruby on Rails shop. There are a few that are, you know, choice, but for the most part, all of our application is a React Redux application. Every feature that they, that fire hydrant exposes in the UI actually has an underlying API that our customers can integrate with as well. So said differently, our customers can use all the same APIs that we use for ourselves. And that was a very conscious decision that we made as a business for the long term of our platform. Because an early goal of fire hydrant was to be an integration platform. And what that means is that everything our platform can do, our customers can also programmatically integrate with us. And if you're building an API, all really is you want people to be able to programmatically integrate with you, unless you have some like weirdos that want to read JSON instead of like a beautifully architected page. But I doubt that that's not, that's usually the case. But it's also meant, it also meant that we had to consider our API design earlier. APIs, they can't change. If someone programmatically is interfacing with your API, you can't pull it out from under them and change the schema or remove it or do certain things to it that would break their implementation. They've spent a ton of time integrating with you. Don't do that to them. And that's actually challenging as a startup because we are moving fast. We want to move fast. How do we move fast with an API that can't change? It actually means you have to consider a lot of things very early in the application design of the company. And then another thing that it actually changed is our database design. Our API's first mentality meant that we had to start accompanying for different actors. So remember person, thing, integration, all types of actors that can integrate with our API. Our database had to change just in the earliest days. And we also, again, we built a front end, accessing our API from the start. This created the need for a well-defined engineering roles. Early on, while we have people that can operate full stack, we actually don't hire full stack engineers. We explicitly hire people for the front end or the back end. And for some companies, that's scary. It is you want that person that can do everything, but we want those specialists. We want the people that really know that domain because it builds a better experience for customers in the end. So why don't companies do this? Most companies, I would say, do this. It's expensive. So building an API first and then building a front end is more expensive initially. The benefit actually of having that API early will almost always exceed the initial cost by orders of magnitude. Yes, you are going to spend more money building it back and building a front end separately that talk to each other. That's not, I'm not an ignorant to that fact. But if you want to build a mobile app and then release it, and let's say you're thinking this is two years away, well, do you want to build the API in two years separately and staple it on, or do you just want to have it now, have people integrating with it, and then when you go to build your mobile app, it's there. Customers that integrate with you are also way less likely to churn. And from a pure business point of view, that's very valuable. It is hard, it's much harder to get new customers to retain existing ones. There is a lot of reasons why like building an API and saying it's expensive is just not a good argument in the long run. It's time consuming. It is. But for us, we kind of sat down and we said like, well, we have a lot of faith that this thing is going to work and these features and this product and this company is going to work. Let's add to our risk. We're going to increase our risk profile and just spend more time. We're going to spend more time, we're going to build an API. If this doesn't work out, it doesn't work out. But we're around, we're two and a half years old, we are here to stay. And because we made that bet early on, we have so many people that now integrate with us and are happy with those integrations that we can actually say that was the right move to take. So my API first, I've said it a couple of times, what does that mean? And literally it means don't build a user interface until you have an API, literally. That sounds insane, right? How could you possibly do that? Well, here's a way to kind of think of this. Your API should be a bin of Legos. On the right, this is a pretty awesome Lego app from years ago, print ad, where it's kind of using the child's imagination. Like sure, it's two Lego bricks, but to the child, it's an airplane. And or adult like me, who still has Legos and still plays with them. But the point here is that when you provide an API with all these really, really well-defined API endpoints that can attach to each other really nicely and have nice standards and are very sturdy and solid, you can actually start building that airplane and have the imagination to build whatever you want with the given ingredients. And one of the problems that you kind of have to avoid here is when you start mixing your UI with your behavior, your application should have, your application will have a very hard time becoming a platform for others to integrate with if you have this mixed mindset of behavior and UI. They're fundamentally different things. And when behavior is exposed via an API, actors internally or externally, can start to imagine a UI for themselves. They can use the bricks provided to execute their own imagination, their own UI. And that's why Fire Hydrant has the backend engineers that those really, really experienced people on the back and building the API people in the front really experience of building these UIs and wonderful user experiences. So this doesn't mean building APIs blindly. I know that that's what I'm, maybe that could be interpreted, but really it's a breakdown of how we build and end result for our customers. And I'd wager that if you're in this talk, that you're probably what a part of a company that does something similar to this workflow and if you're part of agile, scrum, extreme programming, whatever it is, you have some level of product planning. You have feature specification, wireframes, acceptance criteria and the why you're building it. If you're actually at a very mature organization, that's a really important thing to include. Writing a story kind of comes next, might come from you, a project manager, product manager. It goes in Clubhouse or JIRA and it goes there to be planned. And then you have an iteration planning meeting, you have some assignment given when then and then engineering goes and builds that feature. And after engineering has taken wireframes design, the acceptance criteria, they write a bunch of code, they ship it. And then marketing delivers to customers via an announcement, you move on, you go back to the beginning, you do it again. The problem with this though is that this workflow tends to mix UI and behavior together. And it doesn't really work when you are trying to be an API first mentality. You have to break this down actually. And another thing as I mentioned before, this workflow kind of forces the need for a full stack engineer in many companies. And again, I'm not advocating against full stack engineers but for what we're trying to do by building a platform, you have to break down the way that you build software a little differently. So some of the subtle differences in the process break down here to build an API first. You have to have a different feature to composition. So we have feature teams at Fire Hydrant and one of them is our integrations team. We have UX UI design, we have Jax, we have front-end engineering, we have Hillary, we have product manager Dylan, and we have back-end engineering Justin. And then we also have a concept of we have our site reliability engineers and they kind of float around between the teams. They have mixed responsibility of site reliability as a whole. And so with this composition of a team, what we do is we'll have Jax work with Dylan and Jax will make a great design and this is from a real feature. This is an actual breakdown. These are real screenshots from how we broke down a feature of ours recently called Runbook Templates. And what Jax did is she used Figma to basically says this is what the information is going to be displayed. This is how it's going to be organized. This is the beginnings of the feature. And you can use a Sharpie, right? You could do this on a whiteboard, that's okay. Just presenting the information in some way, at least like with the information that you're going to display, that's the most important piece of this. Because once you know what's going to be on the page, you can start to kind of figure out, okay, well, that starter template over here, that's going to need an API, something coming out of the API to show that. We're going to need something to show the text here. What about this link, what is this? And then on the right, what happened is we created a ticket in Clubhouse to basically represent the information and the API that would need to be created to build this pick. So Dylan and Justin and another gentleman JP wrote this out and worked on it. And what happened is that back into engineering was able to deliver a API endpoint. So the API endpoint actually came asynchronously to the front end work. And this is something mind blowing, but this is really just how we think of our APIs and how we build them and why we do it. Because what's going on while this API was being built is the front end was also being built. And so Hilary is working on the starter template page where she knows that I'm about to have an API. Once the API is released, we're able to kind of mesh the gears together and then we low and behold, we have a create new runbook page with templates. And obviously there's a whole bunch of other API endpoints that come into this, but you get the general idea of how we break down our builds. So why is this better? It's not much different, right? Why is it better? Building an API first, it is a forcing function. If this process would never work unless every person on that team is on the same page. Things would break down very quickly because you're trying to mesh gears here. You're trying to mesh a backend and a friend amongst many people. It forces you to all be on the same page pointing in the same direction. Now we designed our future teams to be very tight knit in order to ship backends and frontends asynchronously. We do use Storyboard out of Airbnb's engineering team. That allows us to kind of plug in what the shape of the API will be early so we can actually continue to progress even if an API isn't actually done yet. And this points everyone on the future team in the same direction. That's very important. It also creates interfaces that your customers can now interface with. A platform that people can integrate with means tighter customer bonds. Again, if you have someone that has spent the time to program that like write code paying that high salary employee to write code against your API, that customer is much more likely to A, be happy and B, like less likely to leave you. It's just a better way of delivering value to customers that are really forward thinking and willing to integrate with you. It generates conversations. We've also noticed this amongst the team that would never otherwise happen. You really have to start thinking about the information on that screen. It's really easy for someone to go off if it's an individual full stack that's gonna be the front end and the back end or UI. It's really easy to just know what the information is going to be on the page because I'm the only one that needs to know. But when you have two people that need to kind of pay attention to what's on that screen, it generates conversations that would otherwise maybe not happen. So let's talk about a different concept now. Let's talk about building for two and how to build an API that lasts. So API access and why you should never tie records to users. API meant for computers. So while a user will make a request to your API from your front end, you must account for other actors. So that means that typically in an API, you make a request to the API, maybe it creates some data, a note, a comment, whatever it might be. That's usually associated to a user and a user only. That's how a lot of APIs work. That's how JIRA's API works. That's how Salesforce's API works. It's a very, very common pattern. But that's a problem actually because when you only have access to your API like that, it actually, it really restricts the integratable way. It really restricts the way that someone can integrate with that API because computers are not people. They're not users. They are bots, they're robots. Maybe they're integrations. You have to accommodate for multiple types of actors against an API. And you have to build in authentication and authorization nodes that allow for both people and programs to have a merry world together. Your underlying data model needs to change to support this idea. So some considerations for data model when you're building APIs first. Your data model needs to support the idea of multiple actors creating and modifying data. It has to do this. Most systems in my career and out in the wild, they have this concept of a God object, the user. Everything has an association to the user. That needs to change if you're gonna build an integratable platform because not users, people creating data all the time now. We have integrations creating data. How do you associate to an integration when your entire data model is only pointed at the user record? It's not possible. You have to break this down. So what I recommend is you can use polymorphism or a single entity with a type key on it to achieve this. So let's break those down. This is FireHydrogen's data model. Again, we have multiple concepts of actors, users, integrations, bots. And what we've done is we've made our database schema heavily polymorphic, heavily heavily heavily polymorphic. This allows us to store multiple actor types on records such as an incident. We are an incident management platform. So this is a snippet from our database. Actually, this is, you know, if you wanna build part of the incident table for FireHydrogen, here's part of it. So this is creating a table called incidents in Postgres. And at the bottom here, you can see these orange bolded keys, columns created by type and created by UID. Now, the difference here is that on a lot of databases, you would only have created by user ID. And that's a single ID and that ties to a user record. But what we're doing is we're actually having this type column to be able to say it's the ID of an integration, an ID of a bot or an ID of a user. So when someone creates an incident against our API, post V1 incidents, maybe they are acting on our API as a bot. And what we do is we say, oh, it's the bot that's authenticated against the API right now and they're creating an incident. And when we create the incident, we say, well, the bot created it, not this user. And that is, you know, this is one way that you can start to introduce multiple actors in that concept of build for two. When you start to build for two, you get to build for many. It's just a way of thinking. You don't have to build it explicitly for two. That's not what I'm saying. But I'm saying break out of the idea that items are associated to only one thing. It is a change that will fundamentally make your software more flexible in the future. I wanted to present an alternative data model. So at Fire Hydro, we've been doing this data model for a long time. And we've had some ideas on, you know, what would we do different? And I'd actually propose this nowadays, hindsight. I think this is actually better. You know, there's trade-offs to both, but and they both work and accomplish the same thing, but for the purposes of the talk and making sure that people come away with something interesting, I would do it this way now. I would actually have an actor's record in my database that's extremely simple. And then what I would do is I would actually make all of my other associations point to the actor. And then what I would do is I would make the actor record a polymorphic thing. And the reason you would do that is that it actually cleans up your database to the point where incidents, instead of having two columns, they can have actor ID, Runbook can have created by actor ID. And if you need to know, if you really need to know, was it a user that created or bought or an integration, you still have that foreign-gea association. So it's a little simpler, a little bit more flexible because you can continue to add different types of actors up here easily. So just a proposal, if you are getting something out of this talk so far, I would actually build it this way now if I were starting over. But both of these unlock the same things. So on the right side, this is a view from our application. It's a timeline. We store a timeline during an incident. So when you go into a retrospective, it's just readily available for you. So you can now separate the types of actors in your application with these. Not everyone is a user anymore. And that unlocks some cool things. So if you see, this icon represents that Daniel Connemity is a fire hydrant user, but this information was actually added by a Slack user. So different types of actors integrating in the same feature because of this data model that supports this. If our data model associates everything to a user via the API, what happens when that person leaves the company? This is a caveat, right? All of your integrations that you built with that user's account also break. If you think like, oh, if we have a software engineer that built all of our integrations and that software engineer gets an offer to another company and they leave, we deactivate their account and that means all the integrations down here also break because the API is not in requests. So you need to kind of break out of this model and support bots and integrations so you don't hit that type of scenario. The other advantage of this is that all of this information is still created via the same APIs that our front end uses. Nothing has changed that way. So another concept that comes in the build for two arena theory is you want to allow for many and constrain to one. What I say here is like think two features ahead. It doesn't mean that you're gonna over engineer something or over plan, but it's okay to entertain a feature that could like plausibly be built in the future. Possibly, I think that's a word. But a golden rule is it's okay for an array to have one element in it in your API. I know that sounds crazy, but if you're building an API and you have one association and you got, I'll just have the one association, you just add it to your API. Keep in mind, your API can't change. It's okay to have an array with one element in it. And I'll show you an example of how that has bitten me in the past. But it's a common mistake to restrict your JSON schema to a singular object. And then later on, you need to add another. Much easier to constrain to one in code, but allow for multiple in your database. Databases are very, very, very hard to change. It's hard to change a database schema. It is way easier to allow for many in your database and constrain to one in your code. Code is way cheaper to change. So let's talk about a story. I used to be a staff engineer at Namely. I was on the SRE team. I also built and led the core services and integrations team. I was responsible for all types of APIs internally, externally, a lot of responsibility for how people integrated with Namely. And this is a story about where Build42 would have saved me a headache at Namely. So if you work at a company today, you're sitting there, you probably have a manager. And logically you think, I only have one manager. And you would be right most of the time. But the problem is that there's actually a concept in HR called a dotted line report. And this is a snippet from Wikipedia, but basically what it means is that there's another manager in the organization that might need your attention and might hold you accountable for certain things. So if you think about it, Namely, HR company, we store your manager, your dotted line reports, we store all this information. And it started to build API that exposed who a person reported to. So API endpoint of the profile. So we can see here, this is an ID of a profile, the email of that person and who they report to. So ID 122, I report to Dylan at firehydron.io. So pretty simple, but you can notice, you know, this is a JSON object. This is a squiggly line. It is not an array. I can only have a singular reports to in here. Well, what happens if we were to have built this for two? So the JSON only supports one reports to field. Even though the product now supports multiple reports to the dotted line managers, maybe my colleague Dan is also requires my attention and is holding me accountable to things. He is a dotted line manager of mine. How do I report that in my API? So the situation is a worst case scenario because if our JSON APIs can't change, we built this API and people started integrating with it almost immediately. And we can't change it without a heavy notice or complete deprecation of that key in that API endpoint. It is a lot of work and time to do that. We could have avoided this. We had just thought like a couple of features ahead. If we just had a discussion about reporting structures and all that, like we could potentially avoided this. Reports could have been an array. It could have been, okay, the first element of this array is Dylan. And then the second element, if this happens, is Daniel with a type key called dotted line. This is better because it means that people that integrated with our API don't have to change their clients. It works the same exact way. And that's why I think people really should start considering like think two features ahead. You're not going to over engineer something to the point if you think two features ahead with some level of credibility that something will be coming up. So what have we built for two? I mean, these opinions are mostly from putting my hand on a hot stove over the last 10 years. I know I look like I'm a teenager, but like, this is the last 10 years. Early decisions don't always have to be got to go fast mentality. They don't. You can often build a model that will last you for years if you think two features away. What if we may have users now, but will we have companies? There is a really, I don't know if it's still out there, but GitHub has a story about this. GitHub used to be only users. And then they introduced the concept of organizations. It took GitHub nearly a year to support that concept. Not because creating organizations was hard, but being able to associate users to organizations was hard. What if we have multiple payment profiles? That's another thing that is very common in websites. You don't need to build the feature that will allow you to add multiple, but you should be thinking, we might need that and build your software to accommodate for that possibility in the future. So some tools and tricks to deliver great APIs. Document in tandem. So while we're building our APIs at FireHydron, we actually document our APIs in the code that is powering them. So while you're building your API, please or please document it as you go. No one wants to go back and document 100 API endpoints. No one. Use the OpenAPI specification too. So swagger, swagger.io, it will allow you to standardize your documentation as well as generate clients, generate documentation. It's a good standard to just kind of follow. Also called the OpenAPI initiative. Again, we are Ruby, Ruby on Rails core application. We have some go applications, you know, scattered around too, but use something that plugs into your framework that can generate OpenAPI specs for you. We use Grape, we've been using Grape for a very long time. It is the API endpoint framework that we use, and then we use Grape Swagger, which can read our API spec and Grape and actually generate beautiful OpenAPI spec compatible JSON. So really, you know, try to do this early. If you're not, if you have an API already, like please take the time, go back, document those API endpoints with Swagger, it really will be a better experience for, and even yourself actually, if you integrate against your own APIs. So getting towards the end here, documentation hosting. So Stoplight, Stoplight is actually sponsoring this conference. They are not sponsoring me. There are a few options out there for API documentation, but I personally, I recommend Stoplight and prefer it. They can read OpenAPI spec. They've done a nice job of that. They've been doing it for a long time. You said it, namely, as well. They can generate nice try-up pages for every endpoint. It's just a really kind of nice product. It does what it does very, very well. There are a few others out there. If you type in API hosting service, I'm sure you'll find that. So, you know, kind of tying all together. APIs have firehiger. They are a first-class feature. They're not an afterthought. We are APIs all the way down. All of our customers can access the FireHydrant API that our UI does. I joke and I say, if you just absolutely loathe the FireHydrant UI, you could build FireHydrant again on our APIs. We really are that open and honest about our APIs and the availability of them. And it's important because it means our customers get the same guarantees that our front-end gets. It's not an afterthought. It is the thought. Open API spec has also allowed us to generate documentation websites and clients with ease. We use our own clients within our application and also our integrations as well, such as our Kubernetes integration, CLI integration. They're all powered off of this open API documentation that we have built for ourselves. Developers.FireHydrant.io, if you want to check that out. So, what I'm going to close up here and hopefully this has come across, but build an API first. Future you will love you for it. Promise. And that's all I have. Thanks.