Automated APIs for Scaling Enterprises: How to Set Standards and Create Smooth API Implementations

Jeremy Glassenberg, DocuSign

API standards and schemas have helped to automate much of API design, implementation and maintenance — and not a moment too soon. As many tech companies experienced growth spurts in the past year, they ended up with multiple teams working on new products and new APIs. Consequently, they learned that their ways to create well-designed APIs wouldn’t work so easily when multiple teams have to create them.

Thanks to new solutions (centralized around a good API gateway), growing companies can establish a scalable system for designing, implementing and launching consistent APIs across many teams. We'll share best practices and solutions from experiences with enterprises in this phase to understand how to be effective working across Product, Infrastructure and Engineering teams to do so.


Speaker1: Hello, everyone. Welcome to today’s talk on Automated APIs for Scaling and growing and scaling enterprises. My name’s Jeremy Glasenberg and I’ve been working on API technologies at various companies, mostly B2B focused and including many, many unicorns and decacorns. And here we’re going to talk about the challenges that I’ve seen, not only from taking a company, from taking those companies who’ve just launched an API and set up a nice system of automating the planning and implementation of their APIs. And now getting to that challenge of a growing company that’s scaling those multiple teams, building APIs. And how do you position your APIs to scale? Let’s dive in first a little bit about myself. I basically been working on APIs for a little over 13 years now and a good variety of companies. I was a very early employee at places like box and Trade Shift. I was actually the first hire for the developer platform at Box, and I help these companies become unicorns. I’ve also worked at many companies that were unsuccessful, learn quite a bit from them and working with many APIs. Also as an advisor and as a consultant, I’ve seen many successful launches and successful scaling of APIs, but also many challenges and many failures as companies will grow their APIs. Today I am working at DocuSign. This is one company that years ago was very small, had one team working on APIs, and now it’s the $50 billion plus company over five thousand employees and is currently handling those challenges of scaling their APIs.

Speaker1: I’ve been working with them full time, but in the past have worked with other enterprises as they scale their APIs, and that’s what I want to get to today. So a little bit of an intro before we get into the topic of scaling our APIs. I first want to talk about design first API principles. Now there are many talks on this topic. You can find them on YouTube. Kong had talks in this just last year. So you can find longer bits on design, first principles and APIs. I’m just going to say that, well, I’m a big fan of design first principles and basically applying product process to APIs as a very short summary. This is basically about aligning your business model and your developer community with your API designs before you actually build them. So rather than design your APIs according to your backend, you ask What are the kind of apps you want to see built in your platform? Who are the developers? Who are you who are going to build this? What sort of challenges are they going to encounter and how do you make development is easy for them as possible?

Ok, I just realize we lost my screen share, so I’m going to mirror my apologies for the complication. All right. Let me just double-check here. Can you all post in chat and just make sure they just let me know if you can actually see what I’m presenting it now. Can you see my slides? Just person static you. All right, great, thank you. Just confirming I had to make a slight adjustment here. All right. One more moment here.

So I want to first start with that, I assume that your company is designing APIs according to use case, and you are designing our APIs first before you build them. If you do so. There you go. If you do so, you’ll find there are many tools available to automate that. I give a talk actually. Last year I kong. about this topic for those implementing APIs with design first principles. What are the tools available? And yes, Kong. is a big part of this. In addition to the Gateway, they have all of these tools to fully cover the product development process, helping you through Insomnia to design your APIs and write your API schema first, providing you with developer, Portal Builder and API documentation for when you’re actually ready to launch your APIs, providing you with monitoring to learn and iterate all of the components that you need to design an API first, implement, launch and then test your APIs are available through Kong and Kong’s ecosystem. But this really just steps one for an enterprise, for many of the startups, I helped. This is really all you need. Make sure your APIs are designed according to use case. But as the company grows well, APIs aren’t going to be designed by just one team applying product principles.

