API Documentation Best Practices: Embracing a Shared Definition and Downstream Tooling

When it comes to API documentation, it's essential to keep things programmatically in sync and connect downstream tooling to a shared definition. This can be achieved by using a format that includes code annotations, which helps to maintain consistency and makes it easier for developers to understand the documentation. By doing so, you can create a more robust and reliable documentation system that serves as a reference point for your APIs.

Accessibility is another crucial aspect of API documentation. A significant portion of the world's population requires accessible content, with approximately 15% of people being colorblind. This highlights the importance of considering accessibility concerns when developing and documenting APIs. Utilizing tools that can check content for accessibility issues can be incredibly helpful in identifying potential problems. Furthermore, incorporating features like labels and text on images can significantly improve the user experience for visually impaired individuals.

In addition to accessibility, another critical aspect is the presentation of content. API documentation can sometimes feel overwhelming due to its volume. Using tools and processes that help streamline and simplify content can make a significant difference in maintaining developer engagement. It's also essential to be mindful of repetition in documentation, as this can lead to cluttered and confusing information.

Tone and style are also crucial elements when it comes to API documentation. A well-crafted tone and style can greatly impact the user experience. Templates and guidelines can help ensure consistency across different APIs. However, the most important aspect is achieving consistency in a way that feels natural and intuitive for developers.

Governance and security measures play a vital role in maintaining high-quality API documentation. Having processes in place to review and update documentation ensures that it remains relevant and accurate. This includes implementing measures to prevent outdated information from being presented as current. By prioritizing consistency, relevance, and accuracy, you can create an API documentation system that supports developers and fosters a positive experience.

Iterative Development and Refining

APIs are not static entities; they evolve over time through iterative development and refinement. Documentation should reflect this dynamic nature. Using tools like screenshots can provide valuable insights into the functionality of APIs, but it's essential to be cautious when selecting screenshots. Outdated screenshots can create confusion if the API has undergone significant changes since their creation.

To address this issue, it's crucial to implement a process that allows for regular review and updating of documentation. This includes not only reviewing reference materials but also guidance tutorials, task-driven content, and other relevant information. By doing so, you can ensure that your documentation remains accurate and relevant as your API continues to evolve.

Another challenge in API documentation is the potential for content bloat. As APIs grow and new features are added, it's easy for documentation to become overwhelming. Implementing processes that help streamline and simplify content can make a significant difference in maintaining developer engagement. Furthermore, being mindful of repetition in documentation can help prevent clutter and confusion.

The Importance of Search

APIs often span multiple services, making it difficult for developers to find the information they need. Effective search functionality is critical in addressing this challenge. By optimizing documentation for relevance, tone, style, and consistency, you can create a system that supports developers and makes it easier for them to find the information they require.

Consistency Across APIs

Achieving consistency across multiple APIs is crucial for creating a cohesive developer experience. While it's challenging to ensure complete uniformity, implementing processes and guidelines that promote consistency can significantly improve the overall quality of documentation. This includes using templates, following style guides, and prioritizing tone and language that resonates with developers.

By embracing these best practices, you can create an API documentation system that supports developers and fosters a positive experience. By staying up-to-date with the latest trends and challenges in API development and documentation, you can ensure that your documentation remains relevant and effective.

