Understanding API Documentation for Upcoming Tech Writers

APIs, or Application Programming Interfaces, are sets of rules and protocols that allow different software applications to communicate with each other. They define the methods and data format programs used to request and exchange information, serving as a bridge between systems or applications. Simply put, APIs enable one piece of software to interact with another without needing to understand its internal workings, for example:

• When you use a weather app, it communicates with an API to retrieve real-time weather data from a remote server.
• When you book a flight online, the website uses APIs to pull flight data from airlines.

I am writing this piece with younger professionals in mind, particularly those exploring technical writing as a career. API documentation is a critical skill, but often writers feel unsure about how to start or where to end. Over the years, I have noticed confusion surrounding APIs among writers, who are not sure how to approach the subject.

In technical writing interviews today, candidates are frequently asked about their experience with API documentation. A typical response is, "Yes, we use Swagger." However, when probed further, it often becomes evident that the candidate's understanding of APIs is superficial. Writers are simply updating Swagger files (JSON/YAML) and uploading them, without fully grasping the underlying API concepts.

Do not get me wrong—Swagger is a fantastic tool! If Swagger had been around when I started documenting APIs, I would have used it the same way. Swagger accelerates your learning, but it is important to supplement that with a deeper understanding of the basics.

While Swagger is useful for developers, it might not be the best starting point for writers who are learning how to document APIs. It generates documentation from code, ensuring technical accuracy, but does not necessarily teach the underlying concepts writers need—like understanding HTTP methods, status codes, or crafting user-friendly content for different audiences.

Where Writers Should Start

For writers new to API documentation, starting with more conceptual tools like Postman may be more effective. These tools provide visual interfaces that help you understand API behavior without requiring you to dive into code. This allows writers to focus on writing clear explanations, examples, and instructions for their audience.

It is crucial for writers to go beyond documenting endpoints. They should capture the business use cases, API flows, and how these APIs integrate with other systems. This adds context and clarity beyond what Swagger offers, especially for REST APIs.

API Types

Primarily, Swagger is for documenting REST APIs, but there are various other API types that go beyond REST. Each type comes with its own documentation practices:

• GraphQL APIs: These APIs offer greater flexibility than REST by allowing clients to precisely request the data they need. Tools such as Apollo and GraphiQL are used for documentation and interaction with GraphQL endpoints.
• gRPC APIs: High-performance, language-agnostic APIs commonly used for microservices. These require different documentation practices, often involving Protocol Buffers (Protobuf) instead of JSON.
• SOAP APIs: Widely used in enterprise environments, SOAP APIs use XML and have their own conventions for documentation, often relying on WSDL (Web Services Description Language).
• WebSocket APIs: For real-time communication, WebSockets involve bidirectional messaging, requiring more dynamic documentation methods.

Here is a brief comparison of different API types:

• REST API: Uses simple HTTP requests with JSON payloads.
• SOAP API: Uses XML-based messaging with a more rigid structure.
• GraphQL API: Allows the client to request exactly the data they need, providing flexibility in responses.
• gRPC API: Binary and optimized for high-performance communication, often used in microservices.

Conclusion

Start with the fundamentals of how APIs work, focus on writing for your audience, and do not hesitate to explore API standards. Each has unique characteristics and documentation needs.

If this article helps clarify even if a bit your confusion around API documentation, I would be happy to hear your thoughts.

#Thinkabout

• How have you approached API documentation in your career?
• Do you use sequence diagrams to document or develop an initial understanding?
• What tools have you found most helpful in API Documentation?

Feel free to message me for any queries if you have.

*Here is an example of Mermaid code you can try out and generate a sequence diagram using draw.io. (This basic example was created with the help of ChatGPT.)