Most likely, you’re going to have segmented product teams, each of which need their own APIs. Some of those teams may not be aligned in terms of skill and experience and applying design first principles for APIs. But even if all of your teams are aligned, you may have well-designed APIs, restful APIs, but not APIs that are consistent across products. And then developers coming in will notice this. They’ll see inconsistencies in your APIs. They’re going to find they have to build different apps for each of your APIs. It’s just not going to run that smoothly. And we’re seeing this actually quite a bit from the last two years as well. We saw it in 2020 2021. The tech industry exploded and many unicorn companies suddenly became decacorn companies with thousands of employees. These same companies, some of them have actually reached out to me because they had gone from having one API team to having many API teams, and they quickly understood that once that happens, you have to decentralize your process of designing APIs. So how do you enable this? How do you let teams have the autonomy to plan their own APIs while making sure that your APIs are consistent? And also, what are the tools that can make this easier still? So at the highest level, I emphasize to companies who are scaling who have just encountered this, you now have more than one team working on your APIs. We’re going to dive into the steps to approach this properly, tactfully.

But it’s all about process, standards, communications and tools. You’re going to want to get these teams align on some sort of a standard to get everyone to agree, not just about rest, but other general requirements to make your APIs consistent. You want to also make it easy through tools and resources for teams to actually act on the plan because again, this has to be decentralized. And also, if not most important, you want to make sure that teams are communicating and collaborating and do what you can to make this easier. In general, this is done through what’s still a central API team, but not a team that’s dictating the rules. Rather, a team that’s facilitating. And so to do this was usually this one team that’s working cross-functionally cross-functionally across product areas to coordinate with all these teams and have them work together on establishing that standard. All these larger companies I’ve seen in order to be effective at API standards, they set up an API council. It’s facilitated by central team, but anyone who’s working on API gets involved. This is where you discuss and agree as the company as to what your standards are going beyond rest and saying What property names are we going to reuse? What property requirements are we going to have in our inputs and responses? How should our air models be structured? So we’ll have these discussed in the council, but to make sure that what’s coming out of that council is enforced? Well, the number one tool is the Linter.

The Linter is basically saying beyond checking your open API schema to make sure it’s nice and restful and proper open API. We’re going to make sure we’re meeting a bunch of additional custom requirements that we’ve set in that council. We’re not just writing it down somewhere. We have a way of checking automatically your API design and making sure it meets with our standards. Now you can set these rules in the councils, you can utilize tools like limiters to enforce the rules. But remember, we’re not going to have a central team dictating APIs. We need teams to have their freedom and responsibility. The autonomy to plan their APIs will so making sure they’re aligned. So a linter isn’t just about restricting your teams and forcing them to plan their APIs according to your designs. This is about making it easier to design and implement your APIs, while also making sure that each team’s APIs are aligned with the standards. The Linters once say. Working with Kong can work with the insomnia tool. So for those teams who are designing the APIs first, they can actually, as they’re planning their API and writing their schema spot in the linter, what changes they need to make sure their APIs are aligned, according to the linters. And then for engineering, after they’ve developed the APIs, the winter is there. In addition, in the sicced process to make sure that the APIs you’ve built are still aligned with the standards and a check for other things, this is all about just helping these teams make their APIs of higher quality more easily, rather than simply being a means of forcing an API standard on anyone.

And then coming back to communication and coordination, and this is another nice thing about tools like insomnia. As teams plan their APIs, they’re going have certain functions, certain models and more central APIs that you’re going to want other teams to get aligned on and by allowing teams to as easily as possible, share their designs so they can be reusable. You know, here at DocuSign, many of our APIs are centralized around documents, forms, signatures and we have models around this. And we want our other APIs focused on topics like workflows to utilize the same models so that developer coming in and working off the different APIs, they get responses in our APIs that are consistent. And it’s easier to do if you make it easy for teams to share their models and for other teams to grab those models and reuse them in API planning. This is something that tends to be added to API editors like Insomnia. Keep a lookout because this is one of those little components to the editors in addition to the winter that helps your team scale. So these are the key aspects to make sure your positioning yourself to scale. Have the council use the Linterton force. Would you agree in the council and then have those other tools to encourage sharing and collaboration? Now, tactically, you’re going to find that actually getting to work is much more complicated.

