AsyncAPI AsyncAPI Conf 2022, 5 Nov 2022

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Automating Governance for Asynchronous APIs - Nauman Ali, Stoplight

Description

AsyncAPI Conference 2022 - Day 3
5th November 2022

Style guides are one of the most effective tools to build consistent Async APIs, that follow best practices. Automation increases the effectiveness of style guides by making it easy for developers/designers to do the right thing. In this session, we'll go through best practices for creating AsyncAPI style guides and making them part of the CI/CD process.

A

Hi everyone um I'm Noman, so I'm a product manager at stoplight and I'm, primarily looking at the Epi governance piece, um Epi governance piece within stoplight here, um I know: API governance is a term, that's thrown around a lot and it has a lot of different pieces to it um from how your workflow Works, within your API design, how reviews work to actually managing and deploying apis and eventually deprecating them. So there's a lot of different pieces to it.

A

What I really want to get to today is actually automating automating, some of those some of those pieces and primarily getting into API Styles or style guides, and how you can potentially use them as an effective tool to to make API governance better in your organization.

A

um So before I before I get started with um before I get started with um or how to get into actually creating these style guides and using them. I just want to set a bit of context into why we're talking about what we're talking about and I took a quote from the state of API report that smartware does and standardized, and what it says is. Standardization is the number one challenge that teams building apis are looking to overcome this year.

A

Now, when we talk about standardization, it's primarily especially when you go on scale, let's say: You're, Building, hundreds or thousands of apis. How do you make sure that people across different geographical regions um and new developers or designers coming in make sure follow similar guidelines and your apis as an organization look similar so that the developer experience is called for whoever's, consuming it internally or externally?

A

And API governance like I talked about, has a lot of different pieces to it, but one General goal that um we're looking to achieve with all the processes that we build around API design and development is consistency. You really want to be consistent in the apis that you're building out um and while, while there are multiple ways to go about governance, some centralized teams or pushing it more down to the teams that are building apis.

A

Good API governance, in my perspective, was more about making the right thing to do, which might be following some different some principles or some specific guidelines or a workflow easy to do and how you can make it easy as I think that's the theme of my uh what I'm going to be talking about is automation um if you're automating the different piece of the different pieces of your workflow, your easier for people who are uh whose main goal is to build apis, make sure that they're doing it right and from what we've seen from customers within the community.

A

One effective tool to achieve that is setting up any API style guide. Be it if you are a small company, just starting out start with something small and Define. What good looks like in your organization, and especially if you are at scale you'd, want a style guide out there. Much like you might have a style guide for how you how you develop, apps or other things, just to make sure that everybody has a good sense of what best practices and what good looks like in your organization.

A

There are a couple of different governance strategies. What we have seen over the years for large companies like you'd, see Google PayPal putting out these. These API guides is a large PDF that might be a large PDF that might be that might contain all those different um all those different best practices.

A

The problem with that is that one there's it reduces the time to Market or reduces the time it takes for you to put apis out, because there's a central team that has to look at all API designs and make sure that, if that style, guide is being followed and feedback is always late in the process plus another piece being people who need to follow these style guides.

A

People who are building out apis need to read large in PDF documents, just to make sure what the style guide looks like, and now you cannot expect everybody to be doing that and it's just cumbersome General. So the other piece which is um would just come and gain popularity of late is automating some of these um some of these guidelines.

A

Now you build out these API standards and we'll talk about more about what these contain and how um how you can potentially make them part of your workflow, but the general idea being if you can automate some of these rules, your reviews go faster because feedback is much faster, maybe within the design environment and within your review process.

A

There's visibility across the board as to what those rules are when those appear and it scales well, especially in larger organizations, so the general idea being automate what you can and it's going to bring you a lot of um a lot of advantages over time, especially as you scale your program um just reiterating the point and how important automation is to a um API governance and we've seen that across different people that you talk to all right, so I'm I talked about this a bit but just to put into perspective.

A

This is um this: is Google style guide out there in terms of API design and what it is is a large website with different topics and how to go about versioning? What naming conventions to follow? What errors? um How do? How does Google do errors within the organization? This is great because at least there's an idea out there on what code looks like, but then again for somebody coming in newer buildings, these things out.

A

