Search results

Workshop activities

Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 4,500+ subscribers

For API workshops, it helps to consolidate activities into a single page with brief instructions. The content for the activities below is the same content that appears in other parts of the course — it’s just pulled in here (single-sourced) for convenience. Workshops require a healthy amount of hands-on activities to be engaging. If you have feedback about how to improve the activities, or places where you keep getting stuck, let me know.

Note that not all activities in this course are consolidated here (since participants can only do so much during a workshop). Only workshop activities are denoted with the icon.

Part I: Intro to API documentation

Activity: Identify your goals with API documentation

Ramping up on API documentation, developing a portfolio of API documentation writing samples, and completing all the activities in this course will require a lot of time and effort. Identify your goals here and make sure they align with this course.

Answer the following questions:

  • Why are you taking this course?
  • What are your career ambitions related to API documentation?
  • Are you in a place where developer documentation jobs are plentiful?
  • What would you consider to be a success metric for this course?
  • Do you have the technical mindset needed to excel in developer documentation fields?

For live workshops, we typically share responses in a get-to-know-everyone format. But if you’re taking this course online, consider jotting down some thoughts in a journal or blog entry.

For more information related to this activity, see Documenting APIs: A guide for technical writers.

Part II: Using an API like a developer

Activity: Get familiar with the OpenWeatherMap API

Let’s explore the basic sections in the OpenWeatherMap API:

  1. Go to https://openweathermap.org
  2. Click API in the top navigation bar.
  3. In the Current weather data section, click the API Doc button.

    Get a sense of the information this Current Weather Data API provides. The API calls provide developers with ways to pull information into their applications. In other words, the APIs will provide the data plumbing for the applications that developers build.

  4. Answer the following questions about the Current weather data API endpoint:

    • Does the API provide the information we need about temperature, wind speed, wind direction, and current conditions? (Hint: Look at one of the sample API responses by clicking the Example link.)
    • How many different ways can you specify the location for the weather information?
    • What does a sample request look like?
    • How many endpoints does the API have?
    • What authorization credentials are required to get a response?

For more information related to this activity, see Scenario for using a weather API.

Activity: Get an OpenWeatherMap API key

To get an API key for the OpenWeatherMap API:

  1. Go to https://openweathermap.org/.
  2. Click Sign Up in the top navigation bar and create an account.
  3. After you sign up, return to the OpenWeatherMap homepage and click Sign in.
  4. After signing in, you’ll see the developer dashboard. Click the API Keys tab.
  5. Copy the key into a place you can easily find it.

For more information related to this activity, see Get authorization keys.

Activity: Make requests with Postman

Make a request

In this exercise, you’ll use Postman to make a request using OpenWeatherMap’s current weather data API endpoint. To make the request:

  1. If you haven’t already done so, download and install the Postman app at http://www.getpostman.com.
  2. Start the Postman app.
  3. If necessary, select GET for the method. (This is the default.)
  4. Insert the following endpoint into the box next to GET: https://api.openweathermap.org/data/2.5/weather.
  5. Click the Params tab (below the box where you inserted the endpoint) and then add the following three parameters in the key and value rows:

    • key: zip / value: 95050
    • key: units / value: imperial
    • key: appid/ value: APIKEY

    Customize the zip and appid values to your own zip code and API key.

    Your Postman UI should look like this:

    When you add these parameters, they will dynamically be added as a query string to the endpoint URL in the GET box. For example, your endpoint will now look like this: https://api.openweathermap.org/data/2.5/weather?zip=95050&units=imperial&appid=fd4698c940c6d1da602a70ac34f0b147 (but with different query string values). Query string parameters appear after the question mark ? symbol and are separated ampersands &. The order of query string parameters doesn’t matter.

    Many APIs pass the API key in the header rather than as a query string parameter in the request URL. (If that were the case, you would click the Headers tab and insert the required key-value pairs in the header.)

  6. Click Send.

    The response appears in the lower pane. For example:

Save the request

  1. In Postman, click the Save button (next to Send).
  2. In the Save Request dialog box, in the Request Name box at the top, type a friendly name for the request, such as “OpenWeatherMap Current API.”
  3. In the Request description (Optional) field, type a description such as “gets the current weather for 95050 in imperial units.”
  4. Scroll down a bit and click Create collection to create a folder to save the request in (e.g., “OpenWeatherMap”). Then select the new collection you just created.

    After you create the collection, the Save button will be enabled. Your Postman collection should look something like this:

  5. Click Save to [collection name]