There can be a lot of little things and getting things from the council to being enforced to making sure app APIs are well tested to making sure each team test their APIs of high quality. Some teams may not be as good about this as others, so the solution make it easier through tools and resources. One challenge that I’ve seen frequently when it comes to creating API libraries, most companies today are automating this with a tool like Codegen, a library or SDK generator. I still agree that custom made homemade libraries are usually going to be at higher quality. But even the stripes of the world are automating this in many cases, because whenever you want to update an API, it’s nice to have the libraries nasty case automatically updated. You just update the APIs, and that’s it. You don’t have to manually update SDKs. Well, in theory, this works well in practice. Those of you who worked on worked with cogen or other generator tools know that these things are kind of janky. They require extra stuff that’s not an officially requirement for the open API schema. And if you have a centralized team that’s taking these SDKs cards and releasing them, which is common, well, there’s going to be some back and forth challenges if because those SDK generators aren’t going to work as smoothly as you like. So if it’s important to, in your validation process, have something in CICD to let each team make sure that they have in their swagger they have in their APIs, what is needed to generate these SDKs let them run those extra tests, not just make sure your apps arrest will not just make sure the meeting your lynch requirements, make sure they’re going to work with your SDK generator.

And so we’re talking a lot about the tools around your APIs to design them, to implement them. Let’s come back to the Gateway because, yeah, your API gateway really, really helps. I find it’s vital to for a team working on API standards, work with your infrastructure team and make sure that you have a standard requirement for the gateway that’s going to be used across your teams and the configuration behind it. I’ve seen this more than once as a consultant, a company that has grown. They have multiple API teams and they’re so disjoint that rate limiting isn’t even consistent and the developer community is taking advantage of it. How do you handle that? Well. Let’s make it so that your teams don’t have to think about rate limiting rules. Just have them all on the same gateway that you can configure. If you do this, then rate limiting will be consistent across your API. So it’ll be simple for developers and the developer community and the development teams working on your APIs, implementing your API. They just won’t have to worry about this at all.

And yeah, this also really comes up with off, I’m not going to name names, but I have seen more than once a team, a company allowing their APIs to get so disjointed that authentication and authorization are happening in completely different product areas in areas where most developers will want to work across products in one application. What are they? Fine. They have to write different codes to handle different means of authentication. They have to prompt their users to authenticate multiple times for access to different product areas. And sometimes security holes are open up because some teams didn’t align their scoping the rules and permissions with another team. How is this resolved? Well, again, if everyone’s on the same gateway, you’ve established them more easily the rules for authentication, scopes, and permissions and implement that only once in the Gateway and make sure it’s reflected across your other API implementations. You do it this way. You’re making sure your apps are secure, consistent, and a much nicer experience for developers to build apps that work across your APIs. And I go on and on about the benefits of the Gateway, of course, but besides or besides rate limiting. Among those top five issues, I’ve seen tactically and getting alignment across teams for APIs is how do you actually monitor APIs? How do you track what’s going on? How do you collect data to figure out how to improve your APIs? Well, if teams are building their own APIs, then you go to the data science folk who have to take this data from all these different APIs and bring it into a central repository.

In practice, this isn’t easy, either. Find the data science folk writing custom code for each API to get data, and they get inconsistent data into a central repository and then teams trying to enhance their APIs or the holistic API. They find they only have so much data and they have more data on certain APIs than others. Well, incomes in one gateway, which has a built-in, usually a built-in analytics tool in case they have built-in monitoring, they also have plug-ins for other API monitoring. So, yeah, every team is on the same gateway. And guess what? It’s now a lot easier to collect data, bring it into a centralized system in a consistent format. It’s easier in your data science team. It’s easier for each of these teams who have to implement APIs. You can set requirements for analytics and monitoring that are easy for them to implement because they’re all working under the same gateway.

All right, I’m watching the clock here and we had a technical complication, but I want to save time for Q&A and I still want us to go beyond the current rules to see what is available to smooth that process of scaling your APIs across teams. And let’s look at what may come in the future, because again, the challenge of scaling teams, it’s been around for more than a decade, but it’s become more prevalent the last couple of years, and a lot of the tooling around open API is new.

There’s still plenty of opportunities. I want us to keep thinking about what the future may hold. For one thing, I’ve talked about this in other sessions you may have heard in other Kong sessions, but the topic of schema decorators tools that can take an open API schema and enhance it. I actually coded one that takes an open API schema that’s just your API models and automatically generates the definitions of the endpoints, the crud endpoints, knowing that in most cases, API said the same crud operations under one object. And so this allows you to write the majority of your schema automatically. Now, these sort of tools is actually quite helpful in enabling consistency across your APIs by providing these two teams working on APIs and making it easier to get an open API schema out the door. And one that has some of your general standards baked in. There’s another tool swagger, and it has many purposes, but I have used it for clients who had a very loosely typed API definition where they just said that all properties, all inputs, all responses, they’re all just string format. Nothing is specified as date-time not being specified as Boolean. Nothing is specified in Int, and they start to see the limitations, not just in the developer experience for an API, but APIs are more likely to be inconsistent across teams if they’re not strongly defined.

