Use cases for AI: Summarize long content

REST APIs are flourishing and consist of requests and responses between clients and servers over HTTP. There is a strong need for accurate API documentation, and technical writers can apply their skills to fill this gap. This introduction discusses different API types, reasons for API growth, and why docs are critical for REST APIs. It outlines course contents, prerequisites, goals, and target audiences. The introduction sets the stage for learning API documentation through the hands-on activities in the course.

This chapter covers using a REST API from a developer's perspective. It walks through getting API keys, making requests with Postman and curl, analyzing JSON responses, and dynamically displaying API responses on a web page. These hands-on activities provide context for understanding developer needs and how developers use APIs. After using the API, you switch perspectives and start documenting the API in the next chapter. Going through the developer workflow first gives you insight into developer requirements for documentation.

This chapter covers documenting API endpoints, the core reference documentation for APIs. It walks through the five key sections: resource description, endpoints and methods, parameters, request example, and response example/schema. These sections provide the reference details developers need to work with the API. The chapter includes a hands-on tutorial to create documentation for a sample endpoint, as well as activities to evaluate and improve existing API reference topics. The goal is to learn best practices for structuring and writing clear API endpoint documentation.

Chapter 4 covers the OpenAPI specification, which provides a standard way to describe REST APIs. The chapter introduces the OpenAPI spec and shows how tools like Stoplight Studio, Swagger UI, SwaggerHub, and Redocly can use an OpenAPI file to generate interactive API reference documentation. The chapter includes tutorials on creating an OpenAPI file both manually and using a visual editor, validating the spec, and publishing the documentation. Key topics include spec-first development, integrating reference docs into full documentation, and leveraging the OpenAPI spec to empower API design, testing, implementation, and documentation.

Chapter 5 provides a step-by-step tutorial for manually creating an OpenAPI specification document. It walks through each of the main objects in the OpenAPI spec, including openapi, info, servers, paths, components, security, tags, and externalDocs. For each object, it shows code samples and explains how the information maps to an interactive documentation site powered by the OpenAPI spec. The tutorial uses the OpenWeatherMap API as an example and shows how to build the OpenAPI document in the Swagger Editor using YAML. The goal is to gain familiarity with the OpenAPI objects and properties by building a valid OpenAPI file from scratch.

Chapter 6 focuses on the importance of testing documentation, especially for APIs and developer documentation. It emphasizes setting up a test environment, walking through all instructions personally, testing assumptions against real users, and collaborating with QA teams. Key points are that documentation should be treated like code and put through rigorous testing before release. Writers should not just passively document what developers say but actively validate everything. The chapter provides strategies for testing docs, getting access to test systems, and soliciting user feedback. Thorough testing leads to higher quality and more accurate documentation.

Chapter 7 covers the common conceptual topics that make up about half of API documentation, including product overviews, getting started tutorials, authentication and authorization, status and error codes, rate limiting and thresholds, quick reference guides, glossaries, and best practices. These conceptual topics provide critical context for understanding and using the API beyond just the reference documentation. The chapter explores best practices for each topic, reasons why the topics are often neglected, and includes examples from API documentation sites. Activities guide you to evaluate these topics in an open source API project and decide which examples demonstrate best practices. The chapter emphasizes the importance of conceptual documentation in facilitating the user's journey in understanding and adopting the API.

Chapter 8 covers techniques for documenting code, one of the most challenging aspects of API documentation, especially for non-engineers. It starts by explaining why code is difficult to document, including its non-linear nature, audience variance, and dependence on specific languages. Research provides guidance around when to document simple vs complex code, timing docs with development, focusing on "how" questions, and accommodating opportunistic learning behaviors. The chapter then explores five strategies for documenting code: separating conceptual "why" from code "how," using a third column for juxtaposed commentary, building up complexity in steps like Legos, starting simple and expanding complexity like a nautilus shell, and creating interactive browser experiences. Other code documentation forms covered include code samples, sample apps, and SDKs. The chapter concludes with assessing API design and developer experience usability.

Chapter 9 covers the 5 main steps in the API documentation writing process: planning (creating a doc plan, establishing roles), gathering information (interviewing engineers, product managers, partner engineers, QA), writing (separating content into groups, outlining, scheduling reviews, writing the first draft), reviewing (strategies for ineffective and effective reviews, incorporating feedback, resolving conflicts), and publishing (integrating new content, adding metadata, coordinating timing, publicizing releases). The chapter provides practical tips tailored to tech writers creating API documentation, such as recording engineering interviews, bringing questions to review meetings, and publicizing releases through newsletters.

This chapter covers best practices and tools for publishing API documentation. It discusses common design patterns seen in API doc sites, such as consistent structure and templates, seamless branding, abundant code samples, lengthy pages, and interactive API explorers. The chapter then explores docs-as-code tools like static site generators, version control systems, Markdown, and hosting platforms. It provides an overview of tools like Jekyll, Hugo, Sphinx, GitHub Pages, ReadTheDocs, and more. The chapter concludes with recommendations for selecting the right publishing tools based on your content, authors, infrastructure, and other requirements. The main goal is to choose lightweight tools that integrate into engineering workflows, so developers can more easily contribute to the docs.

