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

When I give API workshops, it helps to consolidate activities into a single page with brief instructions. The following are activities used in the live workshops in Denver. I include this resource here in case you’re using this content to provide your own workshop or classroom instruction.

Part I: Intro to API documentation

Slides: Intro to API documentation

Activity: Explore an API

Explore the basic sections in API reference documentation in these two weather APIs:

Generate your own API key for at least the OpenWeatherMap API.

Activity: Make a curl request

This is a curl request for the weather endpoint in the OpenWeatherMap API:

curl -I -X GET ""

Swap in your own API key for the appid value in the URL’s query string.

Activity: Postman client

  1. Download Postman.
  2. Populate Postman from the Run in Postman buttons below (or from the import links):

    OpenWeatherMap API collection

    If this button doesn’t work for you, copy this import link.

    Aeris Weather API collection

    If this button doesn’t work for you, copy this import link.

  3. Make requests in Postman.
  4. Generate code snippets in JavaScript (AJAX) from Postman.
  5. Create a Run in Postman button for your requests. In the Collections pane, click the < arrow to expand the pane and click Share.

Part II: OpenAPI and Swagger

Slides: OpenAPI and Swagger

Activity: OpenAPI with Stoplight

  1. Open v3 next Stoplight app. (You can also use the Desktop app.)
  2. From main.oas, open the Code tab and paste in content for this 2.0 JSON Open API definition: openweathermap_swagger20.json.
  3. Edit, explore Basics, Requests, Responses sections.
  4. In the Responses area, click Generate from JSON, paste in complex JSON snippet into the Responses area, then click Generate!

      "coord": {
        "lon": -121.96,
        "lat": 37.35
      "weather": [
          "id": 804,
          "main": "Clouds",
          "description": "overcast clouds",
          "icon": "04d"
      "base": "stations",
      "main": {
        "temp": 57.18,
        "pressure": 1020,
        "humidity": 47,
        "temp_min": 53.6,
        "temp_max": 59
      "visibility": 16093,
      "wind": {
        "speed": 3.29,
        "deg": 256.502
      "clouds": {
        "all": 90
      "dt": 1522947600,
      "sys": {
        "type": 1,
        "id": 479,
        "message": 0.0049,
        "country": "US",
        "sunrise": 1522935974,
        "sunset": 1522982091
      "id": 420006397,
      "name": "Santa Clara",
      "cod": 200

More details about Stoplight are available here:

Activity: Swagger Editor

  1. Paste this YAML file into Swagger Editor and make updates.
  2. Go to this SwaggerHub API. Observe Generate Client SDK options.

Activity: Swagger UI

  1. Download Swagger UI.
  2. Uncompress and pull out the dist folder.
  3. Save this file locally: openapi_openweathermap.yml into the dist folder.
  4. Reference openapi_openweathermap.yml in place of the default url value.
  5. Open in Firefox.

Part III: Non-reference content in API docs

Slides: Non-reference content in API docs

Activity: GitHub workflow

This workflow is key for working with sample apps and code repositories.

  1. Create new repo and initialize with readme. Clone repo locally using git clone.
  2. Make update to readme file and push back into repo:

    git add .
    git commit -m "made update to readme"
    git pull
    git push
108% Complete
You've completed the course!

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