"WEBVTTKind: captionsLanguage: enthis course covers everything you need to know to create automate and publish API documentation that your developers partners and users will love Jason Harmon developed this course Jason brings over 20 years of experience in the technology and API world and he's the CTO of stoplight hello free code Camp community and welcome to appek University and this course on API documentation best practices my name is Dan barahona co-founder of appek University and for the next 90 minutes or so you'll learn all about API documentation including how to write good doc good documentation techniques and tools for creating documentation and even the business impact of good documentation your instructor for the course is my good friend Jason Harman CTO of stoplight and one of the most recognized experts in this field I'd also like to invite you to check out all our free courses on appc University you'll find courses on API pen testing the oasp API top 10 API security fundamentals and more all the courses on our site are free and include quizzes to assess your knowledge and if you complete everything and pass the final quiz we'll issue you a certificate and badge to recognize your accomplishment thanks again for watching and I hope you enjoy this course welcome to the documentation best practices course we're going to talk today about creating great docs and as really almost a byproduct of that why that's going to improve your security picture uh but to be clear we're going to take a big look picture at kind of documentation in general with a focus on apis doing that in a lot of companies this is the lifeblood of how software is working now quick agenda of what we're going to cover we'll talk about Who I Am wrot with just so you maybe believe why you should listen uh Define what we mean by API documentation and kind of what that entails from a business perspective why why API documentation can make a really big impact some techniques and tools and and finally best practices for what works well in this space so first up on our agenda who am I my name is Jason Harman I'm the chief technology officer at stoplight and I oversee all the giggy stuff engineering product security it I also host a podcast called apat intersection all of this is more relevant in thaten a practitioner of building platforms and and apis and that sort of thing at everything ranging from Big public companies like PayPal and Expedia group down to fast growing star type form you should and all of that has comeing into play in in my role as stoplight and I've been pretty involved in the community at large I think I've always been seen as an advocate for API documentation so let's define what we mean what is API documentation I think documentation is a big nebulous word so we're going to start start big and Whitt our way down in simple terms this is a human readable description of how developers will enable machines to communicate with each other so man of full but this is my attempt to wrap up a few different things one is documentations for humans this is for people to read and understand the developer aspect that's not the whole story we're not just talking about documentation for developers but at the end of the day the outcome um why people are engaging with these sorts of things is for developers to create connections between machines that's what apis are all about now I do think a lot of what we're going to talk about is portable to many other Realms of documentation especially technical documentation and in general in the world that we live in today interprocess communication between machines is quite often what we're doing so I think it's pretty relevant so there's a couple of different high level things that we would look at when we talk about documentation at large the first is documenting your product and this may or may not entail apis there's the second big bucket of of documenting apis and kind of the difference here is in product documentation you might be showing someone how to use a product and quite often this is going to be a point-and-click experience kind of thing where it's how do I go set this up and I can go figure that out from the documentation API documentation can be a bit of a unique creature in that one it's pretty developer Centric and again we'll talk about the other personas that we should consider but it's really about how to write code to use something pretty different in nature and this is really more where we're going to go I think there's a lot of Concepts that are applicable to both in here but we're going to focus on that kind of more developer Centric documentation to that question who is this documentation 4 and as I said developers mentioned that a number of times but it's really important when you're sitting down to write this kind of content that it's both developers and a lot of different non-developers my tagline to help remember this developers try and business buys what do I mean by that is that increasingly in in engineering and it circles leaders are looking to Developers for is this something that can use and live with and with apis this is especially important you're in essence building a relationship with another company when you use their API so you're counting on the fact that a developer you're going to have a very narrow window of attention they're going to go try it out see how it works and make a judgment call so that developer experience the big picture of it is really important and documentation is the first thing they're going to see the first thing they're going to interact with so critical to capture their imagination and confidence quickly however at the end of the day most developers are not the ones making buying decision and so there are often technology or Business Leaders or both who are involved in approving the budgets to go by these sorts of things so when we're talking about content it's important that we speak in two voices we'll look at examples of breaking this down and a way to do it that it is easy enough as a rule of thumb and speaks to these two audiences because we really need to communicate in different ways there's another kind of Matrix aspect to this which is are you building Internal Documentation for within your organization to bring Folks up to speed on how to use apis between different teams and again this could apply to other things as well or is it externally focused and this is really productized potentially monetized thing that you're going to put out there to the world and external doesn't always mean publicly open more and more more we see that partner programs and this sort of thing you might invite someone to a portal where they're going to read the documentation on how to integrate and create a long-term relationship there are definitely some nuanced differences between these these different kind of environments in internal environments really it's just fair to say that authorization and access control patterns are going to look pretty different for internal apis versus external and we'll talk talk plenty more trust me about the things that we need to pay attention to around off patterns and why they're so important but it is important to recognize that you're going to have a pretty different look on internal versus external facing um additionally for Internal Documentation you're often going to have a lot of proprietary information links to perhaps other knowledge stores on where to find out more about the implementation behind this or the team who's supporting it these sorts of things you might have operation metrics that are linked into this to point to how healthy is this thing should you trust it based on its track record of operational Health as we're in the external world you're often going to put a lot more effort into customizing The Experience putting stronger branding messaging and really some developer marketing on why should you use this thing now I do think these external concerns are starting to creep into the internal world and a thought of this is not really the documentation writer's job per se but again we're trying to look at a total developer experience which really entails many aspects so these are just things to keep in mind if you're going down the road uh let's go build a documentation Bo for apis you're going to have a pretty different consideration set depending on the environment that it's being published to but I will say that I still think that the developers try business by Mantra holds up in both okay the basic context of what is API documentation let's take a little deeper step into what are the different types as I said documentation can be a bit of a nebulous word and we really need to get a little more precise as we get into creating something practical and useful so there's really three highlevel things that you tend to see in this type of documentation and again I think a lot of this is portable to things outside of apis the first is reference material and I think for most say developers when we think about API documentation this is the stuff we're thinking about it's really the Encyclopedia of how to go use this API when you already know what it does you understand the ideas and you're ready to go write code references where you go however if you only document an API in its reference format and and we'll look at what these look like so don't worry if reference doesn't mean much to you yet all is more important is the concepts right what are the things in simple terms what does this API do but often it's not just one API it's that there's a set of ideas of why you would come use this Suite of apis what are the big things that you're trying to accomplish so in sort of product speak we might say what is the job that you're trying to do and then furthermore you might have tasks and this is where could be a whole other chain of things that need to be done you might want to showcase certain steps that users need to take in order to accomplish so these are pretty similar and it's a pretty blurry line between Concepts and tests but we'll look at some examples what these things look like so first up on API reference I just picked on one API portal here and we'll look at a few different ones but this is pager duties and one example of L their API is listing escalation policies now what we're really looking at here is reference material and you'll notice that right off the top we've got request and query parameters on the right we've got off information there's a request sample kind of falling off the bottom there we've got you know the get so the verb that's being used in HTTP and then the URL that's being called so there's a lot of kind of parameterized information for an engineer is filling in the blanks that they need on knowing how to call this thing but you'll notice a couple of things first the first paragraph of this reference material is not really speaking to developers if I looked and said what is list escalation policies mean first list all of the existing escalation policies so that tells me the list and I'm getting the existing thing that's not something that is fabricated from thin air so it's not a lot but I'm starting to learn escalation policies Define which user should be alerted at which time that's what an escalation policy is right so now we're starting to get tidbits of Concepts and this is I think to that point of if it's a non-developer who's browsing pager Duty site and saying is this something that we should be using now in this case I'm being contrived because peder duty is a pretty developer Centric product as a whole but let's imagine for a moment that I'm shopping as a non-technical user I get a sense of what this thing does now if this isn't enough this is typically a very topical description functional description of what this does we might dig into what are the concepts behind this and in this case Pedro Duty expressly calls out an API Concepts document right they have a specific thing for this but let's come back to the concepts in a moment the other part that I really want to break down for you is the anatomy of API reference material now there are certainly lots of other things out there we're going to talk about more of the rest style apis a request response kind of thing you'll notice on the far left we've got responses and across the top we've got different status codes in kind of a rest stle API 200 is good 400 the user did something wrong 500ish errors that something's wrong in the server we'll look at that in a later section a little more in detail but you notice the B section here for developers this is what we're looking for right what's the information that comes back and I need every field described in an adequate enough fashion that I know what that field means so if I looked at this and let's say offset and limit weren't described most developers would guess this is probably pagination same thing with total and more these are pretty easy but as we get into the escalation policies summary in this case is a pretty specific meaning it's short form ser generated string sync important information so it's okay this isn't really something that someone hand curated this is a server generated value this has some kind of insight built into it so I understand that there's going to be something interesting and valuable in that summary information and as we go if we went down the list of all these properties there's things to learn at every step and so just keep in mind that when you're looking at the fields were returned in the body of a response the field name itself would often have incredible ambiguity so for instance if I said look at the summary in escalation policies what does summary mean summary is a very ambiguous term it's used in lots and lots of domains and it needs a precise definition of what summary means in order for it to have adequate context to be useful now we're kind of looking at it backwards here from left to right we're looking at the response first but for what it's worth this is what people quite often want to see first is before I do all the work to make a request am I going to get in the response resp wantse does this have the data that I need but if we shift over to that request side you'll notice right off the bat Security in this case it's an API key and there's probably a whole set of steps to go get that it is an important and critical first step to making any request is there some kind of security being passed here um beyond that is all the query parameters and you might see headers as well which I have highlighted on the right and these are going to depend on what kind of endpoint or calling whether it's a get or put or a post or a delete you're going to see different kind of interaction patterns here so just keep in mind that like in this case we're looking at a list of things and you'll notice a lot of stuff with like offset and limit total these are paging controls and we'll talk about kind of consistency this is a great example of the kind of thing that I would expect if I look across all of PAG your duty apis that I would tend to see these same paging parameters and paging response parameters as a a consistent pattern so that if I write code as a client against this API I can reuse how paging works against the pager data API across many apis and not have to write a bespoke way of doing it every time I integrate with yet another operation in headers I think this is one that a lot of folks maybe don't grasp so well and it won't go too far down the rabbit hole with the API thing but in this case accept in content type these are about content negotiation and this is an important thing to cover as well in pager Duty's case they're calling out that they're using a specific media type that's bespoke to pager Duty when we look in there we see this plus Json which tells me it's going to be Json data they're just telling me that application D and pager duty is their specific domain description of what's going to be in that Jason and then version two it's another important one to cover is how are you handling versioning in pag your Duty's case they're passing it as part of a media type in the accept header and making it an implied part of their content negotiation content type is again just part of that content negotiation you'll see here application Jason it is increasingly likely that you're only going to be seeing application Json type content in apis but always be mindful that there could be other content types supported on older stuff you might see XML in specific domains you could see very specific media types to that domain something like VCF for contact information right so be mindful that developers may have multiple ways or multiple formats that they can retrieve from one API so I promised we dig into those status codes and this is a concept that we really need to embrace is that if the documentation is the first thing that a developer goes and looks to to learn how to use an API and they form their first request it's pretty likely that their first interaction with that API is going to produce an error because they don't know how to use it and maybe they've made mistakes in how they formed that request so it's essential that we describe what happens in the case that is not 200 and something 200 class errors are success 400 classes you did something wrong in 500 classes I did something wrong if you're the API Builder so for a client a 400 class error is going to tell you there's probably something wrong with the way that you provided those parameter values and you need to fix that in order to get a valid response now the shape of that error again this is one of those consistency things I'm going to dog here we're going to come back to talking about consistency but if I'm using an API from pager Duty and I use it one I'm going to write error handling code and I'm going to expect that all the other apis they offer I should be able to reuse that error handling code by and large so that's going to save me a lot of code as a client of it and not having to duplicate all those efforts from a documentation perspective one it's critical that you're focusing a lot of energy early on in what are the errors going to look like both in their shape and in their content so in this case we're really just showing the shape but it certainly is common that you might have some breakdown of what kind of errors are you're going to get and this often Beyond just the status code if we look on the right in the body you'll see that underneath that error object that is returned in the response in the case of this 400 that there's a message so you'll see in the example message and this should tell the human what's wrong there's quite often a code that's accompanied with it and this goes a level deeper than just those HTTP status codes and goes into an application specific error code and quite often having reference material that enumerates what those error codes mean will help users when they're not looking at the documentation down the road and they're writing code and they suddenly get a 400 error and some weird code in a message that they don't understand they want to be able to go back to the documentation and find what does this error mean or detail so another common practi is in these errors that you would actually provide a link back to the documentation I say it's common practice I I wish it was more common but it is a a commonly understood affordance I think more folks should Implement at the very least in our documentation we should always have some place to go look up those error codes and really just understand in general what our errors going to look like on your platform and for what it's worth bottom left here I wanted to highlight that beyond all of that customer facing or kind of API consumer facing attention that we should pay to probably their first interaction with errors the mere practice of documenting what the errors on I promise you it's going to surface weirdness in your error handling and if you don't go through that that discipline of documenting those things those are going to be surprises that no one is going to welcome this is the first taste of something we're going to hit quite a bit is that you're going to uncover quality problems here and part of that quality I think is going to be a security aspect if you have access control that don't work right and you're not getting 401 or 403 errors typically for off related issues where you expected them even as a writer who's addressing this you should be able to flag to the team that look we've got a hole in our access control that I can't explain in the documentation so this is where there's a lot of implicit quality and security enhancement that goes with documentation and I think errors is one of the big wins moving on another typical thing that you're going to see in API documentation is a try it type component where you can go get some sort of authorization token fill in the parameters and hit send API request and see what the response looks like now in some cases this might have a Sandbox environment or sort of a mock interface that gives you fake information but it should give you quick tacti feedback on what is this going to look like so this kind of gives you a no code way to try an API and for developers quite often as a way to quickly get quick test of what it is they're thinking and then on the right you'll notice the request sample so in this case it's a curl example you could certainly have language specific code examples here something that somebody can copy paste drop into their application and use as a starting point for making that call and hopefully this combination uh significantly reduces the error rate that new users are going to experience while this isn't explicitly a a feature of how you write your documentation I think from a how to present documentation this is increasingly a table Stakes feature that people expect to see in developer portals at large especially with apis coming back to I promised before we we highlighted where in patri duties API about listing escalation policies that they had a link to read about these Concepts and this is a a snippet from their documentation of what that looks like now before we got two lines that said the list escalation policies gives you a list of existing escalation policies and an escalation policy keeps track of who gets the notification whatever it was two simple sentences however in the concepts document we get a pretty comprehensive description of what this means and I won't read through it all here but I think it's a a great example of where you've got a simple functional description at top of the the reference documentation for an operation that might link back to a more comprehensive description and internally if this is an internal focused API you might also see accompanying links and material on how this is implemented on the back end or what other systems it relies on to make this work for new user when they look at those couple of sentences that quick paragraph you still don't get it you want them to be able to jump in and get a deeper definition of what something means and you'll notice in this case there's many references that link to other reference material right at the top user schedule notified incident Services all of those are other Concepts and likely other API operations they will call a group of related things in order to build a full interaction so sometimes you need these overviews to describe how these Concepts relate to each other and how they're tied together in fulfilling certain workflows although we'll come back to that more workflow oriented view uh it's important not only to describe beyond the simple paragraph and have the bigger Concepts but also what concepts does this relate to or depend on them the most important Concept in I think all documentation but is exceptionally true in API documentation is how do we get started this should be the first thing that any new user who looks for your apis and comes up on that first page they should immediately be taken down an enumerated set of steps here is what I need to do to call these apis and I say these apis intentionally to say that it hopefully isn't a lot of different ways to call a lot of different apis if there's one way to provide access that's a win for everyone from a consumption standpoint I have one way to do things from a security standpoint you'll notice right off the bat the step one and in this example we switch gears to the stripe API which I think is probably one of the strongest examples over the last 10 years or so of excellent API documentation excellent developer experience and step one in the stripe API every call to a stripe AP API must include an API secret key and then it goes on to very briefly describe here's what you need to do to get these API keys and notice it doesn't say if you're calling this API do it this way if you're calling this other API do it that way one consistent method of off is key here both in terms of usability and having a single method accessing these things so that you can really focus your effort on securing one areir area so these steps should lead me down a road of at the end of a few steps and hopefully this isn't more than four or five steps I've made a successful API call that's really the goal that you're getting to and in many API programs this is actually an instrumented thing in that we want to look at what is the time to First hello world how long does it take to get through those first steps and make the first call and a common Benchmark is to say this should take no more than 5 minutes now from a documentation standpoint this is where we take hard and make it look easy right and in some ways we have to really bench test what we're thinking about on how people are going to use this and really simplify and really Whittle things down to be easy for a new user to adopt so most important concept this is where you should be putting a ton of effort I know I said the errors were the first place to start but that's in reference this is more a Concepts so just super key especially because Step One is almost always how to do off and as the old adage goes if you're running a two-day hackathon day one is getting off done um this is quite often the inconvenient difficult tricky part and if you're building an API and documenting it this is your riskiest part so you should have a crystal CER succinct understanding of how this works for everybody preferably one way to do it for all apis so that you comprehend how it works and then you can explain it succinctly if you can't do that you probably shouldn't be publishing it you're probably taking risks and our final topic tasks again we'll look at stripe and I said Concepts and tasks can be a bit of a fuzzy line but I think the way I think of this is It's really what is the workflow that you're trying to here and what is it that you're trying to do so I often refer to this as like a showcase so in strip's case right there top left they're saying all right do you want to start an integration and they're starting with a conceptual idea payment link checkout web elements that is going to take you down at the road of learning some Concepts and learning how to do those things together this is really important in the API world because if you launch something out there with say reference material only no Concepts no workflow driven tasks people will do serendipitous things right they will come up with very creative ways to use your hii that it's in some cases you didn't plan for and just don't work so in some ways this is also projecting to end users this is what this API was meant to do this is the job that it will do for you and keeping that frame of mind for new users will guide them into using it in the way that you intended and hopefully not creating friction or problems for them El or for you not listed in kind of the big three and this is because it's not pervasively common in some ways it's a cost prohibitive concept for many programs but it's definitely a key to large scale success is that if you want quick adoption and you want API consumers to connect quickly don't make them write too much code and you can do that by providing sdks client libraries tooling around the API means you don't write code to call it explicitly you might call a library you might use a command line interface things like this and I say these can be cost prohibitive especially in the startup world or in smaller companies building and maintaining client libraries can be a very costly effort but you'll notice in Pedro Duty's case Pedro Duty didn't go build libraries to interact with its API all languages in fact many of these came from the pager Duty Community see you'll notice there's a warning on here too Community Support P Duty doesn't endorse or provide technical support so on this in some ways is how a lot of folks make this an affordable approach uh but from a documentation standpoint it's also an opportunity for you to Showcase where there could be Community Options out there that you didn't build that ultimately are going to provide a better experience faster onboarding all that sort of stuff with the caveat this isn't stuff we built and so thereby we can't really directly support it you're going to have to work with the community on that but at any rate it is an optional fourth column that in more mature programs you'll tend to see this is also very applicable for internal API programs as you reach a larger scale a larger quantity of apis it is definitely a speed accelerant to have more of these kind of client libraries command line tools So Okay so we've touched on some points in here about some of the corollary benefits that you're going to get out of investing in documentation most of it in general and and specific to this class in API documentation but let's really distill some of that out and expand on what is the value so let's say as a learner here you're thinking about learning about this concept and you're going to take it back to uh your team and say this is why I think we should do this hopefully this fills your quiver with arrows on Great Value points for investing in great documentation so why do we need to do this and I think we we touched on these bits the first is it's about education you've got to teach customers prospective customers your own employees potentially Partners about what are the things that we do and how do you connect to these things with apis um it's surprising companies that lack this sort of platform wide documentation about all their apis how you talk to say Business Leaders they don't really know exactly how things work they have a general idea but when you've got one source of Truth to document things that your company does you know the capabilities of the apis provide you have vastly more engaged and educated leaders and this applies as you work your way through the organization especially with apis because it's such a crosscutting concern through the company and it's such a distilled representation of what you do they really important that everyone understands this and obviously where the rubber meets the road on is someone going to adopt this API or not really essential that you're able to teach those folks and not just hand them the encyclopedia and walk away second you're in part often defining boundaries between products within your platform and that understanding within the organization can often transcend the way that you're organized today so we'll refer to this as like an inverse Conway maneuver the idea that Conway's law tells us if one team builds a compiler you get a one pass compiler if two teams build a compiler you get a two- pass compiler in other words if you're not intentional your software will represent how you're organized and increasingly this inverse Conway maneuver says let's be intentional about what we want the future of our uh platform to look like what if we want our capabilities to be manifested in apis so defining those boundaries uh can be really important for people to understand the customer perspective on what you do and that could apply for your own employees that could you know we touched some the education bit all of that leads into clearer definition of the things that you do which is going to heavily inform how you test and secure those product boundaries so these things can you know heavily influence how you're setting up your network your application layers all that sort of stuff as well as at the end of the day again we come back to does someone want to adopt this thing they need to understand those boundaries kind of the groupings of things right so just comprehensibility the ability for somebody to look understand the big picture quickly and then be able to drill down and understand some of the details quickly this can be very powerful organizational amplifier over time enabling customer support offerings this is another factor that isn't really documentation but you know we're the front door for these things if someone's reviewing this API or maybe they've tried it and they're stuck how do they get help documentation can help lead those consumers lead those customers to find the right kind of support I say the right kind because sometimes it's self-help only it's Community Support or there may be self-service options to go fix some of of the problems they're running into if you don't have this sort of thing then people will wander the hallways looking for help right meetings will spawn off everywhere on I'm stuck how do I get help I need to get on the phone with somebody I need to get an email chain going these things are just friction and toil let's document one place make it easy to find and finally supporting technical or developer marketing efforts in the API World um you know it's it's a weird thing to Market to this crowd because you know we have kind of a low BS threshold but in short we should be teaching not selling in kind of technical marketing efforts and rather than sending some big huge toe in an email or attaching a PDF we can link back to documentation that maybe highlights new features or points to a change log with what's the newest change to the CI and all of those things from a marketing perspective can help boost adoption again if you're teaching and not selling so who benefits from all this right and we kind of said before that you could have an internal view of this you could have an external view of this sometimes it's both but quite often you might have different apis that you offer internally or externally so the internal value is I think more than anything avoiding duplicated effort if you have undocumented apis all over your organization there's a good chance that many of these are going to be built a not very reusable way and worse if no one knows what exists there's a tendency to just look around and if you can't find it create your own and so you end up with four different ways to do the same thing and that's really not good for anybody right it's not good from a smart investment standpoint as a company it's not good for frankly job security in some cases when these things get discovered so you know avoiding that duplicated effort is just such an obvious win versus not documenting the second I mentioned there's a tendency that if you have undocumented things people will build oneoff bespoke things is that we can really promote increasing shared leverage it's a fancy word to say that rather than duplicating efforts let's join forces and build something more powerful and more reusable that we can use for a lot of different scenarios and not maybe just to enable one partnership or to connect one system somewhere so that shared leverage over time will build stronger capabilities and more aligned organizations as opposed to fragmented collections of ons and finally just beating the dead horse here on organizational understanding if you don't document the apis you have and you have this big sprawl and we'll talk about that later nobody really knows how anything works and it becomes tribal knowledge hallway discussions and email threads and meetings trying to chase down does this exist and how does it work it's just a huge weight that we can lift off the organization and really promote a lot of innovation and and speed as it builds momentum on the external side again you might be publishing to a partner Network or to a wide open publicly facing thing you obviously have to document something we're going to dism you it here to say what's the difference between adequate documentation and really great and I think done well this will promote stronger adoption from consumers and if you've got and built an API whether it's directly monetized or not you're almost always looking for can we get lots of people to use this right there's some economy of scale that comes with this along with that I mentioned before when you're evaluating an API that you're going to go use you're really in some ways evaluating what is this relationship going to be like and so let's say you have a hastily clad document that was a project artifact written by developers as a second thought and you're shuttling that over in a PDF on request that's an a great way to start a relationship is it so instead if we have durable documentation that's there on a well-known URL that's easy to find and folks are going in and having a great experience on learning making that first call less than five minutes that sort of thing we're off on the right foot with building a great relationship with whoever the API consumer is whether they be developer off the street or a close partner relationship all of these things lead to folks sticking around and being satisfied having a great developer experience and finally to the point of developers when you're marketing products to developers and in in the API world we almost always are all the no code low code is changing that somewhat folks are going to take away from that evaluation of looking using an API is was this a good experience or not and they're going to tell their friends and in the developer marketing world we deeply understand that word of mouth is key traditional marketing efforts often drive people away producing great experiences with thought leaders who share with their communities is what builds really big communities around apis so distilling this down even further let's try to boil down three big reasons that we really should be able to share with folks this is why we have to do solid documentation the first is we're going to look at this from a security standpoint this is an apis set curriculum and while it is an explicitly only about security there's a longer to documentation it is actually one of the primary reasons uh is that you can reduce risk so API exploits and I'm going to really make a strong call to action here if you've never heard of oasp go take a look in general and specifically the API top 10 was actually just refreshed in early 2023 the inconsistent or non-existent off mechanisms and this is authentication authorization U these are the reasons at the very top of the list and they have been for a long time even in the non-api top 10 is broken object level authorization or Bola and broken authen ation these are reasons one and two that API exploits are happening and at the time of putting this together looking back on 2023 we've had an unprecedented wave of API exploits and the vast majority are because of these reasons so the part that we're going to focus on is inconsistent and non-existent if you document an API what's one of the first things we're going to do getting started how to get that token and how to attach that token to the API call if that doesn't exist and you're writing that documentation the the flashing red lights are blasting there is a huge problem we cannot use this until this is fixed inconsistent I said before if you're describing how to get started you should have one way to do the off patterns if your documenting the next API and it does something wildly different big bright flashing red lights they're is a problem we have a new way to do o was that intentional is that a good idea that is inconsistent so really just catching those inconsistent or completely lacking off mechanisms it is actually one of the most important ways that you can avoid API exploits before anything's ever even in production assuming that you're documenting these before you release them and related to that is is joking that we put here missing mistakes is that if you're doing this in an iterative way every time the API is changed you're updating documentation that you essentially have audit and review built into your process now is your documentation writer always going to be the expert on what the standards are and this sort of thing not necessarily but if you have a more comprehensive review process that includes documentation those things should be caught and we'll talk a little bit more about kind some ways to build Bridges from the documentation process into a broader API design review process we'll talk about style guides and standards and these sorts of things but as you're folks writing documentation become more familiar with those Concepts just by the very Act of documenting it they're going to effectively have done a high level audit and review so it's a fantastic place to start in reducing these risks second is let's not spawn the army of zombies and it sounds like a goofy joke but this is really a thing that folks refer to in our space is the prevalence of Shadow or zombie apis and this in the it and Engineering world what we're referring to is the apis that no one knows about and this is exceedingly a huge problem is that folks are having to go dig through logs and look through production information to try to figure out what are all the apis we have because we don't even know what they do we don't know how they're authenticated we don't know what their performance is like these things could be producing huge risk vectors they could be producing terrible experiences and you'll notice here we we provided some reference to noric apis that 94% of respondents had experienced some sort of incident in the last year this is actually the second big category of risk is just the undocumented stuff the things that no one knows exist are the things that become stale that are not monitored and just present huge risks and Blindside opportunities things you don't even know exist could present vectors you're not even thinking about so really we want to build this catalog of what are the apis what are the capabilities that we have keep it maintained have process around it because if you know what you have you're able to protect it if you don't even know it exists who knows what could happen so taking this concept a little further we often refer to this notion of APs raw and while zombie or Shadow apis are the things we don't know exist sometimes sprawl is there might be some idea that these things exist there may be sporadic lists of these things floating around or there's an idea of we kind of know this is a thing but there's little cognitive alignment meaning folks don't NE necessarily have some agreement on what these things are and how they fit together as one platform and now that risk of duplication we talked about before suddenly becomes a huge problem is people building really close to the same thing over and over again and very little reusability if we have that better understanding of what are all the things and we can see them all in one place they're documented together there's some portal that manifests these things we can start to build that cognitive alignment the idea that we all understand Big Ideas in the business that we run or in the consumer base that we're serving here that ultimately will lead to Stronger alignment to Stronger execution to more satisfied customers this sort of just reiterate the lack of visibility it's going to result in less reusability right if we can see all the things we'll recognize duplication we'll recognize where there's shared leverage potential and we can be more customer Centric in how we describe things rather than describing them as a happen stance way all right so we described our top reasons that you must have these things and they're very risky scary and sometimes that's not the best place to start in justifying or convincing folks of why we should do something so let's talk about the positives the nice to have what are the benefits of doing this the first is observability and this is the antithesis of that sprawl and zombie stuff we talked about uh it's really the outcome that we're going for we want to observability we want to be able to look at the catalog of things that we have how they relate to each other and ultimately have one you know clear view of so let's say that observability is the positive outcome that you're seeking to escape the sprawl in zombies and Sh leverage already said this over and over just in the first section but getting that collaborative culture together on how to reduce the wasted effort reduce the duplicated single use case functionality and really build powerful reusable capabilities with your apis this is essential okay so we have lots of reasons that we should be doing documentation and we have an idea of kind of the the structure of what these things look like now let's get down to like who's going to do this who's going to write the docs and what's an appropriate choice in how you plan for writing your API docs and I think this is true for a lot of technical documentation and General to so developers is what we all think of right it's apis it's technical stuff developers have to document the thing they built and the reality on the ground is that the folks who built the API are not always great at being able to describe how it's used seems counterintuitive but let's say that when you're building it you have a system Centric View and when you're consuming it you don't know anything about those systems and so there's a tendency that implementers will think more about how it was built rather than how it's used and it's very difficult for them to escape those thought patterns that's not a knock that's not a criticism it's just a reality at a bare minimum we should have some kind of peer review related teams or teams that are planning to use these things at least providing that contrasting view of here's what it looks like from the outside now a pro of having Developers invol in the documentation and frankly I don't think you should try to escape developers involved inting apis is that if a developers implementing the apis partnered well with other folks they can be great about providing developer Centric feedback especially in this peer review type stuff we're describing another developer looking at what when developer bill will produce a better outcome you're going to have something that is going to have a Viewpoint that's about writing code that no one else can really provide in the organization so next in typical truct development we might see product managers who are involved and increasingly we see the role of API product managers being a thing now over the last four or five years we see this job description increasingly popping up everywhere so we describe this as occasionally who will write the docs the pro of doing it this way is that you have a very customer centered perspective compared to say a developer who's building it so that can really ultim provide an effective developer experience and this goes back to before where we said developers try business buys is you need that clear functional description and sometimes developers get into kind of the sausage making side of it rather than being a little more empathetic to the end user product managers are often naturally better at this thing now the obvious con is if you have say very non-technical product managers that lack of technical expertise could lead to some problematic ways they would describe things and this is again where putting those PMs and developers together and partnership to describe these things can be effective now who should write the docs we talked about what kind of tends to happen you know dev's building the API and wres the documentation of the task on Project or the PM maybe kicks in and helps out and cleans it up and makes it readable for customers I think you can get to perfectly adequate outcomes for that that are L effective however I think in a perfect world with no budget constraints I reach for technical writers especially those if you're doing apis who've done it before and understand the intricacies so that the pros is like I don't think it's it's well described here but it's to say that we have real professionals who understand how to communicate technical Concepts and ideas and how to be precise and thorough describing all the things it is a smart investment period or around apis in my opinion and I think it's really underutilized in so many companies it always surprises me when I find companies that don't even have technical writers so if you're going to reach for that and say let's go hire Tech writers to help with this great call but keep in mind that you can't have a team go Implement and build a whole apil row it over the fence to a tech riter and expect magic to happen you've got to have those writers involved early in the process and you've got to have some sty guide defined around this so that they're enabled to produce consistent results so document the simple basic stuff as soon as you know it even in the abstract for any implementation has happened and then iterate to release that will produce all those benefits in Tech writers being implicit QA they're going to find problems as they document things don't do all that at the end and treat a lot of friction and delivery do that from the beginning and find those problems while you're developing all right so onto our second section we've established now what is an API who writes those things why we should be doing it all these benefits but let's really break this down in in strong terms on what's the impact to a business in investing in API documentation so we already referenced before good docs matter to security reviewing those off patterns consistency these sorts of things you're going to find security issues and consistency I keep saying that word let's break that down a little bit more a lot of folks talk about standardization and really consistency in some ways is the outcome of standardizing want to have things that look and feel the same and in the business of building platforms the main difference between just a bunch of apis and something that feels like a platform is that consistency so investing in docs is going to show where you have those inconsistencies especially if you've got professional Tech writers involved consistency is the name of the game and they're going to see those things clear's day quality I I keep saying that those who write docs for an API Through The Eyes of a consumer will find quality problems they're going to find bad error handling issues they're going to find logical problems and how the API works and they're going to provide that functional view so we talked about those first few sentences in each reference material that describe what this thing does and the concepts that amend that all of that can be incredibly use for someone who's working on how are we going to test this and make sure that that it's at adequate quality if we don't know all those things early then how are we expected to test it at adequate quality and it's more secure we are leaving less room for error if we just go build an API undocumented and get ready to release and say oh security Ops Dev Ops can you uh check this out it's a terrible way to start that engagement and if they find problems then it becomes a fight because I've got to ship this thing customers are expecting it business is expecting it security and devop hooks you're holding me up that's no good right if we're able to provide documentation about what we intend this thing to be even if it's rough documentation early in the process those teams are more aware they can plan they can prepare they can do deeper Dives more questions without holding up delivery and by actually documenting the things we ship the security and devops folks are given a fighting chance against the army of zombies or the sprawl problems if they're never even made aware and someone just pushes code and there's no documentation for it how can they be expected to do a great job in defending those assets so in simple terms here at the bottom bad poorly maintained non-existent documentation these this is a leading risk for security exposures so while we're saying that consistency standardization is good sometimes so scope are we just make try to make things too perfect I don't think in this case we're looking for Perfection we're looking for existence and reasonable quality right let's reduce those risks there's no such thing as no risk but at least having reasonable documentation is going to heavily mitigate the risk that we have unmonitored assets so let's dig a little more into security right if we're taking this approach that we should document things and Design things before we build them and I know that's that sounds a little counterintuitive a little cart before the horse but it's not to say that we have perfect documentation day one before we build anything or that we have a perfect design before we've built anything it's that we should have a basic understanding of what this thing will do what it will look like before we go and get too far into implementation and realize there's problems and what's key about this in the security realm is we can review off patterns before a line of code has been written and that in itself is one of the most powerful ideas in probably addressing 80% of API equids now if you didn't document anything you didn't design up front and you just went off and built something and shipped it to production you just lost that 80% B so Security review is a pretty commonly understood thing what we would suggest here is with this documentation first design first mindset as soon as you can describe the thing that you're going to build let's start engaging in some kind of security Ry process so how do we do that API style guides are are a big step in the right direction and we're going to take a little closer look at what those look like but this in essence is saying that we have some standardized patterns in how we design our apis especially including how we do o so if your API design review incorporates security and you have some automation around style guides and these sort of things you can put a lot of really sophisticated look at things very early in the process and really cut off a lot of the problems that tend to emerge when this acument is not addressed one weapon here as we describ it in your repository can be security style guide and so really this is a subset of a broader API I to say that how do we do these security Centric things and I keep talking about off but there could be lots of other security related things in your apis for instance if it's a payment related API making sure that you don't have some exploit available to say manipulate currencies or you know some scenario that you need to be very cautious about you should have some defined standards tend to call this style guide because I don't know standards make people bristle saying that there's a style in which we design things I think is more appropriate to a design discipline so all of that can help put some guard rails around the design process and incorporate security early with that early documentation so that everyone understands what we're going to do everyone understands the risks earlier and ultimately at the end here with a a well chosen set of rules around your security and enforceable sounds a little rough here but it's just to say that do we have process that plugs in those rules somewhere that you can keep using these tools in an iterative way to keep just building stronger defenses into the future and not constantly be digging a deeper hole so all of this is taking us down a road here and you know we're going to have to say the GW I know it's not always popular but I insist we should reclaim the word governs and make it what it needs to be into the future and not the painful thing some of us have experienced from the past so a healthy documentation process is a great way to start moving toward having stronger governance and this is where we'll dig into kind of that style guide thing that I keep referring to this is about automating consistency we keep saying that when we look across a bunch of apis that consistency is the only thing that makes it feel like a platform that they all look feel smell touch the same manually maintaining that it's it's risky it's hard um as somebody who has done many manual API reviews I know I've always missed stuff it's impossible to catch it all we are not great as humans at finding these things so we should really be looking at how can we put more automation around these things so consistency standardization these things live together but how do we do that so the First with style guide and linking approaches is key one example of this it happens to be an open source project of stop lights so it does sound like I'm Shilling but I can objectively say that this is a broadly adopted artifact in the open source Community to Define governance rule sets and I think the reason it's really relevant in our learning about API documentation is there's actually do documentation Centric rule sets that you can use that do things like have all the description Fields been filled out for all the the fields in your response if that's something that you want to set a rule for and so you see here on the right an example of what a stal guide looks like and how the errors might manifest so for instance here at the top of the rules it says info contact info object should contain a contact object that might actually be a great documentation rule for let's say an internal API is okay I found the API I know what it does I read the documentation and there's something I still don't get who can I contact to find out more right so you might want to standardize and say that there should always be contact information with every API listed so could you do that manually and say oh make sure that we've always got contact information sure you might miss it and let's be honest no one really wants to do that manual review so put it on a check we can manifest an error somewhere that'll show folks hey don't forget to have this and then by the time you sit down to do some sort of manual review for the things you can't automate you don't have to worry about that this is a huge Force multiplier for kind of all things apis but surprisingly even in the documentation world we can do a lot of good here another suggestion from Talking Tech writers is Veil so Veil is basically another kind of linting engine for enforcing writing style so quite often you're going to develop a voice a certain you might adhere to say Microsoft's technical writing guideline something along those lines and you want to be able to turn on a rule set that says here is how we phrase certain Concepts or here's when we use acronyms and we don't things like that so point being with a few different tools and there certainly are some more out there but I think these these are some really leading strong ones you can make the review process predominantly automated so you can spend all of your cognitive energy on a stuff that matters what does this thing dude should it be here is it reusable and not did you remember the contact info did use an acronym or not so all of this leads down the road of stronger scaling we can replicate this kind of process this kind of automation on all the things that we do and ultimately it should lead us down a road of more reusable things things that you don't have to write BB code every time you use a different API and all of this too should lead toward something that's just pleasing to a developer's eye you know developers can't help but be precise in our nature right in building big complex things with lots of things to remember we love consistency we love to be able to look at something and go ah that is so pleasing there's nothing out of place everything's where it should be um and these kinds of approaches and automating your consistency it's an intangible difficult to measure thing but it really can produce a much better developer experience another concept here we talked a little bit about how there's internal and external apis and I keep mentioning partner networks this sort of thing in the world of Partnerships documentation is one of the most important assets that you're going to trade in the early phases is hey you want to partner with us here's how you would integrate so for those potential Partners who might be looking at your partner portal there's a few things that you can really punch through here one is brand affinity and this is where we talked about you might want to have a little more customization on the external facing stuff if they don't ever get documentation and they're having to constantly ask questions that's a terrible uh relationship so that's a bad starting point let's give them something that's our best forward but there're also just going to be in a way evaluating your company and how you operate by their interaction here so there is an implied kind of brand Affinity so when folks talk about loving strip right uh in the developer world this is a common sentiment it's because they had a great experience with that documentation they didn't have to ask anyone questions they were able to accomplish their goal without help they have a love for that brand so that's one of these tough to measure tricky and tangible things but really is something you have to keep in mind the second and I've said this a few times that API adoption if you don't know anything else about an API that's the first thing you should measure is if we went to all the trouble to build this thing these are not always easy things to build or people using it do we have a good Trend going that people are getting value from it so docs are your best tactic to push that adoption you have a crappy docks experience I promise promise it will be worse adoption than if you had a great experience and then finally is scaling and we talk about some of the processes and things that should dovetail into your documentation efforts and you're not going to be able to reach scale if you don't kind of have that game together and if you have a bunch of undocumented one andof crappy relationships you're going to struggle to scale this program so documentation is and often you know not thought about strongly as it's a critical asset in producing that scale so let's dig into the simple question of how do we write good documentation I think we've touched on a few of these different subjects we' hit it from a few angles let's get a little more practical so again just reminder we want to think about who's the the audience here are these internal developer oriented documents are they end consumers who might be external to the company are there any sort of security gates involved these are all things we want to keep in mind before we enter into this so it's always important start with those relationships understand who's going to be using it so that you're using the right voice and the right approach and enabling them some high level things on as you're sitting down to document an API a couple of high Lev things to think about first is an explanation of what request data is required what's optional an example might be the version of your API this is commonly passed in a path there's certainly other approaches like headers uh but this is often required information you need to supply which version it is that you want to get um and if it's not required that's also important uh and what happens if I don't Supply a version do I get the latest and an auto upgrades me how does all that work important to explain along the same lines Authentication any other uh sort of headers or anything that are to be expected the path to call each endpoint think this is the most seminal information in calling an API is what's that URL going to look like what HTTP methods are going to be used get postl delete the options could be other things and the request data fields what's the request body look like are there things besides the body like query stream parameters that might be passed on the other side we need to look at what's expected in the response which responses will always be there what am I going to get when I call this thing so example data always really useful as a an easy way to go beyond the documentation to what does this actually look like what status codes are possible I will'll definitely look at this in kind of a more real example but as we've said before it's not always the 200 okay that comes back sometimes we run into problems so we get errors like 400s or 500 class errors those are all different status codes that could occur and it's important to document what all those possibilities are and if there's any sort of status code or any other information that comes back what does it mean in the context of this call is there's something specific to it and again documenting one API is one thing but we also want to think about where are we sending folks when we write this document and I hope that the answer is is not we're going to email them because that's just it's not really acceptable these days we want to be able to send them a URL to here's all the apis you can find the thing that you looking for so we're really talking about death portals and things like this so think about how are people going to find these things is it discoverable as you're sitting down to write your documentation you want to think about who's going to read it and test it out and this is where some form of developer advocacy is important and there's a lot of different ways to organize this and put this into action but at a bare minimum have other internal developers read through the documents even if you don't have sort of developer relations developer advocacy who might be your contacts in the field who talk to end users a lot a little pizza and beer can go a long way recruit some folks who were not on the team building the API to go look through and try to follow the documentation and see what they run into and if possible observe them doing it where are they running into sticky spots friction where are they struggling to understand what to do next are they getting caught up in terms they don't understand and having to go read definitions and hunt for that information as we've said before what we expect is probably don't get the off right the first time this is a common story and again we want to have that be step one in getting started but making sure that not only is that documented but someone's tested it out who isn't writing the docs and who isn't building the API to make sure that it actually works in reality because if that one thing breaks nothing else works so you've got to get that right above all other things so with that let's go make a fake API let's go create something you know at least partially from scratch and see what this looks like in practice so let's take a look at our imaginary API in this case we're going to create a widget API obviously our descriptions are not going to be very verbose as they widgets a fairly Indescribable thing but from the top we see that already defined uh aversion we've come up with a base URL as well as a mock server URL this basically just means that we can call a fake API before it's actually been created information about security any additional information about who to contact any license information that might be applicable terms of service and from the top again we want to provide a simple basic description of what this thing does what is a widget right tell me that in this case there's not much to say getting started we talked about this before that in an overview of an API I should know what to do to go use it and in this case the only real prerequisite is making sure that I've done the off stuff and made up how that would work if it actually existed typical usage just gives me an idea of why people would use this thing right uh and again the description isn't terribly relevant here but this gives us an idea of content placeholders and then Concepts I've already kind of predefined and we'll look at it the idea that anywhere that we have a list of things that we would have uh some simple paging controls like page and Page size as query parameters we'll see this in the actual definition so let's look at the retrieve all widgets endpoint this is basically basically my get SL widgets so I immediately get information on what I need to do to call the thing that's straightfor description retrieve a list of all widgets widgets are blah right uh made something up here and reiterating that this is pageable list that you get back security information yet again and this is going to be one of those things that you really got to have on every operation you really want to show folks very clearly that you're going to have to do this security stuff in order to call it a description of how those query parameters for paging work and of course what do we get back in the response when I get SL widgets the paging information's here on page and total Pages at the top but you'll note that we didn't just say page integer total Pages integer done so not only do we have the data type we describe what this does how it works like in this case it'll match your request query parameter if it was available otherwise the default is one and our example total Pages this is basically how many were available it tells me basically it supports up to 100 pages and there's an example there of 10 the items that come back in that array of widgets a widget has an ID a name and a skew these are all strings but you'll notice on the right here the name is required the skew is required in this case it's a a response so it seems a little odd it'll make more sense when we go to actually create something this is basically saying these fields should be populated again we see examples provided on what you would typically expect these to look like and in the case of name it tells us that it has to be more than one character less than 50 so we have an idea of what the range of available data is and in the skew there's actually a match pattern or regular expression that tells us here's the format that's required for this information now I noticed I missed the description on name so we can go fix that before we get started on the rest but let's go ahead and edit now obviously we're using the stop platform to do this because I'm comfortable this is easy you can do this any number of ways for the sake of a rapid example this is a quick way for me to show you the kinds of things to look at so let's go down and you'll notice here that in my response body for the 200 I can see what its contents are but it sits great out and it's because I've linked to a shared definition here in components and we can see it over here on the left widgets list paged is here and that's really just an array of widget objects are referenced from here so I can go take a look at the widget uh and let's go fix that name attribute so we got a description there there which is good so we can always preview take a look make sure yep there's the name uh were we missing an example yeah that's it so go over here click on this and we can provide an example fidget name there we go so here's some examples of things uh in open API that you can sort of specify we could say if there was a specific format like if this was a date or whatever um we can set up what a default value would be in this case I'm going to say that there is no default widget name you have to supply it um there's no particular pattern that it's checking but there's a max length of 50 Min length of one so this is kind of behind the curtain of you know some of this things that we saw in the docs view okay so I fixed that I'm going to go ahead and publish the change uh but we can look at this in preview and see now that uh I have my example on my widget name so this is a good kind of story here that we've always got examples provided any constraints defined whether or not it's required so you know just having the list of fields on something is only marginally useful without this additional context that lets consuming developers understand you know beyond what you generally mean are there very specific constraints that I have to comply with Okay so let's go back to our API for retrieving all the widgets and now we want to go take a look at creating a new operation for this API so I'm going to say we can get all the widgets let's go create one and so post uh is what in HTTP we would use to create something so let's do add a post operation and we'll say here create a widget okay that is a post to SL widgets the same URL we call to get the list let's make sure that we have a description so the description let's say create a new widget Supply the name notice this is markdown based in this platform uh so by putting the tix it's going to put kind of a little Cod view we'll see that in preview when I tab away uh and skew andd will be autogenerator okay so that give us some idea of you know what do I have to do here in this case it's simple enough I'm going to effectively double describe what we're going to do in real practice you might want to have something a little more practical and useful as to why you would do this thing so security we don't have to Define here because this is set up globally you'll notice on the right it's already showing security information here but in this case I do need to request body so let's go ahead and Define a body now uh I obviously don't want it to be a generic object I'm going to go ahead and go pick widget uh that we already defined over here in our sidebar as kind of a a shared thing between these operations so I don't have to redefine all that stuff so we see now here that the body uh has ID named skew and uh name and skew are really what's required um and in fact in a real world scenario we probably wouldn't show the ID here but I don't want to make the example too complicated so let's just say that this is the shape of object we have to pass those two fields are what's required um in a 200 okay scenario what would we to respond with um it's somewhat likely uh it's fair to say that we might want to return the widget back right uh here's what you asked to be sent here's what we send back um we make sure that the type is correct sure application Jason fair enough um now in many cases you know you will just kind of in the response say okay you could certainly do more uh we could say something like the widget has SP successfully created achieve the autogenerated ID from the response okay uh so now in our preview we start to see this kind of flushing out and you know we might look at this and say cool great like uh you know what the request body is and the fields that you need to supply what's required um and you know what you're going to get back we're done but let's remember what's the first most likely thing that our consuming developer is going to run into well let's think about adding say a 400 error bad request what if uh you know we made a mistake when we posted uh that request body so let's make sure that that uh body that we respond with again I've predefined kind of a common error for the whole platform uh so just by specifying that now all this stuff is predefined for me I certainly could in some cases provide more context in this description as to what the errors are and in this standard error object we would uh probably describe what happened in that specific error it's also not a bad idea by the way and I didn't do it in this example to describe your errors as Concepts in your getting started kind of area of your documentation I would say the bare minimum we should have our 400 we should probably have 401 unauthorized uh oops let's put that back to 400 and we'll create a new one not mistake so let's create a new response on 401 uh and again I'm I'm just always going to have every error come back with the same model I think this is generally accepted best practice if you have an API that suddenly has a whole different way of doing errors from everything else you've done might might want to talk to the developers who built it and make sure that we're following some kind of a standardized approach okay so I've got my 40 400 which is generally the the client provided something wrong in the request 401 which says you were unauthorized um you know you haven't sort of logged in in some fashion uh you don't have an API token perhaps at all 403 is perhaps you supplied a token but you didn't have access so let's describe some of this stuff right and this is the trick is you got to think why would this happen so API key was provided but uh access to this resource was not authorized can say API key missing or invalid okay and then finally we should make sure that we've covered the 500 uh and so all those other things were what did the client do wrong uh and 500 is essentially something happened wrong on the server uh file a support ticket for more he let's say that that's our support flow so now when I go look at my responses over here uh I've got my 200 and the description of the body uh but if I go look at my 400 my 401 my 403 and my 500 uh those have been described well enough that I've at least provided some context to users of here's what you're going to see when errors occur and granted if done well you're going to get this generic error object look at its contents to understand what's happened okay and I'm going to go ahead and publish these changes and we'll go back and look at kind of the docs view for it and see what this looks like all together so now on my left side I've got the get all widgets uh I've got my description of how that works and I can go look at creating a new widget uh again we see there's security information request body information and my response is both successful and unsuccessful Another Thing Worth pointing out here now that we've kind of got this fully rendered out um another sort of let's say portal feature you should be looking for um is like say in this case can I call a fake API that emulates what this would look like if I really did it if I really called this with this body supplied here's what I would get back um and for consuming clients can I get uh code samples perhaps in different languages uh or just a curl call so I can try this command line um and examples of what the response looks like without having to do the try it thing right uh so these are all generally expected kinds of features um that go beyond what your job would be as documenting an API but I think how you would render and provide good context for how to consume this we're going to go back and look at our widgets apis again we had our retrieve all widgets our create a widget let's look at the one that we created I'm going to go in and headed this and look at kind of what's under the covers here um you know we kind of focused on just getting through the documentation filling in the blanks making sure that we did all the the basics for this example but I'm actually going to switch over to our code view here and this is actually what we're producing kind of under the covers let me turn off the preview so we have more Viewpoint um so this is using open API 3.1 and you'll notice like there's an info section where we can fill in title version summary description all those things we were doing we can see the servers where we showed that widget server as what folks would use to call this as well as our paths so underneath paths we have SL widgets and then you'll notice we go into the verbs the get and we should have down here a post within our get ver basally our summary or we can put our description the individual response codes we have our 200 400 500 that we defined as well as descriptions for each of those and what the content type coming back is again we typically see application Jason on newer development and the schema in this case it gets a little bit tricky looking because I had defined a shared way of defining the widget response object and request object that we could link everywhere and this is how open API does it is this sort of dollar ref language that uses Jason pointer to play over to that we've also got a description of what that looks like this is what it's going to look like if you're writing raw open API obviously you can go read up on the open API spec and better understand how to structure these things and I should point out to that that ref where we had a link here um you know in this case it's a a specific sort of stoplight way of resolving it for those workspace wide sharables but in this case we're just pointing this widget list paged which if we go down to the bottom here we'll see components and schemas are defined in here for the widget as well as widget paged and these are really no different than defining it in line with the operation but just to break it down a little bit we've got our widget it's got title what type of object it is so in this case it's just a generic object and then the properties these are essentially the fields or ID or name or skew um what those types are whether they're string or number so like down here in our widget list page for a page number it's an integer not a string and things like pattern where we talked about that we have a a regular expression to make sure that this is 10 to 20 combination letters and numbers examples are provided in the field as well and of course our description in this case because I use stoplight we've got this stoplight thing that's an extension that goes beyond open API and youly wouldn't put that in if you're not using stop light platform and it's autogenerated for you but that we've also got here at the bottom the security schemes where we're specifying authorization and this applies to everything here and yeah so that gives you an idea of what it looks like to look directly at the open API you know ultimately when you're putting the content in here it's marked down so you'll notice like pound for headers double pound for second tier headers pretty simple stuff if you've ever looked at mark down for again that's an easy one to go Google look and see how it works but you you're generally going to see folks using markdown in here and then your portal rendering software whatever you're using is going to read that markdown and render it into something that's formatted and that's how we kind of end up for instance where uh we have these headers defined so we look at our widgets overview we look at that preview like the getting started typical usage how these things get rendered out so fairly straightforward you know call me lazy I like having this view where I don't have to do all that syntax uh but certainly there's nothing wrong with learning it and it's probably a good skill if you're working on documenting apis we're going to go back and look at our widgets apis again we had our retrieve all widgets our create a widget let's look at the one that we created I'm going to go in and headit this and look at kind of what's under the covers here um you know we kind of focused on just getting through the documentation filling in the blanks making sure that we did all the the basics for this example but I'm actually going to switch over to our code view here and this is actually what we're producing kind of under the covers let me turn off the preview so we have more Viewpoint um so this is using open API 3.1 and you'll notice like there's an info section where we can fill in title version summary description all those things we were doing we can see the servers where we showed that widget server as the what pugs would use to call this as well as our paths so underneath paths we have SL widgets and then you'll notice we go into the verbs a get and we should have down here a post within our get ver Bally our summary or we can put our description the individual Response Code so we have our 200 400 500 that we defined as well as descriptions for each of those and what the content type coming back back is again we typically see application Jason on newer development and the schema in this case it gets a little bit tricky looking because I had defined a shared way of defining the widget response object and request object that we could link everywhere and this is how open API does it is this sort of dollar ref language that uses Jason pointer to play over to that we've also got a description of what that looks like this is what it's going to look like if you're writing raw open API obviously you can go read up on the open API spec and better understand how to structure these things and I should point out too that that ref where we had a link here um you know in this case it's a a specific sort of stoplight way of resolving it for those workspace wide sharables but in this case we're just pointing this widget list paged which if we go down to the bottom here we'll see components and schemas are defined in here for the widget as well as widget paged and these are really no different than defining it in line with the operation but just to break it down a little bit we've got our widget it's got title what type of object that it is so in this case it's just a generic object and then the properties these are essentially the fields or ID or name or skew um what those types are whether they're string or a number so like down here in our widget list page for a page number it's an integer not a string and things like pattern where we talked about that we have a a regular expression to make sure that this is 10 to 20 combination letters and numbers examples are provided in the field as well and of course our description in this case because I use stoplight we've got this stoplight thing that's an extension that goes beyond open API and youly wouldn't put that in if you're not using stoplight platform and it's autogenerated for you but that we've also got here at the bottom the security schemes where we're specifying an authorization and this applies to everything here and yeah so that gives you an idea of what it looks like to look directly at the open API you know ultimately when you're putting the content in here it's marked down so you'll notice like pound for headers double pound for second tier headers pretty simple stuff if you've ever looked at markdown before again that's an easy one to go Google look see how it works but you you're generally going to see folks using markdown in here and then your portal rendering software whatever you're using is going to read that mark down and render it into something that's formatted and that's how we kind of end up for instance where're uh we have these headers defined so we look at our widgets overview we look at that preview like the getting started typical usage how these things get rendered out right so fairly straightforward you know call me lazy I like having this view where I don't have to do all that syntax uh but certainly there's nothing wrong with learning it and it's probably a good skill if you're working on documenting apis now that we've gone and tried out creating an API and and documenting it let's dig in a little bit deeper and go through some of the details so again rest API documentation is what we're generally focused on here certainly there are nuances to other forms of apis but one thing that we just kind of did in that example and we'll go back and look at it again here in a second is um we didn't start with say a Google doc or an HTML file or you know something from scratch and like hand write like putting the API on one side and a text editor on the other and writing documentation from scratch we used a tool that helped us walk through sort of filling in the blanks and the point to this is and curated content can be very difficult to scale consistent approaches across an organization so using something that generates the documentation for you means you can quickly create some internal reference you saw there in just a few minutes we were able to go Define our API and we could easily go share a link out to that to anybody else to go look at we need to be able to easily and rapidly make changes when those changes occur in the API and ultimately we need to make sure that the API docs match the functionality um this is actually one of the more common things I've said before that like broken off stuff is a really common one but right behind it is the API docs don't actually match reality because we didn't have a process to capture change or we just didn't get it right in the first place so one really powerful way to do this with rest API is open API formerly know known as Swagger is a way to describe an API without actually implementing or building one and that's what actually we just did uh and we'll kind of go back and take a look under the covers what ises that open API look like I just certainly prefer to not have to look at that syntax by default and just use a tool for me but the point is that open API is structured in a way that you can tie into your code base you can tie into other tools make sure that in an automated way everything matches so just to take another look at what API reference looks like when done well obviously in our little example that wasn't the most uh flushed out API in the case of stripes this is what most folks point to as a company they sign it incredibly well from the start each operation has this humanfriendly description when I look here I know I create a charge I charge a credit card or other payment Source I create a charge option object right it's very prun right it gives me an easy way to understand what it is that I need to do and there's also that copy paste example sample call stuff here on the right so this these again are pretty typical things folks expect out of the API documentation experience if you want to go look at what good looks like go take a look strip another great example is twio um you know this is I think number two on the list of very successful API programs that have been largely driven by their developer portal kind of developer experience they've always been brilliant at providing lots of language specific examples so on the panel there on the right you see it's provided in PHP you can change that language and their coverage is quite tremendous and I I know on the back end they're actually testing those examples every time they deploy changes so those are those examp examples work right um so you want to keep that stuff visible while you're browsing the documentation so that as you're beginning to understand how it works it's easy enough to reach over hit copy paste or you know in some cases even click the try it button and and go do it so let's take a broader look I said before that um you know there are lots of other techniques and tools and things like that uh so let's take a quick look at those so from a technique standpoint I think we've been kind of assuming in the course of discussing this that we're designing an API that has not been built yet so right here in the middle put kind of a spec based approach you know using open API like I talked about that's an example of an API specification format one of the advantages is especially if you're sharing these docs in a centralized place it minimizes duplicated effort if you're sharing a spec that you're planning to go build everyone's able to see it and thereby you can join forces or go work on something else don't accidentally build the same thing you can get earlier feedback on something before you've invested in building it find out if it's going to work for the the community that's going to consume it the cons are it is possible that if you implement it different than the spec you could get out of sync so there's certainly some mitigating approaches to address that on the left here we have code annotations this is a pretty widely popular thing for many years I think it's in some ways kind of on its way out in preference in favor of spec based but still widely out there and this is the idea that you actually go into the code and drop annotations into the code that describe what each operation does so obviously the disadvantage here is for especially someone like a tech writer or product manager having to go into a code base and make changes can be a little intimidating on the upside the code code's going to match the docs if you're generating documentation from code annotations um so it's it's harder to get out of sync and there's not any extra sort of tooling or steps that you're going to have to do again the other big downside is you've got to actually go Implement code you've got to have probably Engineers involved in at least stubbing this out before you can even begin documenting and perhaps providing mocks or something um on the right here is more of that hand curated B spoke approach it's like you're not using any specs you're not using any annotations you're just starting with simple so say content management platform and plugging in your own format for all that stuff it's easy and that you don't have to have any fancy tools you don't have to learn any kind of specs or know how to get into code document things and just about any CMS will publish any form of documentation but it is really really difficult to keep anything in sync and there's nothing contract based so there's no other tooling Downstream that's going to be able to integrate with that process so this is you know labor of love to keep it in good shape and you're going to have to do all the kind of format and design aspects to make that in a format people expect especially when you start going down the road about having code samples or you know triy it components those are things that generic cms's just not going to give you um you would have to go custom build certainly say in 2023 that's probably not a great idea so tools that are out there um obviously I have to you know plug the stoplight platform here a bit and primarily because we have a lot of open source and free options available but I would certainly point out that there's lots of great API doation platforms out there uh red doly and readme have always been pretty documentation focused uh so it's certainly one of their strong points Swagger hubs very similar to stock light and having bigger set of functionality it goes beyond docks and in the perspective that maybe you just go do something a little simpler Notions out there but you know probably not nearly as strong because it's a more Boke hand curated approach but I would certainly say you know going and doing this stuff from scratch writing specs by hand or building your Portal from scratch I mean there are so many options and I would say even just looking at GitHub um you know there's so many opsource portal generators that will take like an API spec file like open API and render that documentation for you I really couldn't advise more against going and doing this all from scratch so from there let's get into a little bit more of the best practice stuff we touched on some of the the checklist kind of things that you should always be doing first of all you've got to think about broad audience so it's important that your internal jargon is not leaking into this documentation in a way that's going to be disorienting for those consuming it now if you're building internal oriented stuff I think this is somewhat more permissible uh to use sort of jargon or acronyms but the reality is you should really fight against that Trend um because you can't always count on the fact that everybody in the company knows all these terms and having to go to some big dictionary to look up what it means it's friction filled would certainly advise challenge yourself to look past jargon and acronyms and be more clear help include folks that might not understand those things un approachable tone and plain language I think you know sometimes folks get caught up in lots of buzzword Bingo and business e sounding stuff and especially with developers using these things there's commonly a much more downto Earth straightforward way of talking and I think it can be good in terms of building that relationship with the consuming developer that he this is you know this is a friendly place to be using clear variable names function names and code samples um you know this this starts to get a little bit detailed But ultimately you don't want to have some generated sample that's you look at it and just don't really know what it means so being thoughtful about providing samples and that sort of thing can really help clarify what it is that I'm about to copy paste and use be alert to discriminatory language increasingly there's an awareness that there's words that we might use in you know especially in the traditional software world that increasingly folks might be a little insulted or offended by uh so put your best foot forward and make sure that you're not using that kind of language and making the best first impression practical guides multimedia elements so we've talked before that the reference material it's just not enough you've got to have this sort of walk through of here's the set of things need to go do in order to accomplish your use case so having things that are a little more practical in the outcome that I expect to get from this rather than a sort of mechanical you know go find all the pieces and glue them together yourself and multimedia elements here is really referring that you can include videos and maybe gifts whatever multimedia ways of delivering your content so you can certainly go above and beyond all of this content writing that we've been talking about and really provide something that's perhaps more engaging to different kinds of Learners not everyone is great at sitting down reading a bunch of text sometimes folks really appreciate having a brief video that walks them through the steps then that can be a lot more productive approach and as we pointed out throughout this you can provide simple documents and it works but having more interactivity is certainly more developer friendly we're not having to go t developers and piece together the bits from your content to then go to some different tool try out the AP it's always really convenient and timesaving if I can just click a button it says try it works so just to touch again on multimedia documentation I mention like videos with simple walkthroughs as being a really um userfriendly way to do it another approach is pictures flowcharts sometimes you've got in that cont Concepts idea and documentation Big Ideas that you have to convey and sometimes just a few diagrams pictures things like this can really help punch through the point especially with you know I think here it's called out that it's useful for Less technical users I think it's also just being tuned into the fact again people learn differently some people want to list to text some people are more Visual and want kind of a visual representation of what you're describing um and again some people want to be walked through with the videos don't be afraid to try different ways to connect with Learners as people are learning how to use your API um the other thing called out here is you know sometimes we kind of stop at this send a request get a result and that's it but you really again want to go beyond that mechanical interaction into that step by-step guide can I walk you through the process can I provide some multi media in that process that makes it easier to understand for different kinds of lers or perhaps low code developers non-technical users and uh really make the most out of that first interaction interactive docs again just to reiterate a really important to be able to copy paste examples hit the try button that sort of thing static reference material can really leave you lacking and get you pushed into using other tools it's taking away a barrier taking toil off of the end user and ultimately all that adds up you know having more media more ways to learn more ways to interact with it all of it's about creating this more positive developer experience folks coming away from it saying that was easy I want to do that again right I'm automated docs and we're going to take a pause here in just a moment and go look at this but using some sort of spec format perhaps code annotations things like this it's a really good way to try to keep things more programmatically in sync and connect more Downstream tooling to a shared definition and docs are just one of the things that you can output from that spe and accessibility this is another one that there's a lot of folks out there and in this case who estimates about 15% of the world um needs some sort of specifically accessible content so simple example of this actually is a color blindness uh it's very common thing especially among males so if you're using let's say a color palette or charts diagrams that use a certain ranges of colors for colorblind folks they can all look the same so that can be very off-putting it could really kind of suck the wife out of the multimedia content that you're providing so it's always good to think about a variety of sort of accessibility concerns involved here and it's not really that hard to go use a variety of tools that are out there that will go check your content for you and give you an idea of where it could cause problems for say visually uh impaired users um you know things like labels and all texts on images can be really helpful when you're using something like a screen reader and finally we're really going to come down to a question here is it's content up toate said it before out ofate content in API docs is super offputting and this is where having some kind of process some kind of automation some kind of connection between what you built and what you're documenting can really make a big difference um things like screenshots always seem like a great idea like this going to make this so easy to understand but you got to be really careful that you don't end up with year two old screenshots and you redesigned things since then you've added functionality that can be really disorienting if suddenly the dots you're walking through in the screenshots you're seeing don't match reality um and again this is about embracing the fact that there's an iterative life cycle to these things this is not a oneandone process the only thing you can count on with apis is they're going to change over time and you need to have a process to make sure that uh you know not just the reference material is getting updated but also those guidance tutorials task driven kinds of things are also reviewed to make sure that with the changes that we made do these things still work another thing that happens iteratively and creeps up on us is that content gets bloated right making sure that we're able to go through and really streamline and simplify what we have there take some intention as part of that iterative process that let's look at the big picture here as we've added things over time has this gotten to where it's just chore to grind through all this content and figure out what to do and another thing to watch out for within that uh in that bloat is do you have repetitive bits where you're touching on the same Concepts in too many places and it's just eating up space and cluttering up the experience and finally we didn't touch a lot on expectations around search but searching AAR large catalog of apis it can be really difficult to find the thing that you're looking for and some of this does come back to how you're documenting how you're describing things and making sure that you're optimizing for relevance so we touched on tone and this sort of thing and style is certainly a factor here too and there's some different templates folks use for style things like that really this is coming down to you know we can document one andone API sure we can maybe even do it hit Orly as a process but when we start building lots of apis across a company consistency is the name of the game that's the really hard thing to achieve is that you can do this repeatably in a way that produces things that will feel smell the same right so governance kind of security measures you know you've got to have some process you got to have some pop into how this is going to work and really focus on looking at that big picture and making sure that is this a great developer experience not just when I look at one API but when I look at all the different apis does it all feel like one so that's what's going to take you down the road of of really being able to do API documentation at a bigger scale and with that is the end of our course thank you that wraps up the API documentation best practices course hope you enjoyed it if you'd like to earn a badge and certificate for this course please enroll at appc university.com take the quizzes and we'll be happy to issue your CT and while you're there be sure to check out our other courses and certifications we also host monthly webinars with with API experts on various topics and thanks again for watching and hope to see you again soonthis course covers everything you need to know to create automate and publish API documentation that your developers partners and users will love Jason Harmon developed this course Jason brings over 20 years of experience in the technology and API world and he's the CTO of stoplight hello free code Camp community and welcome to appek University and this course on API documentation best practices my name is Dan barahona co-founder of appek University and for the next 90 minutes or so you'll learn all about API documentation including how to write good doc good documentation techniques and tools for creating documentation and even the business impact of good documentation your instructor for the course is my good friend Jason Harman CTO of stoplight and one of the most recognized experts in this field I'd also like to invite you to check out all our free courses on appc University you'll find courses on API pen testing the oasp API top 10 API security fundamentals and more all the courses on our site are free and include quizzes to assess your knowledge and if you complete everything and pass the final quiz we'll issue you a certificate and badge to recognize your accomplishment thanks again for watching and I hope you enjoy this course welcome to the documentation best practices course we're going to talk today about creating great docs and as really almost a byproduct of that why that's going to improve your security picture uh but to be clear we're going to take a big look picture at kind of documentation in general with a focus on apis doing that in a lot of companies this is the lifeblood of how software is working now quick agenda of what we're going to cover we'll talk about Who I Am wrot with just so you maybe believe why you should listen uh Define what we mean by API documentation and kind of what that entails from a business perspective why why API documentation can make a really big impact some techniques and tools and and finally best practices for what works well in this space so first up on our agenda who am I my name is Jason Harman I'm the chief technology officer at stoplight and I oversee all the giggy stuff engineering product security it I also host a podcast called apat intersection all of this is more relevant in thaten a practitioner of building platforms and and apis and that sort of thing at everything ranging from Big public companies like PayPal and Expedia group down to fast growing star type form you should and all of that has comeing into play in in my role as stoplight and I've been pretty involved in the community at large I think I've always been seen as an advocate for API documentation so let's define what we mean what is API documentation I think documentation is a big nebulous word so we're going to start start big and Whitt our way down in simple terms this is a human readable description of how developers will enable machines to communicate with each other so man of full but this is my attempt to wrap up a few different things one is documentations for humans this is for people to read and understand the developer aspect that's not the whole story we're not just talking about documentation for developers but at the end of the day the outcome um why people are engaging with these sorts of things is for developers to create connections between machines that's what apis are all about now I do think a lot of what we're going to talk about is portable to many other Realms of documentation especially technical documentation and in general in the world that we live in today interprocess communication between machines is quite often what we're doing so I think it's pretty relevant so there's a couple of different high level things that we would look at when we talk about documentation at large the first is documenting your product and this may or may not entail apis there's the second big bucket of of documenting apis and kind of the difference here is in product documentation you might be showing someone how to use a product and quite often this is going to be a point-and-click experience kind of thing where it's how do I go set this up and I can go figure that out from the documentation API documentation can be a bit of a unique creature in that one it's pretty developer Centric and again we'll talk about the other personas that we should consider but it's really about how to write code to use something pretty different in nature and this is really more where we're going to go I think there's a lot of Concepts that are applicable to both in here but we're going to focus on that kind of more developer Centric documentation to that question who is this documentation 4 and as I said developers mentioned that a number of times but it's really important when you're sitting down to write this kind of content that it's both developers and a lot of different non-developers my tagline to help remember this developers try and business buys what do I mean by that is that increasingly in in engineering and it circles leaders are looking to Developers for is this something that can use and live with and with apis this is especially important you're in essence building a relationship with another company when you use their API so you're counting on the fact that a developer you're going to have a very narrow window of attention they're going to go try it out see how it works and make a judgment call so that developer experience the big picture of it is really important and documentation is the first thing they're going to see the first thing they're going to interact with so critical to capture their imagination and confidence quickly however at the end of the day most developers are not the ones making buying decision and so there are often technology or Business Leaders or both who are involved in approving the budgets to go by these sorts of things so when we're talking about content it's important that we speak in two voices we'll look at examples of breaking this down and a way to do it that it is easy enough as a rule of thumb and speaks to these two audiences because we really need to communicate in different ways there's another kind of Matrix aspect to this which is are you building Internal Documentation for within your organization to bring Folks up to speed on how to use apis between different teams and again this could apply to other things as well or is it externally focused and this is really productized potentially monetized thing that you're going to put out there to the world and external doesn't always mean publicly open more and more more we see that partner programs and this sort of thing you might invite someone to a portal where they're going to read the documentation on how to integrate and create a long-term relationship there are definitely some nuanced differences between these these different kind of environments in internal environments really it's just fair to say that authorization and access control patterns are going to look pretty different for internal apis versus external and we'll talk talk plenty more trust me about the things that we need to pay attention to around off patterns and why they're so important but it is important to recognize that you're going to have a pretty different look on internal versus external facing um additionally for Internal Documentation you're often going to have a lot of proprietary information links to perhaps other knowledge stores on where to find out more about the implementation behind this or the team who's supporting it these sorts of things you might have operation metrics that are linked into this to point to how healthy is this thing should you trust it based on its track record of operational Health as we're in the external world you're often going to put a lot more effort into customizing The Experience putting stronger branding messaging and really some developer marketing on why should you use this thing now I do think these external concerns are starting to creep into the internal world and a thought of this is not really the documentation writer's job per se but again we're trying to look at a total developer experience which really entails many aspects so these are just things to keep in mind if you're going down the road uh let's go build a documentation Bo for apis you're going to have a pretty different consideration set depending on the environment that it's being published to but I will say that I still think that the developers try business by Mantra holds up in both okay the basic context of what is API documentation let's take a little deeper step into what are the different types as I said documentation can be a bit of a nebulous word and we really need to get a little more precise as we get into creating something practical and useful so there's really three highlevel things that you tend to see in this type of documentation and again I think a lot of this is portable to things outside of apis the first is reference material and I think for most say developers when we think about API documentation this is the stuff we're thinking about it's really the Encyclopedia of how to go use this API when you already know what it does you understand the ideas and you're ready to go write code references where you go however if you only document an API in its reference format and and we'll look at what these look like so don't worry if reference doesn't mean much to you yet all is more important is the concepts right what are the things in simple terms what does this API do but often it's not just one API it's that there's a set of ideas of why you would come use this Suite of apis what are the big things that you're trying to accomplish so in sort of product speak we might say what is the job that you're trying to do and then furthermore you might have tasks and this is where could be a whole other chain of things that need to be done you might want to showcase certain steps that users need to take in order to accomplish so these are pretty similar and it's a pretty blurry line between Concepts and tests but we'll look at some examples what these things look like so first up on API reference I just picked on one API portal here and we'll look at a few different ones but this is pager duties and one example of L their API is listing escalation policies now what we're really looking at here is reference material and you'll notice that right off the top we've got request and query parameters on the right we've got off information there's a request sample kind of falling off the bottom there we've got you know the get so the verb that's being used in HTTP and then the URL that's being called so there's a lot of kind of parameterized information for an engineer is filling in the blanks that they need on knowing how to call this thing but you'll notice a couple of things first the first paragraph of this reference material is not really speaking to developers if I looked and said what is list escalation policies mean first list all of the existing escalation policies so that tells me the list and I'm getting the existing thing that's not something that is fabricated from thin air so it's not a lot but I'm starting to learn escalation policies Define which user should be alerted at which time that's what an escalation policy is right so now we're starting to get tidbits of Concepts and this is I think to that point of if it's a non-developer who's browsing pager Duty site and saying is this something that we should be using now in this case I'm being contrived because peder duty is a pretty developer Centric product as a whole but let's imagine for a moment that I'm shopping as a non-technical user I get a sense of what this thing does now if this isn't enough this is typically a very topical description functional description of what this does we might dig into what are the concepts behind this and in this case Pedro Duty expressly calls out an API Concepts document right they have a specific thing for this but let's come back to the concepts in a moment the other part that I really want to break down for you is the anatomy of API reference material now there are certainly lots of other things out there we're going to talk about more of the rest style apis a request response kind of thing you'll notice on the far left we've got responses and across the top we've got different status codes in kind of a rest stle API 200 is good 400 the user did something wrong 500ish errors that something's wrong in the server we'll look at that in a later section a little more in detail but you notice the B section here for developers this is what we're looking for right what's the information that comes back and I need every field described in an adequate enough fashion that I know what that field means so if I looked at this and let's say offset and limit weren't described most developers would guess this is probably pagination same thing with total and more these are pretty easy but as we get into the escalation policies summary in this case is a pretty specific meaning it's short form ser generated string sync important information so it's okay this isn't really something that someone hand curated this is a server generated value this has some kind of insight built into it so I understand that there's going to be something interesting and valuable in that summary information and as we go if we went down the list of all these properties there's things to learn at every step and so just keep in mind that when you're looking at the fields were returned in the body of a response the field name itself would often have incredible ambiguity so for instance if I said look at the summary in escalation policies what does summary mean summary is a very ambiguous term it's used in lots and lots of domains and it needs a precise definition of what summary means in order for it to have adequate context to be useful now we're kind of looking at it backwards here from left to right we're looking at the response first but for what it's worth this is what people quite often want to see first is before I do all the work to make a request am I going to get in the response resp wantse does this have the data that I need but if we shift over to that request side you'll notice right off the bat Security in this case it's an API key and there's probably a whole set of steps to go get that it is an important and critical first step to making any request is there some kind of security being passed here um beyond that is all the query parameters and you might see headers as well which I have highlighted on the right and these are going to depend on what kind of endpoint or calling whether it's a get or put or a post or a delete you're going to see different kind of interaction patterns here so just keep in mind that like in this case we're looking at a list of things and you'll notice a lot of stuff with like offset and limit total these are paging controls and we'll talk about kind of consistency this is a great example of the kind of thing that I would expect if I look across all of PAG your duty apis that I would tend to see these same paging parameters and paging response parameters as a a consistent pattern so that if I write code as a client against this API I can reuse how paging works against the pager data API across many apis and not have to write a bespoke way of doing it every time I integrate with yet another operation in headers I think this is one that a lot of folks maybe don't grasp so well and it won't go too far down the rabbit hole with the API thing but in this case accept in content type these are about content negotiation and this is an important thing to cover as well in pager Duty's case they're calling out that they're using a specific media type that's bespoke to pager Duty when we look in there we see this plus Json which tells me it's going to be Json data they're just telling me that application D and pager duty is their specific domain description of what's going to be in that Jason and then version two it's another important one to cover is how are you handling versioning in pag your Duty's case they're passing it as part of a media type in the accept header and making it an implied part of their content negotiation content type is again just part of that content negotiation you'll see here application Jason it is increasingly likely that you're only going to be seeing application Json type content in apis but always be mindful that there could be other content types supported on older stuff you might see XML in specific domains you could see very specific media types to that domain something like VCF for contact information right so be mindful that developers may have multiple ways or multiple formats that they can retrieve from one API so I promised we dig into those status codes and this is a concept that we really need to embrace is that if the documentation is the first thing that a developer goes and looks to to learn how to use an API and they form their first request it's pretty likely that their first interaction with that API is going to produce an error because they don't know how to use it and maybe they've made mistakes in how they formed that request so it's essential that we describe what happens in the case that is not 200 and something 200 class errors are success 400 classes you did something wrong in 500 classes I did something wrong if you're the API Builder so for a client a 400 class error is going to tell you there's probably something wrong with the way that you provided those parameter values and you need to fix that in order to get a valid response now the shape of that error again this is one of those consistency things I'm going to dog here we're going to come back to talking about consistency but if I'm using an API from pager Duty and I use it one I'm going to write error handling code and I'm going to expect that all the other apis they offer I should be able to reuse that error handling code by and large so that's going to save me a lot of code as a client of it and not having to duplicate all those efforts from a documentation perspective one it's critical that you're focusing a lot of energy early on in what are the errors going to look like both in their shape and in their content so in this case we're really just showing the shape but it certainly is common that you might have some breakdown of what kind of errors are you're going to get and this often Beyond just the status code if we look on the right in the body you'll see that underneath that error object that is returned in the response in the case of this 400 that there's a message so you'll see in the example message and this should tell the human what's wrong there's quite often a code that's accompanied with it and this goes a level deeper than just those HTTP status codes and goes into an application specific error code and quite often having reference material that enumerates what those error codes mean will help users when they're not looking at the documentation down the road and they're writing code and they suddenly get a 400 error and some weird code in a message that they don't understand they want to be able to go back to the documentation and find what does this error mean or detail so another common practi is in these errors that you would actually provide a link back to the documentation I say it's common practice I I wish it was more common but it is a a commonly understood affordance I think more folks should Implement at the very least in our documentation we should always have some place to go look up those error codes and really just understand in general what our errors going to look like on your platform and for what it's worth bottom left here I wanted to highlight that beyond all of that customer facing or kind of API consumer facing attention that we should pay to probably their first interaction with errors the mere practice of documenting what the errors on I promise you it's going to surface weirdness in your error handling and if you don't go through that that discipline of documenting those things those are going to be surprises that no one is going to welcome this is the first taste of something we're going to hit quite a bit is that you're going to uncover quality problems here and part of that quality I think is going to be a security aspect if you have access control that don't work right and you're not getting 401 or 403 errors typically for off related issues where you expected them even as a writer who's addressing this you should be able to flag to the team that look we've got a hole in our access control that I can't explain in the documentation so this is where there's a lot of implicit quality and security enhancement that goes with documentation and I think errors is one of the big wins moving on another typical thing that you're going to see in API documentation is a try it type component where you can go get some sort of authorization token fill in the parameters and hit send API request and see what the response looks like now in some cases this might have a Sandbox environment or sort of a mock interface that gives you fake information but it should give you quick tacti feedback on what is this going to look like so this kind of gives you a no code way to try an API and for developers quite often as a way to quickly get quick test of what it is they're thinking and then on the right you'll notice the request sample so in this case it's a curl example you could certainly have language specific code examples here something that somebody can copy paste drop into their application and use as a starting point for making that call and hopefully this combination uh significantly reduces the error rate that new users are going to experience while this isn't explicitly a a feature of how you write your documentation I think from a how to present documentation this is increasingly a table Stakes feature that people expect to see in developer portals at large especially with apis coming back to I promised before we we highlighted where in patri duties API about listing escalation policies that they had a link to read about these Concepts and this is a a snippet from their documentation of what that looks like now before we got two lines that said the list escalation policies gives you a list of existing escalation policies and an escalation policy keeps track of who gets the notification whatever it was two simple sentences however in the concepts document we get a pretty comprehensive description of what this means and I won't read through it all here but I think it's a a great example of where you've got a simple functional description at top of the the reference documentation for an operation that might link back to a more comprehensive description and internally if this is an internal focused API you might also see accompanying links and material on how this is implemented on the back end or what other systems it relies on to make this work for new user when they look at those couple of sentences that quick paragraph you still don't get it you want them to be able to jump in and get a deeper definition of what something means and you'll notice in this case there's many references that link to other reference material right at the top user schedule notified incident Services all of those are other Concepts and likely other API operations they will call a group of related things in order to build a full interaction so sometimes you need these overviews to describe how these Concepts relate to each other and how they're tied together in fulfilling certain workflows although we'll come back to that more workflow oriented view uh it's important not only to describe beyond the simple paragraph and have the bigger Concepts but also what concepts does this relate to or depend on them the most important Concept in I think all documentation but is exceptionally true in API documentation is how do we get started this should be the first thing that any new user who looks for your apis and comes up on that first page they should immediately be taken down an enumerated set of steps here is what I need to do to call these apis and I say these apis intentionally to say that it hopefully isn't a lot of different ways to call a lot of different apis if there's one way to provide access that's a win for everyone from a consumption standpoint I have one way to do things from a security standpoint you'll notice right off the bat the step one and in this example we switch gears to the stripe API which I think is probably one of the strongest examples over the last 10 years or so of excellent API documentation excellent developer experience and step one in the stripe API every call to a stripe AP API must include an API secret key and then it goes on to very briefly describe here's what you need to do to get these API keys and notice it doesn't say if you're calling this API do it this way if you're calling this other API do it that way one consistent method of off is key here both in terms of usability and having a single method accessing these things so that you can really focus your effort on securing one areir area so these steps should lead me down a road of at the end of a few steps and hopefully this isn't more than four or five steps I've made a successful API call that's really the goal that you're getting to and in many API programs this is actually an instrumented thing in that we want to look at what is the time to First hello world how long does it take to get through those first steps and make the first call and a common Benchmark is to say this should take no more than 5 minutes now from a documentation standpoint this is where we take hard and make it look easy right and in some ways we have to really bench test what we're thinking about on how people are going to use this and really simplify and really Whittle things down to be easy for a new user to adopt so most important concept this is where you should be putting a ton of effort I know I said the errors were the first place to start but that's in reference this is more a Concepts so just super key especially because Step One is almost always how to do off and as the old adage goes if you're running a two-day hackathon day one is getting off done um this is quite often the inconvenient difficult tricky part and if you're building an API and documenting it this is your riskiest part so you should have a crystal CER succinct understanding of how this works for everybody preferably one way to do it for all apis so that you comprehend how it works and then you can explain it succinctly if you can't do that you probably shouldn't be publishing it you're probably taking risks and our final topic tasks again we'll look at stripe and I said Concepts and tasks can be a bit of a fuzzy line but I think the way I think of this is It's really what is the workflow that you're trying to here and what is it that you're trying to do so I often refer to this as like a showcase so in strip's case right there top left they're saying all right do you want to start an integration and they're starting with a conceptual idea payment link checkout web elements that is going to take you down at the road of learning some Concepts and learning how to do those things together this is really important in the API world because if you launch something out there with say reference material only no Concepts no workflow driven tasks people will do serendipitous things right they will come up with very creative ways to use your hii that it's in some cases you didn't plan for and just don't work so in some ways this is also projecting to end users this is what this API was meant to do this is the job that it will do for you and keeping that frame of mind for new users will guide them into using it in the way that you intended and hopefully not creating friction or problems for them El or for you not listed in kind of the big three and this is because it's not pervasively common in some ways it's a cost prohibitive concept for many programs but it's definitely a key to large scale success is that if you want quick adoption and you want API consumers to connect quickly don't make them write too much code and you can do that by providing sdks client libraries tooling around the API means you don't write code to call it explicitly you might call a library you might use a command line interface things like this and I say these can be cost prohibitive especially in the startup world or in smaller companies building and maintaining client libraries can be a very costly effort but you'll notice in Pedro Duty's case Pedro Duty didn't go build libraries to interact with its API all languages in fact many of these came from the pager Duty Community see you'll notice there's a warning on here too Community Support P Duty doesn't endorse or provide technical support so on this in some ways is how a lot of folks make this an affordable approach uh but from a documentation standpoint it's also an opportunity for you to Showcase where there could be Community Options out there that you didn't build that ultimately are going to provide a better experience faster onboarding all that sort of stuff with the caveat this isn't stuff we built and so thereby we can't really directly support it you're going to have to work with the community on that but at any rate it is an optional fourth column that in more mature programs you'll tend to see this is also very applicable for internal API programs as you reach a larger scale a larger quantity of apis it is definitely a speed accelerant to have more of these kind of client libraries command line tools So Okay so we've touched on some points in here about some of the corollary benefits that you're going to get out of investing in documentation most of it in general and and specific to this class in API documentation but let's really distill some of that out and expand on what is the value so let's say as a learner here you're thinking about learning about this concept and you're going to take it back to uh your team and say this is why I think we should do this hopefully this fills your quiver with arrows on Great Value points for investing in great documentation so why do we need to do this and I think we we touched on these bits the first is it's about education you've got to teach customers prospective customers your own employees potentially Partners about what are the things that we do and how do you connect to these things with apis um it's surprising companies that lack this sort of platform wide documentation about all their apis how you talk to say Business Leaders they don't really know exactly how things work they have a general idea but when you've got one source of Truth to document things that your company does you know the capabilities of the apis provide you have vastly more engaged and educated leaders and this applies as you work your way through the organization especially with apis because it's such a crosscutting concern through the company and it's such a distilled representation of what you do they really important that everyone understands this and obviously where the rubber meets the road on is someone going to adopt this API or not really essential that you're able to teach those folks and not just hand them the encyclopedia and walk away second you're in part often defining boundaries between products within your platform and that understanding within the organization can often transcend the way that you're organized today so we'll refer to this as like an inverse Conway maneuver the idea that Conway's law tells us if one team builds a compiler you get a one pass compiler if two teams build a compiler you get a two- pass compiler in other words if you're not intentional your software will represent how you're organized and increasingly this inverse Conway maneuver says let's be intentional about what we want the future of our uh platform to look like what if we want our capabilities to be manifested in apis so defining those boundaries uh can be really important for people to understand the customer perspective on what you do and that could apply for your own employees that could you know we touched some the education bit all of that leads into clearer definition of the things that you do which is going to heavily inform how you test and secure those product boundaries so these things can you know heavily influence how you're setting up your network your application layers all that sort of stuff as well as at the end of the day again we come back to does someone want to adopt this thing they need to understand those boundaries kind of the groupings of things right so just comprehensibility the ability for somebody to look understand the big picture quickly and then be able to drill down and understand some of the details quickly this can be very powerful organizational amplifier over time enabling customer support offerings this is another factor that isn't really documentation but you know we're the front door for these things if someone's reviewing this API or maybe they've tried it and they're stuck how do they get help documentation can help lead those consumers lead those customers to find the right kind of support I say the right kind because sometimes it's self-help only it's Community Support or there may be self-service options to go fix some of of the problems they're running into if you don't have this sort of thing then people will wander the hallways looking for help right meetings will spawn off everywhere on I'm stuck how do I get help I need to get on the phone with somebody I need to get an email chain going these things are just friction and toil let's document one place make it easy to find and finally supporting technical or developer marketing efforts in the API World um you know it's it's a weird thing to Market to this crowd because you know we have kind of a low BS threshold but in short we should be teaching not selling in kind of technical marketing efforts and rather than sending some big huge toe in an email or attaching a PDF we can link back to documentation that maybe highlights new features or points to a change log with what's the newest change to the CI and all of those things from a marketing perspective can help boost adoption again if you're teaching and not selling so who benefits from all this right and we kind of said before that you could have an internal view of this you could have an external view of this sometimes it's both but quite often you might have different apis that you offer internally or externally so the internal value is I think more than anything avoiding duplicated effort if you have undocumented apis all over your organization there's a good chance that many of these are going to be built a not very reusable way and worse if no one knows what exists there's a tendency to just look around and if you can't find it create your own and so you end up with four different ways to do the same thing and that's really not good for anybody right it's not good from a smart investment standpoint as a company it's not good for frankly job security in some cases when these things get discovered so you know avoiding that duplicated effort is just such an obvious win versus not documenting the second I mentioned there's a tendency that if you have undocumented things people will build oneoff bespoke things is that we can really promote increasing shared leverage it's a fancy word to say that rather than duplicating efforts let's join forces and build something more powerful and more reusable that we can use for a lot of different scenarios and not maybe just to enable one partnership or to connect one system somewhere so that shared leverage over time will build stronger capabilities and more aligned organizations as opposed to fragmented collections of ons and finally just beating the dead horse here on organizational understanding if you don't document the apis you have and you have this big sprawl and we'll talk about that later nobody really knows how anything works and it becomes tribal knowledge hallway discussions and email threads and meetings trying to chase down does this exist and how does it work it's just a huge weight that we can lift off the organization and really promote a lot of innovation and and speed as it builds momentum on the external side again you might be publishing to a partner Network or to a wide open publicly facing thing you obviously have to document something we're going to dism you it here to say what's the difference between adequate documentation and really great and I think done well this will promote stronger adoption from consumers and if you've got and built an API whether it's directly monetized or not you're almost always looking for can we get lots of people to use this right there's some economy of scale that comes with this along with that I mentioned before when you're evaluating an API that you're going to go use you're really in some ways evaluating what is this relationship going to be like and so let's say you have a hastily clad document that was a project artifact written by developers as a second thought and you're shuttling that over in a PDF on request that's an a great way to start a relationship is it so instead if we have durable documentation that's there on a well-known URL that's easy to find and folks are going in and having a great experience on learning making that first call less than five minutes that sort of thing we're off on the right foot with building a great relationship with whoever the API consumer is whether they be developer off the street or a close partner relationship all of these things lead to folks sticking around and being satisfied having a great developer experience and finally to the point of developers when you're marketing products to developers and in in the API world we almost always are all the no code low code is changing that somewhat folks are going to take away from that evaluation of looking using an API is was this a good experience or not and they're going to tell their friends and in the developer marketing world we deeply understand that word of mouth is key traditional marketing efforts often drive people away producing great experiences with thought leaders who share with their communities is what builds really big communities around apis so distilling this down even further let's try to boil down three big reasons that we really should be able to share with folks this is why we have to do solid documentation the first is we're going to look at this from a security standpoint this is an apis set curriculum and while it is an explicitly only about security there's a longer to documentation it is actually one of the primary reasons uh is that you can reduce risk so API exploits and I'm going to really make a strong call to action here if you've never heard of oasp go take a look in general and specifically the API top 10 was actually just refreshed in early 2023 the inconsistent or non-existent off mechanisms and this is authentication authorization U these are the reasons at the very top of the list and they have been for a long time even in the non-api top 10 is broken object level authorization or Bola and broken authen ation these are reasons one and two that API exploits are happening and at the time of putting this together looking back on 2023 we've had an unprecedented wave of API exploits and the vast majority are because of these reasons so the part that we're going to focus on is inconsistent and non-existent if you document an API what's one of the first things we're going to do getting started how to get that token and how to attach that token to the API call if that doesn't exist and you're writing that documentation the the flashing red lights are blasting there is a huge problem we cannot use this until this is fixed inconsistent I said before if you're describing how to get started you should have one way to do the off patterns if your documenting the next API and it does something wildly different big bright flashing red lights they're is a problem we have a new way to do o was that intentional is that a good idea that is inconsistent so really just catching those inconsistent or completely lacking off mechanisms it is actually one of the most important ways that you can avoid API exploits before anything's ever even in production assuming that you're documenting these before you release them and related to that is is joking that we put here missing mistakes is that if you're doing this in an iterative way every time the API is changed you're updating documentation that you essentially have audit and review built into your process now is your documentation writer always going to be the expert on what the standards are and this sort of thing not necessarily but if you have a more comprehensive review process that includes documentation those things should be caught and we'll talk a little bit more about kind some ways to build Bridges from the documentation process into a broader API design review process we'll talk about style guides and standards and these sorts of things but as you're folks writing documentation become more familiar with those Concepts just by the very Act of documenting it they're going to effectively have done a high level audit and review so it's a fantastic place to start in reducing these risks second is let's not spawn the army of zombies and it sounds like a goofy joke but this is really a thing that folks refer to in our space is the prevalence of Shadow or zombie apis and this in the it and Engineering world what we're referring to is the apis that no one knows about and this is exceedingly a huge problem is that folks are having to go dig through logs and look through production information to try to figure out what are all the apis we have because we don't even know what they do we don't know how they're authenticated we don't know what their performance is like these things could be producing huge risk vectors they could be producing terrible experiences and you'll notice here we we provided some reference to noric apis that 94% of respondents had experienced some sort of incident in the last year this is actually the second big category of risk is just the undocumented stuff the things that no one knows exist are the things that become stale that are not monitored and just present huge risks and Blindside opportunities things you don't even know exist could present vectors you're not even thinking about so really we want to build this catalog of what are the apis what are the capabilities that we have keep it maintained have process around it because if you know what you have you're able to protect it if you don't even know it exists who knows what could happen so taking this concept a little further we often refer to this notion of APs raw and while zombie or Shadow apis are the things we don't know exist sometimes sprawl is there might be some idea that these things exist there may be sporadic lists of these things floating around or there's an idea of we kind of know this is a thing but there's little cognitive alignment meaning folks don't NE necessarily have some agreement on what these things are and how they fit together as one platform and now that risk of duplication we talked about before suddenly becomes a huge problem is people building really close to the same thing over and over again and very little reusability if we have that better understanding of what are all the things and we can see them all in one place they're documented together there's some portal that manifests these things we can start to build that cognitive alignment the idea that we all understand Big Ideas in the business that we run or in the consumer base that we're serving here that ultimately will lead to Stronger alignment to Stronger execution to more satisfied customers this sort of just reiterate the lack of visibility it's going to result in less reusability right if we can see all the things we'll recognize duplication we'll recognize where there's shared leverage potential and we can be more customer Centric in how we describe things rather than describing them as a happen stance way all right so we described our top reasons that you must have these things and they're very risky scary and sometimes that's not the best place to start in justifying or convincing folks of why we should do something so let's talk about the positives the nice to have what are the benefits of doing this the first is observability and this is the antithesis of that sprawl and zombie stuff we talked about uh it's really the outcome that we're going for we want to observability we want to be able to look at the catalog of things that we have how they relate to each other and ultimately have one you know clear view of so let's say that observability is the positive outcome that you're seeking to escape the sprawl in zombies and Sh leverage already said this over and over just in the first section but getting that collaborative culture together on how to reduce the wasted effort reduce the duplicated single use case functionality and really build powerful reusable capabilities with your apis this is essential okay so we have lots of reasons that we should be doing documentation and we have an idea of kind of the the structure of what these things look like now let's get down to like who's going to do this who's going to write the docs and what's an appropriate choice in how you plan for writing your API docs and I think this is true for a lot of technical documentation and General to so developers is what we all think of right it's apis it's technical stuff developers have to document the thing they built and the reality on the ground is that the folks who built the API are not always great at being able to describe how it's used seems counterintuitive but let's say that when you're building it you have a system Centric View and when you're consuming it you don't know anything about those systems and so there's a tendency that implementers will think more about how it was built rather than how it's used and it's very difficult for them to escape those thought patterns that's not a knock that's not a criticism it's just a reality at a bare minimum we should have some kind of peer review related teams or teams that are planning to use these things at least providing that contrasting view of here's what it looks like from the outside now a pro of having Developers invol in the documentation and frankly I don't think you should try to escape developers involved inting apis is that if a developers implementing the apis partnered well with other folks they can be great about providing developer Centric feedback especially in this peer review type stuff we're describing another developer looking at what when developer bill will produce a better outcome you're going to have something that is going to have a Viewpoint that's about writing code that no one else can really provide in the organization so next in typical truct development we might see product managers who are involved and increasingly we see the role of API product managers being a thing now over the last four or five years we see this job description increasingly popping up everywhere so we describe this as occasionally who will write the docs the pro of doing it this way is that you have a very customer centered perspective compared to say a developer who's building it so that can really ultim provide an effective developer experience and this goes back to before where we said developers try business buys is you need that clear functional description and sometimes developers get into kind of the sausage making side of it rather than being a little more empathetic to the end user product managers are often naturally better at this thing now the obvious con is if you have say very non-technical product managers that lack of technical expertise could lead to some problematic ways they would describe things and this is again where putting those PMs and developers together and partnership to describe these things can be effective now who should write the docs we talked about what kind of tends to happen you know dev's building the API and wres the documentation of the task on Project or the PM maybe kicks in and helps out and cleans it up and makes it readable for customers I think you can get to perfectly adequate outcomes for that that are L effective however I think in a perfect world with no budget constraints I reach for technical writers especially those if you're doing apis who've done it before and understand the intricacies so that the pros is like I don't think it's it's well described here but it's to say that we have real professionals who understand how to communicate technical Concepts and ideas and how to be precise and thorough describing all the things it is a smart investment period or around apis in my opinion and I think it's really underutilized in so many companies it always surprises me when I find companies that don't even have technical writers so if you're going to reach for that and say let's go hire Tech writers to help with this great call but keep in mind that you can't have a team go Implement and build a whole apil row it over the fence to a tech riter and expect magic to happen you've got to have those writers involved early in the process and you've got to have some sty guide defined around this so that they're enabled to produce consistent results so document the simple basic stuff as soon as you know it even in the abstract for any implementation has happened and then iterate to release that will produce all those benefits in Tech writers being implicit QA they're going to find problems as they document things don't do all that at the end and treat a lot of friction and delivery do that from the beginning and find those problems while you're developing all right so onto our second section we've established now what is an API who writes those things why we should be doing it all these benefits but let's really break this down in in strong terms on what's the impact to a business in investing in API documentation so we already referenced before good docs matter to security reviewing those off patterns consistency these sorts of things you're going to find security issues and consistency I keep saying that word let's break that down a little bit more a lot of folks talk about standardization and really consistency in some ways is the outcome of standardizing want to have things that look and feel the same and in the business of building platforms the main difference between just a bunch of apis and something that feels like a platform is that consistency so investing in docs is going to show where you have those inconsistencies especially if you've got professional Tech writers involved consistency is the name of the game and they're going to see those things clear's day quality I I keep saying that those who write docs for an API Through The Eyes of a consumer will find quality problems they're going to find bad error handling issues they're going to find logical problems and how the API works and they're going to provide that functional view so we talked about those first few sentences in each reference material that describe what this thing does and the concepts that amend that all of that can be incredibly use for someone who's working on how are we going to test this and make sure that that it's at adequate quality if we don't know all those things early then how are we expected to test it at adequate quality and it's more secure we are leaving less room for error if we just go build an API undocumented and get ready to release and say oh security Ops Dev Ops can you uh check this out it's a terrible way to start that engagement and if they find problems then it becomes a fight because I've got to ship this thing customers are expecting it business is expecting it security and devop hooks you're holding me up that's no good right if we're able to provide documentation about what we intend this thing to be even if it's rough documentation early in the process those teams are more aware they can plan they can prepare they can do deeper Dives more questions without holding up delivery and by actually documenting the things we ship the security and devops folks are given a fighting chance against the army of zombies or the sprawl problems if they're never even made aware and someone just pushes code and there's no documentation for it how can they be expected to do a great job in defending those assets so in simple terms here at the bottom bad poorly maintained non-existent documentation these this is a leading risk for security exposures so while we're saying that consistency standardization is good sometimes so scope are we just make try to make things too perfect I don't think in this case we're looking for Perfection we're looking for existence and reasonable quality right let's reduce those risks there's no such thing as no risk but at least having reasonable documentation is going to heavily mitigate the risk that we have unmonitored assets so let's dig a little more into security right if we're taking this approach that we should document things and Design things before we build them and I know that's that sounds a little counterintuitive a little cart before the horse but it's not to say that we have perfect documentation day one before we build anything or that we have a perfect design before we've built anything it's that we should have a basic understanding of what this thing will do what it will look like before we go and get too far into implementation and realize there's problems and what's key about this in the security realm is we can review off patterns before a line of code has been written and that in itself is one of the most powerful ideas in probably addressing 80% of API equids now if you didn't document anything you didn't design up front and you just went off and built something and shipped it to production you just lost that 80% B so Security review is a pretty commonly understood thing what we would suggest here is with this documentation first design first mindset as soon as you can describe the thing that you're going to build let's start engaging in some kind of security Ry process so how do we do that API style guides are are a big step in the right direction and we're going to take a little closer look at what those look like but this in essence is saying that we have some standardized patterns in how we design our apis especially including how we do o so if your API design review incorporates security and you have some automation around style guides and these sort of things you can put a lot of really sophisticated look at things very early in the process and really cut off a lot of the problems that tend to emerge when this acument is not addressed one weapon here as we describ it in your repository can be security style guide and so really this is a subset of a broader API I to say that how do we do these security Centric things and I keep talking about off but there could be lots of other security related things in your apis for instance if it's a payment related API making sure that you don't have some exploit available to say manipulate currencies or you know some scenario that you need to be very cautious about you should have some defined standards tend to call this style guide because I don't know standards make people bristle saying that there's a style in which we design things I think is more appropriate to a design discipline so all of that can help put some guard rails around the design process and incorporate security early with that early documentation so that everyone understands what we're going to do everyone understands the risks earlier and ultimately at the end here with a a well chosen set of rules around your security and enforceable sounds a little rough here but it's just to say that do we have process that plugs in those rules somewhere that you can keep using these tools in an iterative way to keep just building stronger defenses into the future and not constantly be digging a deeper hole so all of this is taking us down a road here and you know we're going to have to say the GW I know it's not always popular but I insist we should reclaim the word governs and make it what it needs to be into the future and not the painful thing some of us have experienced from the past so a healthy documentation process is a great way to start moving toward having stronger governance and this is where we'll dig into kind of that style guide thing that I keep referring to this is about automating consistency we keep saying that when we look across a bunch of apis that consistency is the only thing that makes it feel like a platform that they all look feel smell touch the same manually maintaining that it's it's risky it's hard um as somebody who has done many manual API reviews I know I've always missed stuff it's impossible to catch it all we are not great as humans at finding these things so we should really be looking at how can we put more automation around these things so consistency standardization these things live together but how do we do that so the First with style guide and linking approaches is key one example of this it happens to be an open source project of stop lights so it does sound like I'm Shilling but I can objectively say that this is a broadly adopted artifact in the open source Community to Define governance rule sets and I think the reason it's really relevant in our learning about API documentation is there's actually do documentation Centric rule sets that you can use that do things like have all the description Fields been filled out for all the the fields in your response if that's something that you want to set a rule for and so you see here on the right an example of what a stal guide looks like and how the errors might manifest so for instance here at the top of the rules it says info contact info object should contain a contact object that might actually be a great documentation rule for let's say an internal API is okay I found the API I know what it does I read the documentation and there's something I still don't get who can I contact to find out more right so you might want to standardize and say that there should always be contact information with every API listed so could you do that manually and say oh make sure that we've always got contact information sure you might miss it and let's be honest no one really wants to do that manual review so put it on a check we can manifest an error somewhere that'll show folks hey don't forget to have this and then by the time you sit down to do some sort of manual review for the things you can't automate you don't have to worry about that this is a huge Force multiplier for kind of all things apis but surprisingly even in the documentation world we can do a lot of good here another suggestion from Talking Tech writers is Veil so Veil is basically another kind of linting engine for enforcing writing style so quite often you're going to develop a voice a certain you might adhere to say Microsoft's technical writing guideline something along those lines and you want to be able to turn on a rule set that says here is how we phrase certain Concepts or here's when we use acronyms and we don't things like that so point being with a few different tools and there certainly are some more out there but I think these these are some really leading strong ones you can make the review process predominantly automated so you can spend all of your cognitive energy on a stuff that matters what does this thing dude should it be here is it reusable and not did you remember the contact info did use an acronym or not so all of this leads down the road of stronger scaling we can replicate this kind of process this kind of automation on all the things that we do and ultimately it should lead us down a road of more reusable things things that you don't have to write BB code every time you use a different API and all of this too should lead toward something that's just pleasing to a developer's eye you know developers can't help but be precise in our nature right in building big complex things with lots of things to remember we love consistency we love to be able to look at something and go ah that is so pleasing there's nothing out of place everything's where it should be um and these kinds of approaches and automating your consistency it's an intangible difficult to measure thing but it really can produce a much better developer experience another concept here we talked a little bit about how there's internal and external apis and I keep mentioning partner networks this sort of thing in the world of Partnerships documentation is one of the most important assets that you're going to trade in the early phases is hey you want to partner with us here's how you would integrate so for those potential Partners who might be looking at your partner portal there's a few things that you can really punch through here one is brand affinity and this is where we talked about you might want to have a little more customization on the external facing stuff if they don't ever get documentation and they're having to constantly ask questions that's a terrible uh relationship so that's a bad starting point let's give them something that's our best forward but there're also just going to be in a way evaluating your company and how you operate by their interaction here so there is an implied kind of brand Affinity so when folks talk about loving strip right uh in the developer world this is a common sentiment it's because they had a great experience with that documentation they didn't have to ask anyone questions they were able to accomplish their goal without help they have a love for that brand so that's one of these tough to measure tricky and tangible things but really is something you have to keep in mind the second and I've said this a few times that API adoption if you don't know anything else about an API that's the first thing you should measure is if we went to all the trouble to build this thing these are not always easy things to build or people using it do we have a good Trend going that people are getting value from it so docs are your best tactic to push that adoption you have a crappy docks experience I promise promise it will be worse adoption than if you had a great experience and then finally is scaling and we talk about some of the processes and things that should dovetail into your documentation efforts and you're not going to be able to reach scale if you don't kind of have that game together and if you have a bunch of undocumented one andof crappy relationships you're going to struggle to scale this program so documentation is and often you know not thought about strongly as it's a critical asset in producing that scale so let's dig into the simple question of how do we write good documentation I think we've touched on a few of these different subjects we' hit it from a few angles let's get a little more practical so again just reminder we want to think about who's the the audience here are these internal developer oriented documents are they end consumers who might be external to the company are there any sort of security gates involved these are all things we want to keep in mind before we enter into this so it's always important start with those relationships understand who's going to be using it so that you're using the right voice and the right approach and enabling them some high level things on as you're sitting down to document an API a couple of high Lev things to think about first is an explanation of what request data is required what's optional an example might be the version of your API this is commonly passed in a path there's certainly other approaches like headers uh but this is often required information you need to supply which version it is that you want to get um and if it's not required that's also important uh and what happens if I don't Supply a version do I get the latest and an auto upgrades me how does all that work important to explain along the same lines Authentication any other uh sort of headers or anything that are to be expected the path to call each endpoint think this is the most seminal information in calling an API is what's that URL going to look like what HTTP methods are going to be used get postl delete the options could be other things and the request data fields what's the request body look like are there things besides the body like query stream parameters that might be passed on the other side we need to look at what's expected in the response which responses will always be there what am I going to get when I call this thing so example data always really useful as a an easy way to go beyond the documentation to what does this actually look like what status codes are possible I will'll definitely look at this in kind of a more real example but as we've said before it's not always the 200 okay that comes back sometimes we run into problems so we get errors like 400s or 500 class errors those are all different status codes that could occur and it's important to document what all those possibilities are and if there's any sort of status code or any other information that comes back what does it mean in the context of this call is there's something specific to it and again documenting one API is one thing but we also want to think about where are we sending folks when we write this document and I hope that the answer is is not we're going to email them because that's just it's not really acceptable these days we want to be able to send them a URL to here's all the apis you can find the thing that you looking for so we're really talking about death portals and things like this so think about how are people going to find these things is it discoverable as you're sitting down to write your documentation you want to think about who's going to read it and test it out and this is where some form of developer advocacy is important and there's a lot of different ways to organize this and put this into action but at a bare minimum have other internal developers read through the documents even if you don't have sort of developer relations developer advocacy who might be your contacts in the field who talk to end users a lot a little pizza and beer can go a long way recruit some folks who were not on the team building the API to go look through and try to follow the documentation and see what they run into and if possible observe them doing it where are they running into sticky spots friction where are they struggling to understand what to do next are they getting caught up in terms they don't understand and having to go read definitions and hunt for that information as we've said before what we expect is probably don't get the off right the first time this is a common story and again we want to have that be step one in getting started but making sure that not only is that documented but someone's tested it out who isn't writing the docs and who isn't building the API to make sure that it actually works in reality because if that one thing breaks nothing else works so you've got to get that right above all other things so with that let's go make a fake API let's go create something you know at least partially from scratch and see what this looks like in practice so let's take a look at our imaginary API in this case we're going to create a widget API obviously our descriptions are not going to be very verbose as they widgets a fairly Indescribable thing but from the top we see that already defined uh aversion we've come up with a base URL as well as a mock server URL this basically just means that we can call a fake API before it's actually been created information about security any additional information about who to contact any license information that might be applicable terms of service and from the top again we want to provide a simple basic description of what this thing does what is a widget right tell me that in this case there's not much to say getting started we talked about this before that in an overview of an API I should know what to do to go use it and in this case the only real prerequisite is making sure that I've done the off stuff and made up how that would work if it actually existed typical usage just gives me an idea of why people would use this thing right uh and again the description isn't terribly relevant here but this gives us an idea of content placeholders and then Concepts I've already kind of predefined and we'll look at it the idea that anywhere that we have a list of things that we would have uh some simple paging controls like page and Page size as query parameters we'll see this in the actual definition so let's look at the retrieve all widgets endpoint this is basically basically my get SL widgets so I immediately get information on what I need to do to call the thing that's straightfor description retrieve a list of all widgets widgets are blah right uh made something up here and reiterating that this is pageable list that you get back security information yet again and this is going to be one of those things that you really got to have on every operation you really want to show folks very clearly that you're going to have to do this security stuff in order to call it a description of how those query parameters for paging work and of course what do we get back in the response when I get SL widgets the paging information's here on page and total Pages at the top but you'll note that we didn't just say page integer total Pages integer done so not only do we have the data type we describe what this does how it works like in this case it'll match your request query parameter if it was available otherwise the default is one and our example total Pages this is basically how many were available it tells me basically it supports up to 100 pages and there's an example there of 10 the items that come back in that array of widgets a widget has an ID a name and a skew these are all strings but you'll notice on the right here the name is required the skew is required in this case it's a a response so it seems a little odd it'll make more sense when we go to actually create something this is basically saying these fields should be populated again we see examples provided on what you would typically expect these to look like and in the case of name it tells us that it has to be more than one character less than 50 so we have an idea of what the range of available data is and in the skew there's actually a match pattern or regular expression that tells us here's the format that's required for this information now I noticed I missed the description on name so we can go fix that before we get started on the rest but let's go ahead and edit now obviously we're using the stop platform to do this because I'm comfortable this is easy you can do this any number of ways for the sake of a rapid example this is a quick way for me to show you the kinds of things to look at so let's go down and you'll notice here that in my response body for the 200 I can see what its contents are but it sits great out and it's because I've linked to a shared definition here in components and we can see it over here on the left widgets list paged is here and that's really just an array of widget objects are referenced from here so I can go take a look at the widget uh and let's go fix that name attribute so we got a description there there which is good so we can always preview take a look make sure yep there's the name uh were we missing an example yeah that's it so go over here click on this and we can provide an example fidget name there we go so here's some examples of things uh in open API that you can sort of specify we could say if there was a specific format like if this was a date or whatever um we can set up what a default value would be in this case I'm going to say that there is no default widget name you have to supply it um there's no particular pattern that it's checking but there's a max length of 50 Min length of one so this is kind of behind the curtain of you know some of this things that we saw in the docs view okay so I fixed that I'm going to go ahead and publish the change uh but we can look at this in preview and see now that uh I have my example on my widget name so this is a good kind of story here that we've always got examples provided any constraints defined whether or not it's required so you know just having the list of fields on something is only marginally useful without this additional context that lets consuming developers understand you know beyond what you generally mean are there very specific constraints that I have to comply with Okay so let's go back to our API for retrieving all the widgets and now we want to go take a look at creating a new operation for this API so I'm going to say we can get all the widgets let's go create one and so post uh is what in HTTP we would use to create something so let's do add a post operation and we'll say here create a widget okay that is a post to SL widgets the same URL we call to get the list let's make sure that we have a description so the description let's say create a new widget Supply the name notice this is markdown based in this platform uh so by putting the tix it's going to put kind of a little Cod view we'll see that in preview when I tab away uh and skew andd will be autogenerator okay so that give us some idea of you know what do I have to do here in this case it's simple enough I'm going to effectively double describe what we're going to do in real practice you might want to have something a little more practical and useful as to why you would do this thing so security we don't have to Define here because this is set up globally you'll notice on the right it's already showing security information here but in this case I do need to request body so let's go ahead and Define a body now uh I obviously don't want it to be a generic object I'm going to go ahead and go pick widget uh that we already defined over here in our sidebar as kind of a a shared thing between these operations so I don't have to redefine all that stuff so we see now here that the body uh has ID named skew and uh name and skew are really what's required um and in fact in a real world scenario we probably wouldn't show the ID here but I don't want to make the example too complicated so let's just say that this is the shape of object we have to pass those two fields are what's required um in a 200 okay scenario what would we to respond with um it's somewhat likely uh it's fair to say that we might want to return the widget back right uh here's what you asked to be sent here's what we send back um we make sure that the type is correct sure application Jason fair enough um now in many cases you know you will just kind of in the response say okay you could certainly do more uh we could say something like the widget has SP successfully created achieve the autogenerated ID from the response okay uh so now in our preview we start to see this kind of flushing out and you know we might look at this and say cool great like uh you know what the request body is and the fields that you need to supply what's required um and you know what you're going to get back we're done but let's remember what's the first most likely thing that our consuming developer is going to run into well let's think about adding say a 400 error bad request what if uh you know we made a mistake when we posted uh that request body so let's make sure that that uh body that we respond with again I've predefined kind of a common error for the whole platform uh so just by specifying that now all this stuff is predefined for me I certainly could in some cases provide more context in this description as to what the errors are and in this standard error object we would uh probably describe what happened in that specific error it's also not a bad idea by the way and I didn't do it in this example to describe your errors as Concepts in your getting started kind of area of your documentation I would say the bare minimum we should have our 400 we should probably have 401 unauthorized uh oops let's put that back to 400 and we'll create a new one not mistake so let's create a new response on 401 uh and again I'm I'm just always going to have every error come back with the same model I think this is generally accepted best practice if you have an API that suddenly has a whole different way of doing errors from everything else you've done might might want to talk to the developers who built it and make sure that we're following some kind of a standardized approach okay so I've got my 40 400 which is generally the the client provided something wrong in the request 401 which says you were unauthorized um you know you haven't sort of logged in in some fashion uh you don't have an API token perhaps at all 403 is perhaps you supplied a token but you didn't have access so let's describe some of this stuff right and this is the trick is you got to think why would this happen so API key was provided but uh access to this resource was not authorized can say API key missing or invalid okay and then finally we should make sure that we've covered the 500 uh and so all those other things were what did the client do wrong uh and 500 is essentially something happened wrong on the server uh file a support ticket for more he let's say that that's our support flow so now when I go look at my responses over here uh I've got my 200 and the description of the body uh but if I go look at my 400 my 401 my 403 and my 500 uh those have been described well enough that I've at least provided some context to users of here's what you're going to see when errors occur and granted if done well you're going to get this generic error object look at its contents to understand what's happened okay and I'm going to go ahead and publish these changes and we'll go back and look at kind of the docs view for it and see what this looks like all together so now on my left side I've got the get all widgets uh I've got my description of how that works and I can go look at creating a new widget uh again we see there's security information request body information and my response is both successful and unsuccessful Another Thing Worth pointing out here now that we've kind of got this fully rendered out um another sort of let's say portal feature you should be looking for um is like say in this case can I call a fake API that emulates what this would look like if I really did it if I really called this with this body supplied here's what I would get back um and for consuming clients can I get uh code samples perhaps in different languages uh or just a curl call so I can try this command line um and examples of what the response looks like without having to do the try it thing right uh so these are all generally expected kinds of features um that go beyond what your job would be as documenting an API but I think how you would render and provide good context for how to consume this we're going to go back and look at our widgets apis again we had our retrieve all widgets our create a widget let's look at the one that we created I'm going to go in and headed this and look at kind of what's under the covers here um you know we kind of focused on just getting through the documentation filling in the blanks making sure that we did all the the basics for this example but I'm actually going to switch over to our code view here and this is actually what we're producing kind of under the covers let me turn off the preview so we have more Viewpoint um so this is using open API 3.1 and you'll notice like there's an info section where we can fill in title version summary description all those things we were doing we can see the servers where we showed that widget server as what folks would use to call this as well as our paths so underneath paths we have SL widgets and then you'll notice we go into the verbs the get and we should have down here a post within our get ver basally our summary or we can put our description the individual response codes we have our 200 400 500 that we defined as well as descriptions for each of those and what the content type coming back is again we typically see application Jason on newer development and the schema in this case it gets a little bit tricky looking because I had defined a shared way of defining the widget response object and request object that we could link everywhere and this is how open API does it is this sort of dollar ref language that uses Jason pointer to play over to that we've also got a description of what that looks like this is what it's going to look like if you're writing raw open API obviously you can go read up on the open API spec and better understand how to structure these things and I should point out to that that ref where we had a link here um you know in this case it's a a specific sort of stoplight way of resolving it for those workspace wide sharables but in this case we're just pointing this widget list paged which if we go down to the bottom here we'll see components and schemas are defined in here for the widget as well as widget paged and these are really no different than defining it in line with the operation but just to break it down a little bit we've got our widget it's got title what type of object it is so in this case it's just a generic object and then the properties these are essentially the fields or ID or name or skew um what those types are whether they're string or number so like down here in our widget list page for a page number it's an integer not a string and things like pattern where we talked about that we have a a regular expression to make sure that this is 10 to 20 combination letters and numbers examples are provided in the field as well and of course our description in this case because I use stoplight we've got this stoplight thing that's an extension that goes beyond open API and youly wouldn't put that in if you're not using stop light platform and it's autogenerated for you but that we've also got here at the bottom the security schemes where we're specifying authorization and this applies to everything here and yeah so that gives you an idea of what it looks like to look directly at the open API you know ultimately when you're putting the content in here it's marked down so you'll notice like pound for headers double pound for second tier headers pretty simple stuff if you've ever looked at mark down for again that's an easy one to go Google look and see how it works but you you're generally going to see folks using markdown in here and then your portal rendering software whatever you're using is going to read that markdown and render it into something that's formatted and that's how we kind of end up for instance where uh we have these headers defined so we look at our widgets overview we look at that preview like the getting started typical usage how these things get rendered out so fairly straightforward you know call me lazy I like having this view where I don't have to do all that syntax uh but certainly there's nothing wrong with learning it and it's probably a good skill if you're working on documenting apis we're going to go back and look at our widgets apis again we had our retrieve all widgets our create a widget let's look at the one that we created I'm going to go in and headit this and look at kind of what's under the covers here um you know we kind of focused on just getting through the documentation filling in the blanks making sure that we did all the the basics for this example but I'm actually going to switch over to our code view here and this is actually what we're producing kind of under the covers let me turn off the preview so we have more Viewpoint um so this is using open API 3.1 and you'll notice like there's an info section where we can fill in title version summary description all those things we were doing we can see the servers where we showed that widget server as the what pugs would use to call this as well as our paths so underneath paths we have SL widgets and then you'll notice we go into the verbs a get and we should have down here a post within our get ver Bally our summary or we can put our description the individual Response Code so we have our 200 400 500 that we defined as well as descriptions for each of those and what the content type coming back back is again we typically see application Jason on newer development and the schema in this case it gets a little bit tricky looking because I had defined a shared way of defining the widget response object and request object that we could link everywhere and this is how open API does it is this sort of dollar ref language that uses Jason pointer to play over to that we've also got a description of what that looks like this is what it's going to look like if you're writing raw open API obviously you can go read up on the open API spec and better understand how to structure these things and I should point out too that that ref where we had a link here um you know in this case it's a a specific sort of stoplight way of resolving it for those workspace wide sharables but in this case we're just pointing this widget list paged which if we go down to the bottom here we'll see components and schemas are defined in here for the widget as well as widget paged and these are really no different than defining it in line with the operation but just to break it down a little bit we've got our widget it's got title what type of object that it is so in this case it's just a generic object and then the properties these are essentially the fields or ID or name or skew um what those types are whether they're string or a number so like down here in our widget list page for a page number it's an integer not a string and things like pattern where we talked about that we have a a regular expression to make sure that this is 10 to 20 combination letters and numbers examples are provided in the field as well and of course our description in this case because I use stoplight we've got this stoplight thing that's an extension that goes beyond open API and youly wouldn't put that in if you're not using stoplight platform and it's autogenerated for you but that we've also got here at the bottom the security schemes where we're specifying an authorization and this applies to everything here and yeah so that gives you an idea of what it looks like to look directly at the open API you know ultimately when you're putting the content in here it's marked down so you'll notice like pound for headers double pound for second tier headers pretty simple stuff if you've ever looked at markdown before again that's an easy one to go Google look see how it works but you you're generally going to see folks using markdown in here and then your portal rendering software whatever you're using is going to read that mark down and render it into something that's formatted and that's how we kind of end up for instance where're uh we have these headers defined so we look at our widgets overview we look at that preview like the getting started typical usage how these things get rendered out right so fairly straightforward you know call me lazy I like having this view where I don't have to do all that syntax uh but certainly there's nothing wrong with learning it and it's probably a good skill if you're working on documenting apis now that we've gone and tried out creating an API and and documenting it let's dig in a little bit deeper and go through some of the details so again rest API documentation is what we're generally focused on here certainly there are nuances to other forms of apis but one thing that we just kind of did in that example and we'll go back and look at it again here in a second is um we didn't start with say a Google doc or an HTML file or you know something from scratch and like hand write like putting the API on one side and a text editor on the other and writing documentation from scratch we used a tool that helped us walk through sort of filling in the blanks and the point to this is and curated content can be very difficult to scale consistent approaches across an organization so using something that generates the documentation for you means you can quickly create some internal reference you saw there in just a few minutes we were able to go Define our API and we could easily go share a link out to that to anybody else to go look at we need to be able to easily and rapidly make changes when those changes occur in the API and ultimately we need to make sure that the API docs match the functionality um this is actually one of the more common things I've said before that like broken off stuff is a really common one but right behind it is the API docs don't actually match reality because we didn't have a process to capture change or we just didn't get it right in the first place so one really powerful way to do this with rest API is open API formerly know known as Swagger is a way to describe an API without actually implementing or building one and that's what actually we just did uh and we'll kind of go back and take a look under the covers what ises that open API look like I just certainly prefer to not have to look at that syntax by default and just use a tool for me but the point is that open API is structured in a way that you can tie into your code base you can tie into other tools make sure that in an automated way everything matches so just to take another look at what API reference looks like when done well obviously in our little example that wasn't the most uh flushed out API in the case of stripes this is what most folks point to as a company they sign it incredibly well from the start each operation has this humanfriendly description when I look here I know I create a charge I charge a credit card or other payment Source I create a charge option object right it's very prun right it gives me an easy way to understand what it is that I need to do and there's also that copy paste example sample call stuff here on the right so this these again are pretty typical things folks expect out of the API documentation experience if you want to go look at what good looks like go take a look strip another great example is twio um you know this is I think number two on the list of very successful API programs that have been largely driven by their developer portal kind of developer experience they've always been brilliant at providing lots of language specific examples so on the panel there on the right you see it's provided in PHP you can change that language and their coverage is quite tremendous and I I know on the back end they're actually testing those examples every time they deploy changes so those are those examp examples work right um so you want to keep that stuff visible while you're browsing the documentation so that as you're beginning to understand how it works it's easy enough to reach over hit copy paste or you know in some cases even click the try it button and and go do it so let's take a broader look I said before that um you know there are lots of other techniques and tools and things like that uh so let's take a quick look at those so from a technique standpoint I think we've been kind of assuming in the course of discussing this that we're designing an API that has not been built yet so right here in the middle put kind of a spec based approach you know using open API like I talked about that's an example of an API specification format one of the advantages is especially if you're sharing these docs in a centralized place it minimizes duplicated effort if you're sharing a spec that you're planning to go build everyone's able to see it and thereby you can join forces or go work on something else don't accidentally build the same thing you can get earlier feedback on something before you've invested in building it find out if it's going to work for the the community that's going to consume it the cons are it is possible that if you implement it different than the spec you could get out of sync so there's certainly some mitigating approaches to address that on the left here we have code annotations this is a pretty widely popular thing for many years I think it's in some ways kind of on its way out in preference in favor of spec based but still widely out there and this is the idea that you actually go into the code and drop annotations into the code that describe what each operation does so obviously the disadvantage here is for especially someone like a tech writer or product manager having to go into a code base and make changes can be a little intimidating on the upside the code code's going to match the docs if you're generating documentation from code annotations um so it's it's harder to get out of sync and there's not any extra sort of tooling or steps that you're going to have to do again the other big downside is you've got to actually go Implement code you've got to have probably Engineers involved in at least stubbing this out before you can even begin documenting and perhaps providing mocks or something um on the right here is more of that hand curated B spoke approach it's like you're not using any specs you're not using any annotations you're just starting with simple so say content management platform and plugging in your own format for all that stuff it's easy and that you don't have to have any fancy tools you don't have to learn any kind of specs or know how to get into code document things and just about any CMS will publish any form of documentation but it is really really difficult to keep anything in sync and there's nothing contract based so there's no other tooling Downstream that's going to be able to integrate with that process so this is you know labor of love to keep it in good shape and you're going to have to do all the kind of format and design aspects to make that in a format people expect especially when you start going down the road about having code samples or you know triy it components those are things that generic cms's just not going to give you um you would have to go custom build certainly say in 2023 that's probably not a great idea so tools that are out there um obviously I have to you know plug the stoplight platform here a bit and primarily because we have a lot of open source and free options available but I would certainly point out that there's lots of great API doation platforms out there uh red doly and readme have always been pretty documentation focused uh so it's certainly one of their strong points Swagger hubs very similar to stock light and having bigger set of functionality it goes beyond docks and in the perspective that maybe you just go do something a little simpler Notions out there but you know probably not nearly as strong because it's a more Boke hand curated approach but I would certainly say you know going and doing this stuff from scratch writing specs by hand or building your Portal from scratch I mean there are so many options and I would say even just looking at GitHub um you know there's so many opsource portal generators that will take like an API spec file like open API and render that documentation for you I really couldn't advise more against going and doing this all from scratch so from there let's get into a little bit more of the best practice stuff we touched on some of the the checklist kind of things that you should always be doing first of all you've got to think about broad audience so it's important that your internal jargon is not leaking into this documentation in a way that's going to be disorienting for those consuming it now if you're building internal oriented stuff I think this is somewhat more permissible uh to use sort of jargon or acronyms but the reality is you should really fight against that Trend um because you can't always count on the fact that everybody in the company knows all these terms and having to go to some big dictionary to look up what it means it's friction filled would certainly advise challenge yourself to look past jargon and acronyms and be more clear help include folks that might not understand those things un approachable tone and plain language I think you know sometimes folks get caught up in lots of buzzword Bingo and business e sounding stuff and especially with developers using these things there's commonly a much more downto Earth straightforward way of talking and I think it can be good in terms of building that relationship with the consuming developer that he this is you know this is a friendly place to be using clear variable names function names and code samples um you know this this starts to get a little bit detailed But ultimately you don't want to have some generated sample that's you look at it and just don't really know what it means so being thoughtful about providing samples and that sort of thing can really help clarify what it is that I'm about to copy paste and use be alert to discriminatory language increasingly there's an awareness that there's words that we might use in you know especially in the traditional software world that increasingly folks might be a little insulted or offended by uh so put your best foot forward and make sure that you're not using that kind of language and making the best first impression practical guides multimedia elements so we've talked before that the reference material it's just not enough you've got to have this sort of walk through of here's the set of things need to go do in order to accomplish your use case so having things that are a little more practical in the outcome that I expect to get from this rather than a sort of mechanical you know go find all the pieces and glue them together yourself and multimedia elements here is really referring that you can include videos and maybe gifts whatever multimedia ways of delivering your content so you can certainly go above and beyond all of this content writing that we've been talking about and really provide something that's perhaps more engaging to different kinds of Learners not everyone is great at sitting down reading a bunch of text sometimes folks really appreciate having a brief video that walks them through the steps then that can be a lot more productive approach and as we pointed out throughout this you can provide simple documents and it works but having more interactivity is certainly more developer friendly we're not having to go t developers and piece together the bits from your content to then go to some different tool try out the AP it's always really convenient and timesaving if I can just click a button it says try it works so just to touch again on multimedia documentation I mention like videos with simple walkthroughs as being a really um userfriendly way to do it another approach is pictures flowcharts sometimes you've got in that cont Concepts idea and documentation Big Ideas that you have to convey and sometimes just a few diagrams pictures things like this can really help punch through the point especially with you know I think here it's called out that it's useful for Less technical users I think it's also just being tuned into the fact again people learn differently some people want to list to text some people are more Visual and want kind of a visual representation of what you're describing um and again some people want to be walked through with the videos don't be afraid to try different ways to connect with Learners as people are learning how to use your API um the other thing called out here is you know sometimes we kind of stop at this send a request get a result and that's it but you really again want to go beyond that mechanical interaction into that step by-step guide can I walk you through the process can I provide some multi media in that process that makes it easier to understand for different kinds of lers or perhaps low code developers non-technical users and uh really make the most out of that first interaction interactive docs again just to reiterate a really important to be able to copy paste examples hit the try button that sort of thing static reference material can really leave you lacking and get you pushed into using other tools it's taking away a barrier taking toil off of the end user and ultimately all that adds up you know having more media more ways to learn more ways to interact with it all of it's about creating this more positive developer experience folks coming away from it saying that was easy I want to do that again right I'm automated docs and we're going to take a pause here in just a moment and go look at this but using some sort of spec format perhaps code annotations things like this it's a really good way to try to keep things more programmatically in sync and connect more Downstream tooling to a shared definition and docs are just one of the things that you can output from that spe and accessibility this is another one that there's a lot of folks out there and in this case who estimates about 15% of the world um needs some sort of specifically accessible content so simple example of this actually is a color blindness uh it's very common thing especially among males so if you're using let's say a color palette or charts diagrams that use a certain ranges of colors for colorblind folks they can all look the same so that can be very off-putting it could really kind of suck the wife out of the multimedia content that you're providing so it's always good to think about a variety of sort of accessibility concerns involved here and it's not really that hard to go use a variety of tools that are out there that will go check your content for you and give you an idea of where it could cause problems for say visually uh impaired users um you know things like labels and all texts on images can be really helpful when you're using something like a screen reader and finally we're really going to come down to a question here is it's content up toate said it before out ofate content in API docs is super offputting and this is where having some kind of process some kind of automation some kind of connection between what you built and what you're documenting can really make a big difference um things like screenshots always seem like a great idea like this going to make this so easy to understand but you got to be really careful that you don't end up with year two old screenshots and you redesigned things since then you've added functionality that can be really disorienting if suddenly the dots you're walking through in the screenshots you're seeing don't match reality um and again this is about embracing the fact that there's an iterative life cycle to these things this is not a oneandone process the only thing you can count on with apis is they're going to change over time and you need to have a process to make sure that uh you know not just the reference material is getting updated but also those guidance tutorials task driven kinds of things are also reviewed to make sure that with the changes that we made do these things still work another thing that happens iteratively and creeps up on us is that content gets bloated right making sure that we're able to go through and really streamline and simplify what we have there take some intention as part of that iterative process that let's look at the big picture here as we've added things over time has this gotten to where it's just chore to grind through all this content and figure out what to do and another thing to watch out for within that uh in that bloat is do you have repetitive bits where you're touching on the same Concepts in too many places and it's just eating up space and cluttering up the experience and finally we didn't touch a lot on expectations around search but searching AAR large catalog of apis it can be really difficult to find the thing that you're looking for and some of this does come back to how you're documenting how you're describing things and making sure that you're optimizing for relevance so we touched on tone and this sort of thing and style is certainly a factor here too and there's some different templates folks use for style things like that really this is coming down to you know we can document one andone API sure we can maybe even do it hit Orly as a process but when we start building lots of apis across a company consistency is the name of the game that's the really hard thing to achieve is that you can do this repeatably in a way that produces things that will feel smell the same right so governance kind of security measures you know you've got to have some process you got to have some pop into how this is going to work and really focus on looking at that big picture and making sure that is this a great developer experience not just when I look at one API but when I look at all the different apis does it all feel like one so that's what's going to take you down the road of of really being able to do API documentation at a bigger scale and with that is the end of our course thank you that wraps up the API documentation best practices course hope you enjoyed it if you'd like to earn a badge and certificate for this course please enroll at appc university.com take the quizzes and we'll be happy to issue your CT and while you're there be sure to check out our other courses and certifications we also host monthly webinars with with API experts on various topics and thanks again for watching and hope to see you again soon\n"