This chapter focuses on publishing tools and workflows for technical documentation. It provides tutorials on using GitHub wikis and GitHub Desktop to manage content with Git version control. It also covers pull request workflows through GitHub as a way to collaborate on content. There is a tutorial on using Jekyll with CloudCannon for continuous deployment, and a section on using Oxygen XML with docs-as-code workflows. The chapter also profiles Blobr, an API portal that arranges API use cases into products, and includes a case study on transitioning documentation processes to docs-as-code. The chapter finishes with a frequently asked questions section on documentation tools.

This chapter focuses on getting a job in API documentation and thriving in the field. It covers the basic qualifications needed, such as familiarity with programming languages, experience writing developer docs, and a portfolio with writing samples. The chapter discusses how much code knowledge is needed and strategies for learning code. It looks at the best locations for API doc jobs, with a focus on tech hubs like California, Texas, New York, and Virginia. The chapter includes activities for finding an open source project to contribute to and creating a sample API reference topic, which will build your portfolio. Overall, the chapter provides guidance on building the skills and portfolio needed to get an API documentation job.

This chapter covers native library APIs, which are programming language-specific APIs like Java and C++ that get compiled into a developer's code rather than accessed over web protocols. It provides an overview comparing REST APIs to native library APIs. The chapter includes a tutorial on generating Javadoc documentation from a sample Java project, with details on Javadoc tags and style guidelines. It also covers Doxygen, a popular document generator for C++. The chapter emphasizes that reference documentation alone is insufficient, and technical writers need to create conceptual documentation around tasks as well. Overall, the chapter aims to clarify native library APIs and how to approach documentation for them.

Chapter 14 covers processes and methodology for managing developer portal documentation. It outlines strategies for handling both large documentation projects and smaller documentation requests, including following an adapted Scrum methodology. The chapter also discusses kickoff meetings, documentation reviews, maintaining existing docs, collecting feedback, working with external contributors, changing documentation culture, sending status reports, broadcasting meeting notes, and ensuring documentation coverage for software releases. The key themes are integrating documentation into formal processes, building visibility for the documentation team, and maintaining healthy documentation practices.

Chapter 15 discusses ways to measure API documentation quality and track improvement efforts. The chapter first looks at the challenges of relying solely on user surveys and satisfaction scores to evaluate documentation. It then surveys different research on defining documentation quality, identifying common criteria like accuracy, clarity, completeness, and relevance. The chapter introduces a comprehensive quality checklist with criteria tailored specifically to API documentation. The checklist can guide an in-depth review to assess strengths and weaknesses of documentation and identify areas needing improvement. While a scoring approach is discussed, the real value is having concrete, actionable criteria for elevating documentation quality. The checklist serves as a practical model for progress.

Chapter 16 explores practical applications of AI tools like ChatGPT and Claude for API documentation workflows. It looks at using an AI assistant plugin in Oxygen XML for tasks like improving readability, generating index terms, and fixing errors. Other applications covered include using AI for pattern-based content prompts, building automation scripts, learning code basics, getting language advice, creating doc updates for bugs, analyzing search analytics for themes, comparing API responses to docs, and assisting with glossary creation. While AI tools can't fully replace human technical writers, the chapter focuses on targeted ways AI can provide helpful assistance with certain documentation tasks, accelerating productivity.

The glossary chapter provides definitions and explanations for over 130 key terms related to API documentation. The terms span a wide range of topics relevant to documenting REST APIs, including general API concepts, OpenAPI/Swagger specifics, API parameters, responses, methods, tools, project management approaches, writing best practices, and more. This glossary serves as a quick reference for readers to look up unfamiliar documentation terminology they encounter throughout the course material. The terms are organized alphabetically as well as by common topic groups, allowing readers to easily browse terms within certain subject areas.

Chapter 18 provides a variety of supplementary material to expand on topics covered in the course. It includes a detailed article comparing REST and GraphQL APIs and recommendations for documenting each. There are several hands-on activities for calling additional APIs to get more practice working with endpoints, parameters, and responses. Tutorials are provided for two alternative API specification formats — RAML and API Blueprint. The chapter also contains answer keys for activities, as well as video recordings of full-day workshops delivering this course content. Overall, this additional resources section offers more in-depth exploration of key course topics for those looking to further solidify their learning.

This book provides a comprehensive guide to creating effective documentation for REST APIs. It approaches the topic from the perspective of a developer first using an API, then as a technical writer documenting the API. The book covers foundational concepts like making API calls, analyzing responses, and displaying data dynamically. Core skills for API documentation are then addressed, including documenting API endpoints, parameters, requests, and responses. Best practices are provided for reference docs, conceptual topics, tutorials, code samples, and testing.