<mxGraphModel dx="1246" dy="492" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
  <root>
    <mxCell id="0" />
    <mxCell id="1" parent="0" />
    <mxCell id="u090aTTRl7yl-rY923xL-1" value="Client (User/App)" style="shape=umlLifeline;perimeter=lifelinePerimeter;whiteSpace=wrap;container=1;dropTarget=0;collapsible=0;recursiveResize=0;outlineConnect=0;portConstraint=eastwest;newEdgeStyle={&quot;edgeStyle&quot;:&quot;elbowEdgeStyle&quot;,&quot;elbow&quot;:&quot;vertical&quot;,&quot;curved&quot;:0,&quot;rounded&quot;:0};size=65;labelBackgroundColor=none;fillColor=#FAE5C7;strokeColor=#0F8B8D;fontColor=#143642;" parent="1" vertex="1">
      <mxGeometry x="40" y="20" width="150" height="940" as="geometry" />
    </mxCell>
    <mxCell id="u090aTTRl7yl-rY923xL-2" value="API Endpoint" style="shape=umlLifeline;perimeter=lifelinePerimeter;whiteSpace=wrap;container=1;dropTarget=0;collapsible=0;recursiveResize=0;outlineConnect=0;portConstraint=eastwest;newEdgeStyle={&quot;edgeStyle&quot;:&quot;elbowEdgeStyle&quot;,&quot;elbow&quot;:&quot;vertical&quot;,&quot;curved&quot;:0,&quot;rounded&quot;:0};size=65;labelBackgroundColor=none;fillColor=#FAE5C7;strokeColor=#0F8B8D;fontColor=#143642;" parent="1" vertex="1">
      <mxGeometry x="372" y="20" width="150" height="940" as="geometry" />
    </mxCell>
    <mxCell id="u090aTTRl7yl-rY923xL-3" value="Authentication Server" style="shape=umlLifeline;perimeter=lifelinePerimeter;whiteSpace=wrap;container=1;dropTarget=0;collapsible=0;recursiveResize=0;outlineConnect=0;portConstraint=eastwest;newEdgeStyle={&quot;edgeStyle&quot;:&quot;elbowEdgeStyle&quot;,&quot;elbow&quot;:&quot;vertical&quot;,&quot;curved&quot;:0,&quot;rounded&quot;:0};size=65;labelBackgroundColor=none;fillColor=#FAE5C7;strokeColor=#0F8B8D;fontColor=#143642;" parent="1" vertex="1">
      <mxGeometry x="594" y="20" width="173" height="940" as="geometry" />
    </mxCell>
    <mxCell id="u090aTTRl7yl-rY923xL-4" value="Database/Service" style="shape=umlLifeline;perimeter=lifelinePerimeter;whiteSpace=wrap;container=1;dropTarget=0;collapsible=0;recursiveResize=0;outlineConnect=0;portConstraint=eastwest;newEdgeStyle={&quot;edgeStyle&quot;:&quot;elbowEdgeStyle&quot;,&quot;elbow&quot;:&quot;vertical&quot;,&quot;curved&quot;:0,&quot;rounded&quot;:0};size=65;labelBackgroundColor=none;fillColor=#FAE5C7;strokeColor=#0F8B8D;fontColor=#143642;" parent="1" vertex="1">
      <mxGeometry x="817" y="20" width="150" height="940" as="geometry" />
    </mxCell>
    <mxCell id="u090aTTRl7yl-rY923xL-5" value="alt" style="shape=umlFrame;dashed=1;pointerEvents=0;dropTarget=0;strokeColor=#0F8B8D;height=20;width=30;labelBackgroundColor=none;fillColor=#FAE5C7;fontColor=#143642;" parent="1" vertex="1">
      <mxGeometry x="104" y="300" width="799" height="300" as="geometry" />
    </mxCell>
    <mxCell id="u090aTTRl7yl-rY923xL-6" value="[Authorized]" style="text;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;labelBackgroundColor=none;fontColor=#143642;" parent="u090aTTRl7yl-rY923xL-5" vertex="1">
      <mxGeometry x="30" width="769" height="20" as="geometry" />
    </mxCell>
    <mxCell id="u090aTTRl7yl-rY923xL-7" value="[Not Authorized]" style="shape=line;dashed=1;whiteSpace=wrap;verticalAlign=top;labelPosition=center;verticalLabelPosition=middle;align=center;strokeColor=#0F8B8D;labelBackgroundColor=none;fillColor=#FAE5C7;fontColor=#143642;" parent="u090aTTRl7yl-rY923xL-5" vertex="1">
      <mxGeometry y="207" width="799" height="4" as="geometry" />
    </mxCell>
    <mxCell id="u090aTTRl7yl-rY923xL-8" value="alt" style="shape=umlFrame;dashed=1;pointerEvents=0;dropTarget=0;strokeColor=#0F8B8D;height=20;width=30;labelBackgroundColor=none;fillColor=#FAE5C7;fontColor=#143642;" parent="1" vertex="1">
      <mxGeometry x="104" y="659" width="354" height="98" as="geometry" />
    </mxCell>
    <mxCell id="u090aTTRl7yl-rY923xL-9" value="[Resource Not Found]" style="text;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;labelBackgroundColor=none;fontColor=#143642;" parent="u090aTTRl7yl-rY923xL-8" vertex="1">
      <mxGeometry x="30" width="324" height="20" as="geometry" />
    </mxCell>
    <mxCell id="u090aTTRl7yl-rY923xL-10" value="alt" style="shape=umlFrame;dashed=1;pointerEvents=0;dropTarget=0;strokeColor=#0F8B8D;height=20;width=30;labelBackgroundColor=none;fillColor=#FAE5C7;fontColor=#143642;" parent="1" vertex="1">
      <mxGeometry x="104" y="767" width="354" height="98" as="geometry" />
    </mxCell>
    <mxCell id="u090aTTRl7yl-rY923xL-11" value="[Server Error]" style="text;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;labelBackgroundColor=none;fontColor=#143642;" parent="u090aTTRl7yl-rY923xL-10" vertex="1">
      <mxGeometry x="30" width="324" height="20" as="geometry" />
    </mxCell>
    <mxCell id="u090aTTRl7yl-rY923xL-12" value="1. Request (URL, Method, Body)" style="verticalAlign=bottom;edgeStyle=elbowEdgeStyle;elbow=vertical;curved=0;rounded=0;endArrow=block;labelBackgroundColor=none;strokeColor=#A8201A;fontColor=default;" parent="1" source="u090aTTRl7yl-rY923xL-1" target="u090aTTRl7yl-rY923xL-2" edge="1">
      <mxGeometry relative="1" as="geometry">
        <Array as="points">
          <mxPoint x="290" y="176" />
        </Array>
      </mxGeometry>
    </mxCell>
    <mxCell id="u090aTTRl7yl-rY923xL-13" value="2. Verify API Key/Token" style="verticalAlign=bottom;edgeStyle=elbowEdgeStyle;elbow=vertical;curved=0;rounded=0;endArrow=block;labelBackgroundColor=none;strokeColor=#A8201A;fontColor=default;" parent="1" source="u090aTTRl7yl-rY923xL-2" target="u090aTTRl7yl-rY923xL-3" edge="1">
      <mxGeometry relative="1" as="geometry">
        <Array as="points">
          <mxPoint x="572" y="228" />
        </Array>
      </mxGeometry>
    </mxCell>
    <mxCell id="u090aTTRl7yl-rY923xL-14" value="3. Return Authorization" style="verticalAlign=bottom;edgeStyle=elbowEdgeStyle;elbow=vertical;curved=0;rounded=0;endArrow=block;labelBackgroundColor=none;strokeColor=#A8201A;fontColor=default;" parent="1" source="u090aTTRl7yl-rY923xL-3" target="u090aTTRl7yl-rY923xL-2" edge="1">
      <mxGeometry relative="1" as="geometry">
        <Array as="points">
          <mxPoint x="575" y="280" />
        </Array>
      </mxGeometry>
    </mxCell>
    <mxCell id="u090aTTRl7yl-rY923xL-15" value="4. Fetch/Store Data" style="verticalAlign=bottom;edgeStyle=elbowEdgeStyle;elbow=vertical;curved=0;rounded=0;endArrow=block;labelBackgroundColor=none;strokeColor=#A8201A;fontColor=default;" parent="1" source="u090aTTRl7yl-rY923xL-2" target="u090aTTRl7yl-rY923xL-4" edge="1">
      <mxGeometry relative="1" as="geometry">
        <Array as="points">
          <mxPoint x="678" y="378" />
        </Array>
      </mxGeometry>
    </mxCell>
    <mxCell id="u090aTTRl7yl-rY923xL-16" value="5. Data Response" style="verticalAlign=bottom;edgeStyle=elbowEdgeStyle;elbow=vertical;curved=0;rounded=0;dashed=1;dashPattern=2 3;endArrow=block;labelBackgroundColor=none;strokeColor=#A8201A;fontColor=default;" parent="1" source="u090aTTRl7yl-rY923xL-4" target="u090aTTRl7yl-rY923xL-2" edge="1">
      <mxGeometry relative="1" as="geometry">
        <Array as="points">
          <mxPoint x="681" y="430" />
        </Array>
      </mxGeometry>
    </mxCell>
    <mxCell id="u090aTTRl7yl-rY923xL-17" value="6. Success Response (200 OK, Data)" style="verticalAlign=bottom;edgeStyle=elbowEdgeStyle;elbow=vertical;curved=0;rounded=0;dashed=1;dashPattern=2 3;endArrow=block;labelBackgroundColor=none;strokeColor=#A8201A;fontColor=default;" parent="1" source="u090aTTRl7yl-rY923xL-2" target="u090aTTRl7yl-rY923xL-1" edge="1">
      <mxGeometry relative="1" as="geometry">
        <Array as="points">
          <mxPoint x="293" y="482" />
        </Array>
      </mxGeometry>
    </mxCell>
    <mxCell id="u090aTTRl7yl-rY923xL-18" value="6. Error Response (401 Unauthorized)" style="verticalAlign=bottom;edgeStyle=elbowEdgeStyle;elbow=vertical;curved=0;rounded=0;dashed=1;dashPattern=2 3;endArrow=block;labelBackgroundColor=none;strokeColor=#A8201A;fontColor=default;" parent="1" source="u090aTTRl7yl-rY923xL-2" target="u090aTTRl7yl-rY923xL-1" edge="1">
      <mxGeometry relative="1" as="geometry">
        <Array as="points">
          <mxPoint x="293" y="580" />
        </Array>
      </mxGeometry>
    </mxCell>
    <mxCell id="u090aTTRl7yl-rY923xL-19" value="Error Response (404 Not Found)" style="verticalAlign=bottom;edgeStyle=elbowEdgeStyle;elbow=vertical;curved=0;rounded=0;dashed=1;dashPattern=2 3;endArrow=block;labelBackgroundColor=none;strokeColor=#A8201A;fontColor=default;" parent="1" source="u090aTTRl7yl-rY923xL-2" target="u090aTTRl7yl-rY923xL-1" edge="1">
      <mxGeometry relative="1" as="geometry">
        <Array as="points">
          <mxPoint x="293" y="737" />
        </Array>
      </mxGeometry>
    </mxCell>
    <mxCell id="u090aTTRl7yl-rY923xL-20" value="Error Response (500 Server Error)" style="verticalAlign=bottom;edgeStyle=elbowEdgeStyle;elbow=vertical;curved=0;rounded=0;dashed=1;dashPattern=2 3;endArrow=block;labelBackgroundColor=none;strokeColor=#A8201A;fontColor=default;" parent="1" source="u090aTTRl7yl-rY923xL-2" target="u090aTTRl7yl-rY923xL-1" edge="1">
      <mxGeometry relative="1" as="geometry">
        <Array as="points">
          <mxPoint x="293" y="845" />
        </Array>
      </mxGeometry>
    </mxCell>
    <mxCell id="u090aTTRl7yl-rY923xL-21" value="API Request (GET/POST)" style="fillColor=#FAE5C7;strokeColor=#0F8B8D;labelBackgroundColor=none;fontColor=#143642;" parent="1" vertex="1">
      <mxGeometry x="20" y="95" width="191" height="49" as="geometry" />
    </mxCell>
    <mxCell id="u090aTTRl7yl-rY923xL-22" value="Example: Ordering Pizza" style="fillColor=#FAE5C7;strokeColor=#0F8B8D;labelBackgroundColor=none;fontColor=#143642;" parent="1" vertex="1">
      <mxGeometry x="90" y="610" width="382" height="49" as="geometry" />
    </mxCell>
  </root>
</mxGraphModel>