They have to go and find the right topic that they need an answer for and really really make sure that they read through wire before actually implementing it. Cumbersome takes time now what you can get to is the automated kind of style guides, which is on the left. What you see is a set of rules.

A

um These are built using spectral which supports both open API and using API and other Json things too, or other tools out there like open, API CLI from redoclay, um where you can, where you can codify some of these rules um and then run them in your CI, run them in your design, environment and get errors um as perfect. So if you automate and automate the guidelines itself, it really um like we talked about really makes your life easier.

A

So you could map what Google has as a PDF into some of these codified rules and run them in your make. It part of your process. Now now, we've I've talked about why you should be creating an automated style guide but big question that um that is certainly hard to answer in terms of like the complete.

A

um What should an API style guide include what everything that is include, but I'll, try and get it give a sense of some of those things that you can include in an API style guide to make sure that you're achieving the right things and, in my, uh in my perspective, I break it down into two um two different buckets. There are two different goals with these um guidelines, especially with um um with us as an industry, the API industry or people building apis, adopting open, API and async apis formats to write these design.

A

These apis one goal is to really churn out good API um specification documents, be it open, API racing kpi to make sure that the tooling that you're using you might be using a code generator or you might be using some other tooling, that are documentation generated to power, your workflow, so the quality of the API spec matters a lot and there's. This is one bucket of um uh one bucket of rules that you can create an example being some async API best practices.

A

First of all, you should have validation for your async API, so you're at least following the right syntax. When you're writing these, but then you can go beyond that and say all right. I'm I want only this version within my organization. That might be the latest async API version, um using a particular protocol, adding valid examples, making sure the operation ID is unique and adding information for like who the contact or is for this API and the license information itself.

A

Just you can go through the async, API document itself and say: okay, these fields are really important for tooling uh for what we do within the organization with these specs. So you create routes for that.

A

um The async API team has done a really good job of actually creating async API rules that they've been contributing to um within spectral. So you can go check it out, which has some of these rules already pre-built, so you can start with them and keep adding on to those to make sure that the async apis that you're building are really good quality.

A

um Another bucket another bucket within this, um this importance of building could API APS and kpi documents is maybe you're using a Gateway right.

A

So if you're using a Gateway you, there would be particular um particular nuances of that, like the Amazon API Gateway, not supporting one off within the Json schema or some X extensions that you might have for your code generation setup or your gateway setup again, you can codify these to make sure that everybody who's building out these apis, adding these Fields within within the document which really helps make sure that the tool in Downstream works well. A big goal of building these documents is documentation itself so make sure to add some documentation.

A

Rules like you should always have examples on payloads ADD descriptions. What what the length of the description should be- maybe add, a grammar or a spelling check just to make sure that the descriptions are not making type you're, not making typos within the descriptions itself, and if there are any other. If the deck writing team has any other requirements in terms of what good documentation looks like within your organization, you could add those into the rules itself and make sure that the documentation that you're producing is of high quality.

A

uh This is one bucket um and I think it's really important to build out these rules to make sure that your documents are high quality and the tooling works well, but then I think where it really gets interesting with these style. Guys and automating is some building out.

A

Some Epi design guidelines and I would look at it as the first level as maturity level, one where you're building out rules to uh make better API, open apis and API documents, but then going ahead and saying this is what good API design looks like within our organization and one bucket of it might be API URLs. Now every company wants to do it or does tend to do it differently.

A

There's no one right way of doing what casing you should use or what your url structure should look like but decide on whatever you want to follow. If you want to follow some particular company like say you want to you really like how stripe does it to take those conventions and build those rules out like what what casing should my parameters be? What should I completely avoid within my urls and um what the structure of my URL looks like now?

A

If you have a good sense on of rules on how your URLs are anybody, who's using your apis would find it far more intuitive as to what the next and what the next call might look like the next, the next piece, which is always a tricky topic within organization's versioning, and while again there are multiple ways of doing how doing versioning within organizations it's good to at least decide whatever works for well. For you and codifier so say.

A

If you want to go for path level, versioning or you want to do versioning within headers, whatever it is, make sure that everybody's doing it at the same way again the goal being consistency itself.

A