The book explores tools and specifications like OpenAPI that power interactive documentation through validated machine-readable specs. It gives tutorials for creating OpenAPI files manually and with visual editors. Workflows for publishing API docs are covered in detail, including docs-as-code tools like static site generators, version control with Git, continuous deployment, and reviewing with pull requests.

Additional topics include documenting native library APIs like Javadoc, evaluating docs through quality checklists, leveraging AI for documentation tasks, creating glossaries, and managing documentation processes. The book aims to provide both strategic advice and practical skills for technical writers creating developer documentation for REST APIs. It combines big picture concepts with realistic tutorials and activities centered around sample APIs. Readers will gain the knowledge needed to create clear, usable API documentation that empowers developers to use APIs effectively.

Here is a draft chapter walking through using a REST API from a developer's perspective:

Chapter 4: Exploring a REST API as a Developer

Introduction

Understanding the developer experience is crucial for writing effective API documentation. This chapter provides hands-on practice using a sample REST API to see firsthand how developers interact with APIs. We will go through the end-to-end workflow of getting API keys, making requests, processing responses, and displaying data. These activities will build empathy for developer needs and requirements. In the next chapter, we'll switch roles and begin documenting this API, bringing hard-won lessons from the developer perspective.

Getting Set Up

Let's first get set up to start making requests. For this exercise, we will use the SpaceX API (https://api.spacex.com), a free REST API with data on SpaceX launches, rockets, and more.

To begin, you'll need to register for an API key. The SpaceX API uses token authentication, with the key passed in an Authorization header. Registering provides a test token we can use.

Now we're ready to start making requests. We'll use Postman, a popular GUI tool for testing APIs. Postman has built-in support for authorization. Install Postman and import the SpaceX API from the app library to get started.

Making GET Requests

Let's start with a simple GET request to retrieve all SpaceX launches. The endpoint is https://api.spacex.com/v4/launches.

Enter this URL in Postman. Then click Params and enter your API key in the authorization field. Send the request.

You should get a 200 OK response with launch data in JSON format. The response body contains an array of launch objects. Each object provides details like launch date, rocket name, success indicator, and more.

We can pass parameters to filter the response. Let's add launch_success=true to get only successful launches. Update the URL:

https://api.spacex.com/v4/launches?launch_success=true

Now the response only contains successful launches. We could also filter by other fields like launch year or rocket ID.

Making POST/PATCH Requests

So far we've only done basic GET requests. Let's try a POST to create a resource. The /launches endpoint supports POST to add a new launch.

Switch to the POST tab in Postman. Set the request body to JSON for a new launch. Provide launch details like name, date, and rocket ID.

Send the request. You should get a 201 Created response with the ID of the new launch. We can GET that launch ID to confirm it was added.

For updating resources, we use PATCH requests. The /launches endpoint supports PATCH to modify launches.

Let's change the launch date we created. Switch the request to PATCH and set the ID path param. Provide the new date in the body. Send the request to update the launch.

Processing JSON Responses

Until now we've looked at JSON responses in Postman. But in an actual app, how do we work with the JSON programmatically?

Let's use a little JavaScript code to parse a launch response. We'll access fields from the JSON object.

First make a GET request using curl and save the response:

curl -H "Authorization: Bearer <your_key>" https://api.spacex.com/v4/launches/latest > response.json

Now open response.json and load it into a JavaScript variable:

const response = require('./response.json');

This parses the JSON into a JavaScript object. We can access fields directly:

const launchName = response.name; 
const launchDate = response.date_local;

We could build UI or pass data to other functions. Processing JSON is critical for working with API data.

Displaying API Responses

Let's combine what we've learned to display launch data on a webpage. We'll:

1. Make API call
2. Process response
3. Insert data into HTML

First, we set up a simple HTML page with placeholders for the data:

<html>
    <h1>Latest SpaceX Launch</h1>
    
    <h2>Launch: <span id="name"></span></h2>
    <p>Date: <span id="date"></span></p>
</html>

Next, we use fetch() in JavaScript to GET the latest launch and process the response:

fetch('https://api.spacex.com/v4/launches/latest', {
    headers: {
        'Authorization': 'Bearer <your_key>'
    }
})
.then(response => response.json())
.then(data => {
    document.getElementById('name').textContent = data.name;  
    document.getElementById('date').textContent = data.date_local;
});

This makes the API call, parses the response to JSON, and inserts launch details into the page. The result is a simple page dynamically populated from API data!

Conclusion

This chapter walked through hands-on API exploration from authentication to displaying data. Key lessons for writing documentation include:

• Guide developers through all steps from getting credentials to processing responses
• Provide examples developers can easily adapt like Postman requests
• Explain how to parse and work with JSON programmatically
• Include sample code for using API data in apps and sites

Approaching documentation from this developer perspective will ensure you provide what developers need to use the API successfully. In the next chapter, we'll apply these lessons as we move to the other side and begin documenting the API.