https://idratherbewriting.com/learnapidoc/ [learnapido] * Blog * About * Contact * PDF and eBook formats * GitHub + GitHub repo + Log an issue + Closed issues * Stay updated Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,500+ subscribers. (See email archive here.) [ ] [Subscribe to newsletter] Documenting APIs Collapse All | Expand All * I: Introduction to REST APIs + Course Overview + What's new + Workshop video recordings + PDF and eBook formats + Workshop agenda, slides, activities + Why I developed this course + About the author + Introduction to REST API documentation + What is a REST API? + Activity: Identify your goals + Developer Documentation Trends: Survey Results + Glossary * II: Using an API like a developer + Scenario for using a weather API + Get authorization keys + Submit requests through Postman + curl intro and installation + Make a curl call + Understand curl more + Activity: Use methods with curl + Analyze the JSON response + Inspect the JSON from the response payload + Access and print a specific JSON value + Dive into dot notation * III: Documenting API endpoints + A new endpoint to document + API reference tutorial overview + Step 1: Resource description + Step 2: Endpoints and methods + Step 3: Parameters + Step 4: Request example + Step 5: Response example and schema + Putting it all together + Activity: What's wrong with this API reference topic + Activity: Evaluate API reference docs for core elements * IV: OpenAPI spec and generated reference docs + Overview of REST API specification formats + Introduction to the OpenAPI specification + Stoplight: Visual modeling tools for creating your spec + Getting started tutorial: Using Stoplight Studio to create an OpenAPI specification document + Swagger UI tutorial + SwaggerHub introduction and tutorial + Swagger UI Demo + Integrating Swagger UI with the rest of your docs + Redocly tutorial -- authoring and publishing API docs with Redocly's command-line tools + Redoc Community Edition Basic Demo * V: Step-by-step OpenAPI code tutorial + OpenAPI tutorial using Swagger Editor and Swagger UI: Overview + Working in YAML + Step 1: The openapi object + Step 2: The info object + Step 3: The servers object + Step 4: The paths object + Step 5: The components object + Step 6: security object + Step 7: The tags object + Step 8: The externalDocs object + Activity: Create an OpenAPI specification document * VI: Testing API docs + Overview of testing your docs + Set up a test environment + Test all instructions yourself + Test your assumptions + Activity: Test your project's documentation * VII: Conceptual topics in API docs + API conceptual topics overview + API product overviews + API getting started tutorials + API authentication and authorization + API status and error codes + API rate limiting and thresholds + API quick reference + API glossary + API best practices + Activity: Complete the SendGrid Getting Started tutorial + Activity: Assess the conceptual content in your project * VIII: Code tutorials + Common characteristics of code tutorials + Why documenting code is so difficult + What research tells us about documenting code + Five strategies for documenting code + Code samples + Sample apps + SDKs (software development kits) + API design and usability + Developer experience (DevX) usability * IX: The writing process + Overview of the writing process + 1. Planning + 2. Information gathering + 3. Writing + 4. Reviewing + 5. Publishing * X: Publishing API docs + Overview for publishing API docs + Survey of API doc sites + Design patterns with API doc sites + Docs-as-code tools + More about Markdown + Version control systems (e.g., Git) + Activity: Manage content in a GitHub wiki + Activity: Use the GitHub Desktop Client + Activity: Pull request workflows through GitHub + Static site generators + Hosting and deployment options + Hybrid documentation systems + Using Oxygen XML with docs-as-code workflows + Which tool to choose for API docs -- my recommendations + Jekyll and CloudCannon continuous deployment tutorial + Case study: Switching tools to docs-as-code + Tools FAQ * XI: Thriving in the API doc space + The job market for API technical writers + How much code do you need to know? + Best locations for API documentation jobs + Activity: Find an Open-Source Project + Activity: Create or fix an API reference documentation topic * XII: Native library APIs + Overview of native library APIs + Get the sample Java project + Java crash course + Activity: Generate a Javadoc from a sample project + Javadoc tags + Explore the Javadoc output + Make edits to Javadoc tags + Doxygen, a document generator mainly for C++ + Create non-ref docs with native library APIs * XIII: Processes and methodology + DX content strategy with developer portals + Following agile scrum with documentation projects + Managing large documentation projects + Managing small documentation requests + Managing SDK releases + Documentation kickoff meetings and product demos + Processes for reviewing documentation + Maintaining existing documentation + Collecting feedback post-release + Managing content from external contributors + Changing internal doc culture + Sending doc status reports -- a tool for visibility and relationship building + Broadcasting your meeting notes to influence a wider audience + Ensuring documentation coverage with each software release * XIV: Metrics and measurement + Measuring progress against documentation quality goals + First-level checklist for API documentation + Second-level checklist for API documentation + Quantifying your progress + Templates for working with metrics * XV: Additional resources + Documenting GraphQL APIs + More REST API activities + Activity: Get event information using the Eventbrite API + Activity: Retrieve a gallery using the Flickr API + Activity: Get wind speed using the Aeris Weather API + RAML tutorial + API Blueprint tutorial + API jeopardy answer key + What's wrong with this topic answer key + Menlo Park API workshop video recording + Denver API workshop video recording + API doc presentation video recordings --------------------------------------------------------------------- SwaggerHub: The Platform for Designing and Documenting APIs with Swagger Follow me on social media Search results Search powered by Algolia 1. I'd Rather Be Writing 2. Learn API Doc 3. Documenting APIs: A guide for technical writers and engineers Last updated: Dec 28, 2021 In this course on writing documentation for APIs, instead of just talking about abstract concepts, I contextualize APIs with a direct, hands-on approach. You'll first learn about API documentation by using a simple weather API to put a weather forecast on your site. As you use the API, you'll learn about endpoints, parameters, data types, authentication, curl, JSON, the command line, Chrome's Developer Console, JavaScript, and more. The idea is that rather than learning about these concepts independent of any context, you learn them by immersing yourself in a real scenario while using an API. Immersion in real scenarios makes these tools and technologies more meaningful. We'll then transition into standards, tools, and specifications for REST APIs. You'll learn about the required sections in API documentation, analyze examples of REST API documentation from various companies, learn how to join an open-source project to get experience, and more. * About REST APIs * From practice to documentation * Who the course is for * Course organization * Sequence and activities * How long will it take to finish the course? * Will this course help you get a job in API documentation? * No programming skills required * What you'll need * Testing Your Setup * Video recordings * Course slides * Copyright and re-use of materials * Is this course really free? * PDF and Kindle/eBook formats * Let me know if any content is out of date * Stay updated * Other resources About REST APIs In a nutshell, REST APIs (which are a type of web API) involve requests and responses, not too unlike visiting a web page. You make a request to a resource stored on a server, and the server responds with the requested information. The protocol used to transport the data is HTTP. "REST" stands for Representational State Transfer. Response and request model for REST APIsREST APIs involve requests and responses over HTTP protocol I dive more into the principles of REST in What is a REST API? In your REST API documentation, you describe the various endpoints available, their methods, parameters, and other details, and you also document sample responses from the endpoints. From practice to documentation In this course, after you practice using an API like a developer, you'll then shift perspectives and "become a technical writer" tasked with documenting a new endpoint that engineers added to an API. As a technical writer, you'll tackle each element of a reference topic in REST API documentation: 1. Resource descriptions 2. Endpoints and methods 3. Parameters 4. Request example 5. Response example Exploring each of these sections will give you a solid understanding of how to document REST APIs. You'll also learn how to document the conceptual sections for an API, such as the getting started tutorial, product overview, status and error codes, request authorization, and more. You'll also dive into different ways to publish REST API documentation, exploring tools and specifications such as GitHub, static site generators like Jekyll, and other docs-as-code approaches . You'll learn how to leverage templates, build interactive API consoles so users can try out requests and see responses, and learn how to manage your content through version control. We'll also dive into specifications such as the OpenAPI specification and Swagger UI (which provides tooling for the OpenAPI specification). Additionally, you'll learn how to document native library APIs and generate Javadoc. Tech writing is about more than tools and technology, though. As such, I even explore processes and methodologies in depth, explaining how to manage both large and small documentation projects, how to collect documentation feedback, how to keep stakeholders happy and updated, and more. I've also included a section on metrics and measurement, which lists a comprehensive first-level quality checklist as well as a second-level checklist. The criteria described can help you evaluate your own developer portal in myriad ways against industry best practices. Throughout this course, I put these concepts in real, applicable contexts with hands-on activities and demos. Who the course is for The course primarily serves the following audiences: * Professional technical writers looking to transition from traditional documentation into more API-focused documentation for developers. * Students learning how to prepare themselves technically to succeed in the tech comm field, which is becoming more focused on developer documentation. * Developers who are documenting their own APIs and want to know best practices for structure, terminology, and style with tech docs. * Educators who are training technical writing students about API documentation practices and technologies. Course organization The course consists of the following sections: * I: Introduction to REST APIs * II: Using an API like a developer * III: Documenting API endpoints * IV: OpenAPI spec and generated reference docs * V: Step-by-step OpenAPI code tutorial * VI: Testing API docs * VII: Conceptual topics in API docs * VIII: Code tutorials * IX: The writing process * X: Publishing API docs * XI: Thriving in the API doc space * XII: Native library APIs * XIII: Processes and methodology * XIV: Metrics and measurement * XV: Additional resources Sequence and activities You don't have to read the sections in order -- feel free to skip around as you prefer. Some of the earlier sections (such as the section on Using a REST API like a developer and Documenting endpoints follow a somewhat sequential order with the same weather API scenario, but by and large you can jump around as desired. Because the purpose of the course is to help you learn, there are many activities that require hands-on coding and other exercises. Along with the learning activities, there are also conceptual deep dives, but the focus is always on learning by doing. Where there are hands-on activities, I typically include this icon in the section title: . Other topics have the word "Activity" in the title. The activities are integrated into various sections, but you can also see many of the activities in the Workshop Activities. These are the activities we do during live workshops. I refer to the content here as a "course" instead of a book or a website, primarily because I include a lot of exercises throughout in each section, and I find that people who want to learn API documentation prefer a more hands-on "course" experience. Below each topic is a progress indicator that reminds you to keep moving through the course. How long will it take to finish the course? Don't be daunted if you never make it entirely through the course. If printed to PDF, the content is about 900 pages. And I keep adding to the content, refining it, rearranging and adjusting it as I see fit and as I grow my experience and awareness. It's a living document. Almost no one really finishes the course from beginning to end because by the time they do, I'll have added new content. Also, you should only focus on those sections that you need to learn. See this Reddit post, Has anyone here completed the idratherbewriting API writing course by Tom Johnson?. For someone already familiar with many concepts, they can breeze through the course in less than a week. For someone new to API documentation, they might spend many months making their way through the course. If you keep finding value in the content, take as long as you want. If you don't find yourself learning anything, skip forward. Will this course help you get a job in API documentation? The most common reason people take this course is to transition into API documentation. This course will help you make that transition, but you can't just passively read through the content. You need to do the activities outlined in each section, especially those topics that involve working with content from an open-source project (or something similar). These activities are crucial to building experience and credibility with a portfolio. I provide more details in Getting an API documentation job and thriving. Without a strong portfolio to demonstrate your writing expertise, almost no manager will hire you, even if you have an extensive tech background. No programming skills required As for the needed technical background for the course, you don't need any programming background or other prerequisites, but it will help to know some basic HTML, CSS, and JavaScript. If you do have some familiarity with programming concepts, you might speed through some of the sections and jump ahead to the topics you want to learn more about. This course assumes you're a beginner, though. Some of the code samples in this course use JavaScript. JavaScript may or may not be a language that you actually use when you document REST APIs, but most likely there will be some programming language or platform that becomes important to know. JavaScript is one of the most useful and easy languages to become familiar with, so it works well in code samples for this introduction to REST API documentation. JavaScript allows you to test code by merely opening it in your browser (rather than compiling it in an IDE). (I have a quick crash-course in JavaScript here if you need it.) What you'll need Here are a few tools you'll need to do the activities in this course: * Computer. You need a computer (if attending the live workshop, a laptop and charging cord), as there are many activities to work through. * Text editor. If you don't already have a favorite text editor, download Sublime Text, as it works well on both Mac and Windows and is free. If you have another text editor you prefer (e.g., Visual Studio Code, Atom, or even Notepad++), that will work too. Just make sure you can write code in plain text. * Chrome browser. Chrome provides a Javascript Console that works well for inspecting JSON, so we'll be using Chrome. Also, in order to read JSON responses more easily in the browser, install the JSON Formatter Chrome extension. * Postman. Postman is an app that allows you to make requests and see responses through a visual client. Make sure you download the app and not the Chrome extension. * curl. curl is essential for making requests to endpoints from the command line. Mac already has curl built-in, but it might not be available by default on Windows. (Some Windows 10 builds already have it in Powershell.) On Windows, open a Command Prompt and type curl -V. If it's not installed, go to confusedbycode.com/ curl and install a version (usually "With Administrator Privileges (free), 64-bit"). Close and re-open your Command Prompt and try typing curl -V again. * Git. Git is a version control tool developers often use to collaborate on code. For Windows, see https://gitforwindows.org/ to set up Git and the Git BASH terminal emulator. For Mac, see Downloading Git. * GitHub account. GitHub will be used for various activities, sometimes to demonstrate the Git workflow and other times as an authentication service for developer tools. If you don't already have a GitHub account, sign up for one. * Stoplight Studio Editor. When working with the OpenAPI specification, we'll use the Stoplight Studio Editor. Stoplight Studio provides visual modeling tools for working with the OpenAPI specification. Stoplight offers both a web browser and standalone app versions of the editor. We'll be using the web browser version because it provides more complete functionality (such as trying out requests). Go to https://stoplight.io/studio and log in with GitHub. * OpenWeatherMap API key. We'll be using the OpenWeatherMap API for some exercises. It takes a couple of hours for the OpenWeatherMap API key to become active, so it's best if you get the API key ahead of time -- then when you get to the OpenWeatherMap API activities, you'll be all set. To get your (free) OpenWeatherMap API key, go to https://openweathermap.org/. Click Sign Up in the top nav bar and create an account. After you sign up, OpenWeatherMap sends you an API key to your email. you can also find it when you log in and click the API Keys tab from the dashboard. Copy the key into a place you can easily find it. Testing Your Setup In the past, people have asked for some tests to check whether their laptops are correctly set up. * If you want to test whether Postman works, open up the Postman app and paste this into the GET box: https:// api.openweathermap.org/data/2.5/weather?zip=95050&units=imperial& appid=126cac1a482f51de0f1287b45ae2bf9a. Then click Send. If you get a response, it's working correctly. (In rare cases, sometimes people have security restrictions on their computers that block all network access.) * If you want to test whether curl is installed, open Terminal (on Mac) or Command Prompt (on Windows) and paste in curl --get "https://api.openweathermap.org/data/2.5/weather?zip=95050&units= imperial&appid=126cac1a482f51de0f1287b45ae2bf9a". If you get a JSON response, you're good. * To check whether Git is installed, open up Terminal (on Mac) or Command Prompt (on Windows) and type git --version. If it's installed, you'll see the version. Video recordings For video recordings of this course, see the Video recordings of API doc workshops. The page lists the most recent video recordings available. The video doesn't go into the same level of detail as the written material, but it would be a good start. See my Upcoming Presentations on my blog for details about future workshops and presentations. Course slides For the live workshops, I have various slides that cover different sections of this course. See Course Slides for the links. The slides use RevealJS, which is an HTML/CSS/JS framework for slides. The images are single-sourced between the site and the slides, so they'll more likely stay in sync. Copyright and re-use of materials Some people have asked whether they can use materials from this course to give their own API documentation workshops. I only allow the material to be used for non-profit workshops where the workshop leader isn't charging participants for the instruction. Of course, many of the ideas and concepts in this course aren't specific or unique to me, and you're entitled to fair use. However, please don't just hijack my site's materials, activities, and other information for your own commercial endeavors. If you're a teacher at a college or university (or high school) and are trying to teach APIs and developer docs to your students, feel free to use this site as part of your instructional materials. I appreciate links back to the site and attribution as needed (links pointing to my site boost search engine rankings). My larger goal for this site is to help educate and empower tech writers with developer documentation strategies, workflows, and best practices. If you'd like to share your API documentation course syllabus, contact me and I'll add a link here. Is this course really free? Yes, this course is entirely free. Advertising helps make this content free, so you will see little text snippets and other ads on the course pages promoting links to API service providers. Sometimes I also include sponsored pages as well to highlight a vendor's particular offerings. Whenever content is sponsored, I note that on the page. I also wouldn't include any content in the course that didn't meet my standards or which I wouldn't recommend. If you'd like to give back, feel free to buy me coffee by clicking the Buy me a coffee button on the bottom of each page. I'm grateful to see many people who find enough value in the course to contribute back. Seeing contributions helps me feel in a more immediate way how much the content helps people. PDF and Kindle/eBook formats To read the same content in PDF or Kindle/eBook formats, see [PDF and eBook formats][docapis_formats.html]. You can print out the section you want, or load it into a PDF reader to highlight/annotate content. Or if you prefer Kindle or another eReader, download the content in ebook format and load it onto your device. Let me know if any content is out of date One of the challenges in any technical course is ensuring the content stays up to date. Technology changes rapidly, and given the many hands-on activities in the course, it's easy for some steps to become out of date as time passes. I've tried to maintain a healthy balance between general and specific details in the content here. If you find something is out of date, either add a comment on that page or let me know. Stay updated If you're following this course, you most likely want to learn more about APIs. I publish regular articles that talk about APIs and strategies for documenting them. You can stay updated about these posts by subscribing to my free newsletter. My newsletter (send 2-3 times a month) contains excerpts of new pages added to this API course as well as the latest posts I publish on my blog, idratherbewriting.com. Other resources If you've looking for additional resources to learn API documentation as well as tech writing best practices, check out the following: * Docs for Developers: An Engineer's Field Guide to Technical Writing, Authors: Bhatti, J., Corleissen, Z.S., Lambourne, J., Nunez, D., Waterhouse, H. * Modern Technical Writing: An Introduction to Software Documentation, by Andrew Etter * Documentation Guide - Write the Docs Community * Docs Like Code, by Anne Gentle * Every Page Is Page One: Topic-Based Writing for Technical Communication and the Web, by Mark Baker * Peter Gruenbaum's API doc courses on Udemy. (Multiple courses on API docs, Swagger, Git, and more.) * The Design of Web APIs, by Arnaud Lauret * The Product is Docs: Writing technical documentation in a product development group, by Christopher Gales and Splunk Documentation Team * The Good Docs Project: Best practice templates and writing instructions for documenting open source software * Google's technical writing courses for engineers * Standards and Guidelines for API Documentation: For Technical Writers, Software Developers, Information and Software Architects , by Anne Tarnoruder For even more books, see Relevant Books from the Write the Docs site. Buy me a coffeeBuy me a coffee Stay updated Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,500+ subscribers. (See email archive here.) [ ] [Subscribe to newsletter] 2% Complete 2/162 pages complete. Only 160 more pages to go. --------------------------------------------------------------------- << Previous: Introduction to REST APIs NEXT >> What's new --------------------------------------------------------------------- About Learn API Doc This site provides tutorials for documenting REST APIs. This content is intended for technical writers working on REST API documentation projects. Links + Blog + Contact + Presentations Social media + WTD Slack + Twitter + Linkedin Contribute back + Suggest edits in GitHub repo (c) 2019, Tom Johnson