um This is the big one in a bucket that contains a large, thus I have all this I won't go through all of it, but the general idea being make security, a big part of your style guide and what I've, really? uh What I've really found helpful, is just to make sure that you're following or stops top 10 the rules there. You can create those rules and then go from there and say this is the security scheme we use within the organization HTTP basic. We stay away from it.

A

um We always add limits to our limits to our schemas in terms of a string. What's the limit of that um if there are minimum maximum properties and objects just to make sure that some of these uh basic security concerns don't fall through the holes, it's it's they're, um they're easy, but they're still easy to miss too.

A

um If you have some great limiting um uh conventions, you should add that too, and this this list can go on and on depending on what what the security posture of your organization looks like um error handling is another um another piece that you can add to your add to your API style guide, make sure you save in your style guide that you shouldn't be added and adding um adding errors into successful responses, but also saying that this is what your error object looks like, and what the popular responses error response is that you want to have um always within your within your API all right.

A

So these are um just to just to summarize data, but um there are two different buckets that you can build. Style guides out of, go to go to API documents and then go to API design uh codeify both of them and put them into one style guide that your organization as a general encourages people across the board to cross the board to use and implement. But one piece is building these out and it's it's certainly a big task to take up. But, let's say you've gotten the point where your style guides ready.

A

How do you roll it out? The first idea would be to socialize it within your organization using some sort of documentation. Considering this is enough. This is uh this. Is a machine readable specs that you're building a style guide and you can probably generate documentation for it, and some are down put it on um put it somewhere, where everybody can go, find it and look at what um how how style guys look within your organization.

A

This is just one more one to get the idea of the style guide out there into half conversations with people who are going to be actually using it.

A

um As to if this makes sense or not, especially in their use cases now, what the next step would be to bring it where your designers or developers are the idea being, instead of it being a document like we saw with Google style guide, bring it to your design environment, so, let's say you're using vs code or some other tool to actually build these async API or open API files out. You can bring those errors into the design environment itself.

A

So, as people are writing these specs, they can get get these errors and warnings within their environment. What this does is it gives real-time feedback. Much like you'd have es link when you're writing code. It makes it easy for folks to follow the style guide itself like we're talking about governance is making about making things easier, and this really.

A

This really puts it right where nobody needs to go and look at something to actually follow these, and you can divide them into some being errors, some being warnings just in case of what do you think about this Rule and the severity of it and people can choose to ignore it. This is more encouraging people to use their drugs than enforce I get, but then um the next bit that you can do is make it part of your review process.

A

So let's say you do your reviews on GitHub you're following that workflow, where somebody changes and chasing it changes. The spec makes a pull request. You can run these um this style guide within the pull request itself. You get errors right there and then have a conversation around.

A

Why is this not fixed, or why is this error here and if we need to ignore it then have a conversation around it, but the general idea of anything that passes those checks and those conversations can be skipped as part of the review process and you can focus more on um rather more important things and that's very good too. Do you still need to review API designs? Yes, but the review can now focus on business capabilities use cases. So what are you actually building rather than how you're building it or what the casing looks like?

A

Are you missing out in an error or not using the right um right convention when it comes to um when it comes to API design, so more about more about? Does this API make sense? Does this solve the use case rather than focusing on um what the conventions might be, so your reviews are more useful, they're, faster and um I. Think in building API is much better and faster too.

A

With this now, as a style guide is a really effective tool and I think um one that has good tooling around there to actually start doing this. But beyond that, what else can you do? And these could be separate conversations in terms of governance but having an improved diff system so that people can look at what has changed when as part of the review process in a better way and some sort of breaking change detection?

A

Just so that you don't you're not putting outbreaking changes without knowing about them, so make this part of the review process as to a better deaf, hopefully not Json or yaml, and some sort of breaking transaction?

A

And there are open source tools out there that do that and then going from there there's um there's a you, can build out a concept of a reusable API components: Library which might have models, parameters, headers error responses that everybody should use just to just so that people can get started with it quickly and keep reusing stuff rather than building it out, so that there are five different types of errors that your organizations apis, throw and templates being.

A

Another I think next step once you have a style guide, a good sense and what good looks like you have reusable components. You can put out templates and say async API documents and open API documents, saying if you're building this kind of an API use, this template get stuck with it just to make the process even faster than what it would be without these.

A

Thank you so much this is. This is what I wanted to talk about. Hopefully it was useful if you all have any questions. Let me know.