Saved endpoints appear in the left side pane under Collections. (If you don’t see the Collections pane, click the Show/Hide Sidebar button in the lower-left corner to expand it.

Make a request for the OpenWeatherMap 5 day forecast

Now instead of getting the current weather, let’s use another OpenWeatherMap endpoint to get the forecast. Enter details into Postman for the 5 day forecast request. In Postman, you can click a new tab, or click the arrow next to Save and choose Save As. Then choose your collection and request name.

A sample endpoint for the 5 day forecast, which specifies location by zip code, looks like this:

https://api.openweathermap.org/data/2.5/forecast?zip=95050,us

Add in the query parameters for the API key and units:

https://api.openweathermap.org/data/2.5/forecast?zip=95050&appid=APIKEY&units=imperial

(In the above code, replace out APIKEY with your own API key.)

Make one more OpenWeatherMap API request

Make one more OpenWeatherMap API request, this time changing the parameters you’re using to specify the location (for either endpoint). For example, if you specified the location by zip code, change it to lat and lon geocoordinates instead. For example:

https://api.openweathermap.org/data/2.5/weather?lat=37.3565982&lon=-121.9689848&units=imperial&appid=fd4698c940c6d1da602a70ac34f0b147

For more information related to this activity, see Submit requests through Postman.

Activity: Make the OpenWeatherAPI request using curl

  1. Assuming you completed the exercises in the Postman tutorial, go back into Postman.
  2. On any call you’ve configured, below the Save button in Postman, click the Code link.
  3. In the Generate Code Snippets dialog box, select cURL from the drop-down list, and then click Copy to Clipboard.

    (The official name is “cURL” but most people just write it as “curl.”)

    The Postman code for the OpenWeatherMap weather request looks like this in curl format:

    curl -X GET \
      'https://api.openweathermap.org/data/2.5/weather?lat=37.3565982&lon=-121.9689848&units=imperial&appid=fd4698c940c6d1da602a70ac34f0b147' \
      -H 'Postman-Token: dcf3c17f-ef3f-4711-85e1-c2d928e1ea1a' \
      -H 'cache-control: no-cache'
    

    Postman adds some of its own header information (designated with -H). You can optionally remove these extra header tags (including them won’t hurt anything). You can also remove the backslashes (\), which are just added for readability. Additionally, note that on Windows you must change single quotes to double quotes, since double quotes are not supported in the default Windows termial. Here’s the curl call with the -H and backslashes removed, and single quotes converted to double quotes:

    curl -X GET "https://api.openweathermap.org/data/2.5/weather?lat=37.3565982&lon=-121.9689848&units=imperial&appid=fd4698c940c6d1da602a70ac34f0b147"
    
  4. Curl is available on Mac by default. If you’re on Windows and you haven’t installed curl, follow the instructions for installing curl here. (Note: Choose one of the “free” versions, such as “With Administrator Privileges (free)”).

  5. Go to your terminal:

    • If you’re on Windows, go to Start and type cmd to open up the command line. (If you’re on Windows 8, see these instructions for accessing the commandline.) Right-click and then select Paste to insert the call.

    • If you’re on a Mac, either open iTerm or Terminal (by pressing Cmd + space bar and typing Terminal). Paste the request you have in your text editor into the command line and then press the Enter key.

    The response from the OpenWeatherMap weather request should look as follows:

    {"coord":{"lon":-121.96,"lat":37.35},"weather":[{"id":801,"main":"Clouds","description":"few clouds","icon":"02d"}],"base":"stations","main":{"temp":65.59,"pressure":1014,"humidity":46,"temp_min":60.8,"temp_max":69.8},"visibility":16093,"wind":{"speed":4.7,"deg":270},"clouds":{"all":20},"dt":1522608960,"sys":{"type":1,"id":479,"message":0.1642,"country":"US","sunrise":1522590719,"sunset":1522636280},"id":420006397,"name":"Santa Clara","cod":200}
    

    This response is minified. You can un-minify it by going to a site such as JSON pretty print, or on a Mac (with Python installed) you can add | python -m json.tool at the end of your cURL request to minify the JSON in the response. See this Stack Overflow thread for details.

  6. Now make a similar curl request for the 5 day forecast request that you also have in Postman. And another curl request for the third OpenWeatherMap API request you made in Postman.

For more information related to this activity, see Make a curl call.

Activity: Make the request on a page with AJAX

For this activity, you’ll use JavaScript to display the API response on a web page. You’ll use some auto-generated jQuery code from Postman to create the AJAX request.

  1. In a text editor (such as Sublime Text), create a new HTML file and paste in the following boilerplate template (which contains basic HTML tags and a reference to jQuery):

    <html>
    <meta charset="UTF-8">
      <head>
          <title>Sample page</title>
          <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
      </head>
    <body>
      <h1>Sample page</h2>
    
    </body>
    </html>
    
  2. Save your file (anywhere convenient) with a name such as weather.html.

  3. Open Postman and go to the Current weather data (weather) endpoint that you configured in an earlier activity (see Submit requests through Postman.
  4. Click the Code link (below the Save button), and then select JavaScript > jQuery AJAX.

    JavaScript Ajax code snippet

    The AJAX code should look as follows:

    var settings = {
      "async": true,
      "crossDomain": true,
      "url": "https://api.openweathermap.org/data/2.5/weather?zip=95050&appid=fd4698c940c6d1da602a70ac34f0b147&units=imperial",
      "method": "GET",
      "headers": {
        "cache-control": "no-cache",
        "postman-token": "e9be9756-b922-89b3-7109-66bc4cf06b17"
      }
    }
    
    $.ajax(settings).done(function (response) {
      console.log(response);
    });
    
  5. Click Copy to Clipboard to copy the code sample.
  6. In the same template you started building in step 1, add a pair of <script></script> tags below the jQuery reference, and then insert the Postman code inside your script tags.
  7. In the jQuery code, remove the headers object that Postman inserts:

    "headers": {
      "cache-control": "no-cache",
      "postman-token": "e9be9756-b922-89b3-7109-66bc4cf06b17"
    }
    
  8. Also remove the comma after "method": "GET".

    Your final code should look like this:

    <!DOCTYPE html>
    <html>
       <meta charset="UTF-8">
       <head>
          <meta charset="UTF-8">
          <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
          <title>Sample Page</title>
          <script>
             var settings = {
               "async": true,
               "crossDomain": true,
               "url": "https://api.openweathermap.org/data/2.5/weather?zip=95050&appid=fd4698c940c6d1da602a70ac34f0b147&units=imperial",
               "method": "GET"
             }
    
             $.ajax(settings).done(function (response) {
               console.log(response);
             });
          </script>
       </head>
       <body>
          <h1>Sample Page</h1>
       </body>
    </html>
    

    You can view the file here: idratherbewriting.com/learnapidoc/assets/files/weather-plain.html

  9. Start Chrome and open the JavaScript Console by going to View > Developer > JavaScript Console.
  10. In Chrome, go to File > Open File and select the weather.html file. (If you don’t see the File menu in Chrome, press Cmd + O or Ctrl + O, or just drag your weather.html file into your browser window.)

    The page body will be blank, but the weather response should be logged to the JavaScript Console (due to the console.log(response) code in the request). If you expand the object returned to the console, it will look as follows:

    JSON payload from weather API logged to console

    This information is now available for you to integrate into your page.

For more information related to this activity, see Inspect the JSON from the response payload and Access and print a specific JSON value.

Part III: Documenting API endpoints

Activity: Find an open-source project with API doc needs

To find an open-source project with API doc needs:

  1. Go to the GitHub Advanced Search.
  2. Under the Issues Options section, in the With the labels row, type help wanted. This is a common tag teams use to attract volunteers to their project (but some teams that need help might not use it).

    Scroll to the top and notice that label: "help wanted" automatically populates in the field.

  3. In this Advanced Search box at the top, add some additional keywords (such as documentation and api) as well:

  4. Click Search and browse the results.

    In the results, you might want to look for a REST API project (rather than a native-library API such as a Java API). Are there any projects that look interesting or promising? If so, great. If not, adjust some of the keywords and keep looking.

  5. If searching GitHub doesn’t yield any appropriate projects, try the following resources:

  6. After selecting a project, make notes on the following:

    • Does the project involve a REST API?
    • How does the project tag documentation-related issues? For example, does it use the “documentation” label?
    • Identify the current state of the project’s documentation. Are the docs robust, skimpy, nonexistent, extensive?
    • How active is the project? (What is the frequency of commits?)
    • How many contributors does the project have?

    You don’t have to actually reach out or interact with the team yet. You’re just gathering information and analyzing documentation needs here.

For more information related to this activity, see Find an Open Source Project.

Activity: Evaluate API reference docs for core elements

In this activity, you’ll review API reference documentation and identify the common elements. To evaluate the API reference docs:

  1. From this list of about 100 API doc sites here, identify three API documentation sites.
  2. In each of the doc sites, look for the API reference documentation section (the list of endpoints).
  3. In the reference documentation, identify each of the following sections:

    (The section names may differ in the API doc sites you find, but they’re usually recognizable.)

  4. Assess the API reference documentation by answering the following questions for each section:

    Resource description:

    • Is the description action-oriented?
    • Is it a brief 1-3 sentence summary?

    Endpoints and methods:

    • How are the endpoints grouped? (Are they listed all on the same page, or on different pages? Are they grouped by method, or by resource?)
    • How are the methods specified for each endpoint?

    Parameters:

    • How many types of parameters are there (header, path, query string, and request body parameters) for the endpoints?
    • Are the data types (string, boolean, etc.) defined for each parameter? Are max/min values noted?

    Request example:

    • In what format or language is the request shown (e.g. curl, specific languages, other)?
    • How many parameters does the sample request include?

    Response example:

    • Is there both a sample response and a response schema? (And is each element in the response actually described?)
    • How does the doc site handle nested hierarchies in the response definitions?

For more information related to this activity, see Evaluate API reference docs for core elements.

Part IV: OpenAPI and Swagger

Activity: Explore Swagger UI through the Petstore Demo

Let’s get some hands-on experience with Swagger UI using the Petstore demo.

  1. Go to the Swagger Pet Store Demo.

    As with most Swagger-based outputs, Swagger UI provides a “Try it out” button. To make it work, first you would normally authorize Swagger by clicking Authorize and completing the right information required in the Authorization modal. If you want, in the Authorization modal, type any number in the api_key field and click Authorize. However, the Petstore authorization modal is just for demo purposes. There isn’t any real code authorizing those requests, so you can simply close the Authorization modal.

    Authorization modal in Swagger UI
    Authorization modal in Swagger UI
  2. Expand the Pet endpoint.
  3. Click Try it out. After you click Try it out, the example value in the Request Body field becomes editable.

    Try it out button in Swagger UI
    Try it out button in Swagger UI
  4. In the Example Value, change the first id value to a unique (and unlikely repeated) whole number. Change the second name value to something you’d recognize (your pet’s name — e.g., Bentley).
  5. Click Execute.

    Executing a sample Petstore request
    Executing a sample Petstore request

    Swagger UI submits the request and shows the curl that was submitted. For example, here’s the curl Swagger UI sent:

    curl -X POST "https://petstore.swagger.io/v2/pet" -H "accept: application/xml" -H "Content-Type: application/json" -d "{ \"id\": 1000, \"category\": { \"id\": 0, \"name\": \"string\" }, \"name\": \"Bentley\", \"photoUrls\": [ \"string\" ], \"tags\": [ { \"id\": 0, \"name\": \"string\" } ], \"status\": \"available\"}"
    

    Notice that, with the -d (data) parameter, the request body parameter is escaped and added directly into the curl command rather than being loaded from a file (as explained in Common curl commands related to REST).

    The Responses section in Swagger UI shows the response from the server. By default, the response returns XML:

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
      <Pet>
        <category>
          <id>0</id>
          <name>string</name>
        </category>
        <id>1000</id>
        <name>Bentley</name>
        <photoUrls>
          <photoUrl>string</photoUrl>
        </photoUrls>
        <status>available</status>
        <tags>
          <tag>
            <id>0</id>
            <name>string</name>
          </tag>
        </tags>
      </Pet>
    

    If you select JSON rather than XML in the “Response content type” drop-down box, you can specify that JSON is returned rather than XML.

    Response from Swagger Petstore get pet request

  6. The Petstore is a functioning API, and you have actually created a pet. For fun, expand the GET /pet/{petId} endpoint, click Try it out, enter the pet id you used in the previous operation, and then execute the request. You should see your pet’s name returned.

For more information related to this activity, see Introduction to the OpenAPI specification and Swagger.

Activity: Edit an existing OpenAPI specification document

Use this simple Sunrise and sunset times API to get more familiar with the process of creating an OpenAPI specification file. This Sunrise and sunset times API doesn’t require authentication with requests, so it removes some of the more complicated authentication workflows (you can skip the security object). In this activity, you’ll simply edit some of the existing values in an OpenAPI specification document that’s already written.

To edit the OpenAPI specification file:

  1. Copy the code from this pre-built OpenAPI specification.
  2. Paste the YAML content into the Swagger Editor.
  3. Identify each of the root-level objects of the OpenAPI spec:
  4. In the info object (near the top), make some changes to the description property and see how the visual display in the right column gets updated.
  5. In the parameters object, make some changes to one of the description properties and see how the visual editor gets updated.
  6. Look for the $ref pointer in the response object. Identify what it points to in components.
  7. Change some spacing in a way that makes the spec invalid (such as inserting a space before info), and look at the error that appears. Then revert the invalid space.
  8. Expand the Get section and click Try it out. Then click Execute and look at the response.

For more information related to this activity, see Create an OpenAPI specification document.

Activity: Create a Swagger UI display with an OpenAPI spec document

In this activity, you’ll create a Swagger UI display for an OpenAPI specification document. If you’re using one of the pre-built OpenAPI files, you can see a demo of what we’ll build here: OpenWeatherMap Swagger UI or Sunrise/sunset Swagger UI.

Demo of Swagger UI
Demo of Swagger UI rendering an OpenWeatherMap OpenAPI specification document

To integrate your OpenAPI spec into Swagger UI:

  1. Prepare a valid OpenAPI specification document:
  2. Make sure your OpenAPI specification is valid. Paste your OpenAPI specification code into the Swagger online editor and make sure no warnings appear. The view on the right of the Swagger Editor shows a fully functional Swagger UI display.

  3. Go to the Swagger UI GitHub project.
  4. Click Clone or download, and then click Download ZIP. Download the files to a convenient location on your computer and extract the files.

    The only folder you’ll be working with in the downloaded zip is the dist folder (short for distribution). Everything else is used only if you’re recompiling the Swagger files, which is beyond the scope of this tutorial.

  5. Drag the dist folder out of the swagger-ui-master folder so that it stands alone. (Then optionally delete the swagger-ui-master folder and zip file.)
  6. Drag your OpenAPI specification file that you prepared earlier (in step 1) into the the dist folder. If you’re using the pre-build OpenAPI files, it’s either openapi_openweathermap.yml or openapi_sunrise_sunset.yml.) Your file structure should look as follows:

    ├── dist
    │   ├── favicon-16x16.png
    │   ├── favicon-32x32.png
    │   ├── index.html
    │   ├── oauth2-redirect.html
    │   ├── swagger-ui-bundle.js
    │   ├── swagger-ui-bundle.js.map
    │   ├── swagger-ui-standalone-preset.js
    │   ├── swagger-ui-standalone-preset.js.map
    │   ├── swagger-ui.css
    │   ├── swagger-ui.css.map
    │   ├── swagger-ui.js
    │   ├── swagger-ui.js.map
    │   ├── swagger30.yml
    │   └── [your openapi specification file]
    
  7. Inside your dist folder, open index.html in a text editor such as Atom editor or Sublime Text.
  8. Look for the following code:

    url: "http://petstore.swagger.io/v2/swagger.json",
    
  9. Change the url value from http://petstore.swagger.io/v2/swagger.json to a relative path to your YAML file, and then save the file. For example

    url: "openapi_openweathermap.yml",
    

    or

    url: "openapi_sunrise_sunset.yml",
    
  10. View the index.html file locally in your browser. Note that Chrome’s security restrictions (CORS objections) prevent you from viewing the Swagger UI file locally. You have several workarounds:

When you’re ready to publish your Swagger UI file, you simply upload the folder to a web server and go to the index.html file. For example, if you called your directory dist (leaving it unchanged), you would go to http://myserver.com/dist. (You can change the “dist” folder name to whatever you want.)

For more instructions in working with Swagger UI, see the Swagger.io docs.

For more information related to this activity, see Swagger UI tutorial.

Activity: Download and populate Stoplight with an OpenAPI specification

In this activity, you’ll work with an OpenAPI file in Stoplight, which provides a GUI editor for working with the OpenAPI specification information. To speed things up, you’ll start with a pre-built OpenAPI file that you paste into the Stoplight editor, and then you’ll make some modifications to it using Stoplight’s visual modeling tools. You can use Stoplight in the browser or as a web app. For simplicity, we’ll use the browser version.

To work with an OpenAPI file in Stoplight:

  1. Stoplight only supports OpenAPI 2.0, not 3.0. You could convert your 3.0 spec using APIMATIC Transformer to 2.0, but to speed things up, download this 2.0 OpenAPI JSON file already converted.
  2. Go to next.stoplight.io/.
  3. Click Login in the upper-right corner and log in using your GitHub account.
  4. Click New Personal Project.
  5. Type a Project name (e.g., “OpenWeatherMap API”), choose whether you want the visibility public or private (it doesn’t matter), and click Next.
  6. On the next screen (Project Designer), select the Import Existing tab. Then the click Upload OpenAPI (Swagger), Markdown or HTML File button and select the openweathermap_swagger20.json file that you downloaded in step 1.
  7. Click the +openweathermap_swagger20.oas2.yml button. The OpenAPI file gets uploaded into Stoplight and the data populates the Stoplight interface.
  8. At the top of the screen, switch between the Code and Design views by clicking the corresponding buttons at the top. Make some edits in the code and then switch to the Design view to see the edits reflected. (Note that Stoplight prefers JSON as the code format.) The following video shows this process:

    When you switch to the code view, the editor automatically goes to the part of the spec you were creating in the visual editor and highlights it. When you switch back, the visual UI updates with any changes you made in the code. Switching between modes is seamless and easy.
  9. Explore the different options in the Design editor (specifically, expand Paths and click /weather > Call current weather data for…) and make some arbitrary textual changes to see how to update information.

Automatically generate schema documentation

One of the coolest features in Stoplight is the ability to auto-generate the schema documentation from a sample JSON response. Try out this auto-generation feature by doing the following:

  1. In the middle column of Stoplight, click PATHS, and then click /weather, and then click Call current weather data for ….
  2. In the Responses section, click Raw Schema and delete the existing response schema. (Even when you delete the info here, it will leave {} there when you switch tabs, which is good.)
  3. Switch to the Editor tab, click Generate from JSON, and paste in the following JSON response from the OpenWeatherMap weather endpoint:

    {
      "coord": {
        "lon": -121.96,
        "lat": 37.35
      },
      "weather": [
        {
          "id": 801,
          "main": "Clouds",
          "description": "few clouds",
          "icon": "02d"
        }
      ],
      "base": "stations",
      "main": {
        "temp": 75.51,
        "pressure": 1014,
        "humidity": 8,
        "temp_min": 66.92,
        "temp_max": 80.6
      },
      "visibility": 16093,
      "wind": {
        "speed": 11.41,
        "deg": 330
      },
      "clouds": {
        "all": 20
      },
      "dt": 1541544960,
      "sys": {
        "type": 1,
        "id": 479,
        "message": 0.0043,
        "country": "US",
        "sunrise": 1541515128,
        "sunset": 1541552625
      },
      "id": 420006397,
      "name": "Santa Clara",
      "cod": 200
    }
    
  4. Click Generate!

    Stoplight automatically generates the JSON schema that conforms to the OpenAPI spec. You just saved yourself an afternoon of work!

    Autogenerated JSON schema
    Stoplight will autogenerate the JSON schema documentation

    Here’s a short video showing the process of auto-generating JSON. The Stoplight editor has evolved a bit, but it’s still highly similar. (Also note that instead of starting with the above sample JSON, the video makes request in Postman and then copies the response from there — but the idea should be clear.)

    Stoplight's visual modeling tools let you automatically create the correct JSON schema definition from a block of JSON that you paste in.
  5. Click the Raw Schema tab to see the code that Stoplight automatically wrote for you based on the sample JSON you copied in.

    This auto-generated schema documentation will make your life easier. Even if you prefer to hand-code your OpenAPI specification files in your own editor, you might find that you visit Stoplight just to auto-generate your response schema documentation.

For more information related to this activity, see Stoplight — visual modeling tools for creating your OpenAPI spec.

Part VI: Non-reference content in API docs

Activity: Assess the non-reference content in 3 API doc sites

  1. Go to the list of 100 API doc sites and identify 3 API doc sites to analyze. The API doc sets could be API documentation sites from your favorite tools or companies, or just API sites you select at random.
  2. Look through the documentation and identify whether the API documentation site contains each of the following:

    Non-reference topic API doc site 1 API doc site 1 API doc site 1
    API overview
    Getting started
    Authentication and authorization
    Status and error codes
    Rate limiting and thresholds
    Code samples and tutorials
    SDKs and sample apps
    Quick reference guides
    Glossary
    API best practices

    Recreate this table in your favorite word processing application and populate the columns with Xs if they contain the topic.

  3. Do you have any noteworthy observations from your analysis?

For more information related to this activity, see Activity: Identify non-reference content.

Part VII: Publishing API documentation

Activity: Look for common patterns in API doc sites

In this activity, identify common patterns in API documentation sites.

  1. Go the list of 100+ API documentation sites.
  2. Select about 5 different APIs (choose any of those listed on the page).
  3. Look for several patterns or commonalities among the API doc sites. For example, you might look for any of the following patterns:

    • Structure and templates
    • Seamless branding (between docs and the marketing site)
    • Abundant code samples and syntax highlighting
    • Lengthy pages
    • API Interactivity (such as an API Explorer)
    • Docs as code tooling
  4. Note any non-patterns, such as the following:

    • PDF
    • Translation
    • Video tutorials
    • Commenting features
    • Multiple outputs by role
  5. Make some notes in an API log or journal (or share them in the comments below).

In the next section, we’ll look at Design patterns with API doc sites. From your notes, look to see if the patterns I highlight match the ones you observed in the API doc sites you analyzed.

For more information related to this activity, see Survey of API doc sites.

Activity: Get practice with Markdown

To get a sense of how Markdown works, let’s practice a bit with Markdown.

  1. Go to an online Markdown editor (such as Dillinger.io).
  2. Create the following:

    • Numbered list
    • Bulleted list
    • Word with bold formatting
    • Code sample
    • Level 2 heading
    • code formatted text
  3. If desired, copy over the Markdown content from this surfreportendpoint.md file and look at the various Markdown tags.

For more information related to this activity, see More about Markdown.

Activity: Create a GitHub wiki and publish content on a sample page

In this section, you will create a new GitHub repo and publish a sample file there.

  1. Create a GitHub account at GitHub.com.
  2. Go to GitHub and sign in. After you’re signed in, click the + button in the upper-right corner and select New repository.

    Creating a new GitHub repository
    Creating a new GitHub repository
  3. Give the repo a Repository name, a short Description, select Public, select Initialize the repo with a README, and then click Create repository. (Don’t worry about selecting the license or gitignore settings for this activity.)
  4. Click the Wiki tab on the top navigation bar of your new repository.
  5. Click Create the first page. (Or if your wiki already has pages, click New Page.)
  6. In the default page (“Home”), insert your own sample documentation content, preferably using Markdown syntax. Or grab the sample Markdown page of a fake endpoint called surfreport here and insert it into the page.
  7. In the Edit message box, type a description of what you updated (your commit message).
  8. Click Save Page.

Notice how GitHub automatically converts the Markdown syntax into HTML and styles it in a readable way. You could work with this GitHub wiki entirely in the browser as a way for multiple people to collaborate and edit content. However, unlike other wikis, with GitHub you can also take all the content offline and edit locally, and then commit your changes and push the changes back online.

For more information related to this activity, see Manage content in a GitHub wiki.

Activity: Clone your GitHub repo locally

So far you’ve been working with GitHub in the browser. Now we’ll take the same content and work with it locally. This is what makes the GitHub wiki unique from other wikis — it’s a Git repo.

  1. If you don’t already have Git installed, set it up on your computer. (You can check by typing git --version in your terminal window. See Install Git for more information on installation.)
  2. While viewing your the GitHub wiki in your browser, look for the section that says Clone this wiki locally. Click the clipboard button. (This copies the clone URL to your clipboard.)

    Clone this wiki locally
    Clone this wiki locally

    The wiki is a separate clone URL than the project’s repository. Make sure you’re viewing your wiki and not your project. The clone URL will include .wiki.

    In contrast to the “Clone this wiki locally” section, the “Clone in Desktop” button launches the GitHub Desktop client and allows you to manage the repository and your modified files, commits, pushes, and pull through the GitHub Desktop client. There’s another tutorial for working with the Desktop client: Activity: Use the GitHub Desktop client.

  3. Open your terminal emulator:

    • If you’re a Windows user, open the Git BASH terminal emulator, which was installed when you installed Git.
    • If you’re a Mac user, go to Applications > Utilities > Terminal (or launch iTerm, if you installed it instead).
  4. In your terminal, either use the default directory or browse (cd) to a directory where you want to download your repository.
  5. Type the following, but replace the git URL with your own git URL that you copied earlier (it should be on your clipboard). The command should look something like this:

      git clone https://github.com/tomjoht/weatherapi.wiki.git
    

    When you clone a repo, Git will show something like the following:

    Cloning into 'weatherapi.wiki'...
    remote: Enumerating objects: 3, done.
    remote: Counting objects: 100% (3/3), done.
    remote: Compressing objects: 100% (2/2), done.
    remote: Total 9 (delta 0), reused 0 (delta 0), pack-reused 6
    Unpacking objects: 100% (9/9), done.
    

    The folder Git creates in the above example is weatherapi.wiki.

    Cloning the wiki gives you a copy of the content on your local machine. Git is distributed version control software, so everyone has his or her own copy. When you clone the repo, you create a copy on your local machine; the version in the cloud on GitHub is referred to as “origin.” Thus, you have two instances of the content.

    More than just copying the files, though, when you clone a repo, you initialize Git in the folder where you clone the repo. Initializing Git means Git will create an invisible Git folder in that directory, and Git can start tracking your edits to the files, providing version control. With Git initialized, you can run pull commands to get updates from the online repository (origin) pulled down to your local copy. You can also commit your changes and then push your changes back up to origin.

  6. Navigate to the directory where you cloned the repo (either using standard ways of browsing for files on your computer or via the terminal with cd) to see the files you downloaded. For example, type cd weatherapi.wiki and then ls to see the files.

    You don’t need to type the full directory name. Just start typing the first few letters and then press your Tab key to autocomplete the rest.

    You might also want to browse to this folder via Finder (Mac) or Explorer (Windows). If you can view invisible files on your machine (for instructions on making hidden files visible, see one of the following: Windows or Mac), you will also see a git folder.

For more information related to this activity, see Manage content in a GitHub wiki.

Activity: Push local changes to the remote

  1. In a text editor, open the Markdown file you downloaded in the GitHub repository. You can open the file directly from your terminal with the following command:

    open Home.md
    

    The file will be opened in the default application associated with that file type. You can also open the file by manually browsing to it and opening it normally.

  2. Make a small change to the content and save it. For example, type your name at the top of the document.
  3. In your terminal, make sure you’re in the directory where you downloaded the GitHub project.

    To look at the directories under your current path, type ls. Then use cd {directory name} to drill into the folder, or cd ../ to move up a level.

  4. Add all the files to your staging area:

      git add .
    

    Git doesn’t automatically track all files in the same folder where Git has been initialized. Git tracks modifications only for the files that have been “added” to Git. By typing git add . or git add --all, you’re telling Git to start tracking modifications to all files in this directory. You could also type a specific file name here instead, such as git add Home.md, to just add a specific file (rather than all files changed) to Git’s tracking.

    After you run the git add command, Git adds the files into what’s called the staging area. As a sports analogy, the staging area is like your on-deck circle. These files are ready to be committed when you run git commit.

  5. See the changes set in your staging area:

      git status
    

    Git responds with a message indicating which files are on-deck to be committed.

    Changes to be committed:
    (use "git reset HEAD <file>..." to unstage)
    
        modified:   Home.md
    

    The staging area lists all the files that have been added to Git that you have modified in some way. It’s a good practice to always type git status before committing files, because you might realize that by typing git add ., you might have accidentally added some files you didn’t intend to track (such as large binary files). If you want to remove this file from the staging area, you can type git reset HEAD Home.md to unstage it.

  6. Commit the changes:

      git commit -m "updated some content"
    

    When you commit the changes, you’re creating a snapshot of the files at a specific point in time for versioning.

    The git commit -m command is a shortcut for committing and typing a commit message in the same step. It’s much easier to commit updates this way.

    If you just type git commit, you’ll be prompted with another window to describe the change. On Windows, this new window will probably be a Notepad window. Describe the change on the top line, and then save and close the Windows file.

    On a Mac, a new window doesn’t open. Instead, the Vim editor mode opens up within the terminal. (“vi” stands for visual and “m” for mode, but it’s not a very visual editor.) I don’t recommend using Vim. If you get stuck in this mode and need to escape, press your Escape key. Then type q to quit. (See Vim commands here.) Normally, you want an external editor such as Sublime Text to open from your terminal. See Associating text editors with Git for details.

  7. Push the changes to your repository:

    git push
    

    If you didn’t set up automatic GitHub authentication, you will be prompted for your GitHub username and password. (Note that your username is your GitHub login ID, such as “jdoe,” not your friendly name, such as “John Doe.”)

    Note that when you type git push or git pull and don’t specify the branch, GitHub uses the default branch from origin. The default branch on GitHub is called master. Thus the command actually passed is git push origin master (it means this: push these changes to the remote origin repository, in the master branch). Some developers prefer to specify the repository and branch to ensure they are interacting with the right repositories and branches.

    Your terminal window probably looks something like this:

    Terminal window with git commands
    Terminal window with git commands
  8. Now verify that your changes took effect. Browse to your GitHub wiki repository and look to see the changes.

For more information related to this activity, see Manage content in a GitHub wiki.

VIII: Getting a job in API documentation

Activity: Look at API documentation jobs and requirements

In this activity, you’ll get a sense of the skills needed for the jobs in your location, and then draw up a plan.

  1. Go to indeed.com.
  2. In the Where field, type your desired location.
  3. Search for “API technical writer” or some combination of API + technical writer + developer documentation jobs.
  4. Read the descriptions of 5 jobs.
  5. Note a few of the salient requirements for these jobs.
  6. Assess where you’re currently at with the following:
    • Portfolio with writing samples that include developer documentation
    • Technical knowledge related to developer domain
    • Experience writing developer documentation
  7. Make a plan for how you’ll match up your portfolio, tech knowledge, and experience related to what these job descriptions are asking for. You might need to dedicate more time to the open-source documentation project that you identified earlier.

For more information related to this activity, see Locations for API doc writer jobs.

6% Complete

6/110 pages complete. Only 104 more pages to go...

Donate?

Want to buy me lunch? Click the Donate button below to donate $10 through Paypal.