The inflicter helps by taking loosely defined APIs and mapping it in a way to give you a little bit of a head start and converting an API to becoming strongly typed. By setting our APIs to be strongly typed through tools like this, you’re more likely to be able to to to establish see stricter but more solid standards that your teams can reuse. And let’s take another look at the Linter. You know, I always say whenever there’s something in JSON or Yaml format, you can probably put a UI on top of it. We’re seeing that today with API editors. They’re not just letting you dive in and type out your open API schema. They’re still giving you an input form or a nice mapping interface for which you can plan your API and then generate the open API schema. Today for API lenders, I’m not yet seeing this. I’m seeing it mostly written in Yaml or JSON, setting your additional rules for an API editor to check and say Here are the restrictions, but you have to write them down. You have to understand the format of the letter. You have to test the letter yourself. Well, I think in time we’re going to see the same thing we saw in API editors. We’re going to have a Linter editor. The Better provides an interface and tools to test your Linter and plan your Linter. All right. All right, so think I’m going to skip the last couple of what the future holds, but I encourage you all to keep a lookout and think, what can you do to contribute to the community to provide these four tools to better enable API planning, design, and implementation, not just for one team, but across teams? I hope this is helpful and understanding how to set standards, how to avoid it, dictating APIs, how to be friendly, how to share, but how to set those standards for consistency and how to keep those teams consistent and coordinated.

Thank you all for putting up with me for the last 20 minutes. We’ve got a few minutes left for anyone who has any questions. Anyone? Otherwise, I will just stare out there anyone who’s interested in working on a Lintern interface, let me know because I am working with a few different community initiatives to try to provide more of these automated tools to help with API design implementation. Oh, there is sorry, there is a Q&A section, and maybe I’m missing it here. Um, up there we go. Ok. Ooh! Yeah, I do see a few questions here, sir, for that you hold up there. Ok, so I see one what are some of the designs or methods use in terms of security for API to API communication? Um, you know. In this presentation and talk as much about security, and I won’t say anything specifically for API to API now, I’m not sure if by API, I mean, internal API is communicating with each other or writing intermediate code between your API and another API in general.

You know, when it comes to API security, I do emphasize the need for it, be the, you know, macroeconomic data on the percentage of breaches that are due to flaws in the API. And key reason for it is that APIs aren’t checked as well as they should. They’re not generally not checked as often. Security teams are often less experienced with APIs. And also, the tools that security teams use are not necessarily API focused. Now there are other talks about that, and there are many companies focused on API security today. So I’m not going to talk about that here. But I do emphasize that security holes can come up when teams are not consistent in their APIs, especially if oath is not consistent if they have different rules around authentication authorization and different expiration rules around tokens scoping. The one thing that I emphasize here is a have a consistent gateway and try to have everyone under the same auth rules that at least make it easier to watch if something’s going on. If their inconsistency is if there are inconsistencies in scope, it’s easier to manage with one consistent gateway. And that’s the area I would watch, making sure that each team is really thinking about their scopes, but also thinking about their scopes and context of how does this affect other teams were, I think, short on time. So whoever asked that question feel free to pin me on LinkedIn because I could talk about that for at least another hour.

If we have time, I hope we’re OK with one more question. Not clear on how you expect developers not to worry about rate-limiting resolution, you the capabilities and systems, which services these APIs. Um, so I may have been misunderstood on my note about rate limiting. It’s not they don’t have to worry about it all, but we want to make it easier for them through Gateway. It’s more managed and it’s easier to set your rate-limiting in a way that’s consistent with other teams. If whatever reason, a particular product area needs a different set of rules for rate limiting, that can be more easily discussed, but certainly alleviates a lot of risk and a lot of effort I find for gateways. Yes, it’s important to know the underlying system, but there’s also this comfort knowing that you have reliable tools underneath there. I think that is that we’re I know men over time with Q&A, so my apologies there. If I didn’t get any of the questions today, you have my name.

Try me out on LinkedIn. I’d be happy to connect and chat further. All right, I think that is all I’m not sure if we have someone here from Kong to close things out otherwise. Thank you again for your time and feel free to reach out to me if you have any questions. Take care, everyone.