Search results

Activity: What's wrong with this API reference topic

Last updated: Apr 05, 2019

Download PDF

In this activity, you’ll critique an existing API reference topic to identify what’s wrong with it.

Activity: What’s wrong with this API reference topic

The following is a sample API reference topic for an endpoint called surfreport. There are about 25 things wrong in the topic. A copy of this same content is available in a read-only Google Doc here. In Google Docs, go to File > Make a Copy to create your own instance. Then make comments in Google docs to note as many errors as you can find.

Make a copy of this Google doc and make comments on it.
Make a copy of this Google doc and make comments on it.

Here’s the same doc (with problems) displayed on the web:

Surfreport

Knowing whether the conditions are optimal for surfing is a necessary detail in every surfer’s life. This endpoint includes information about surfing conditions, including the surf height, water temperature, wind, and tide. Also provides an overall recommendation about whether to go surfing. As an added touch, recommendations are expressed in surfer lingo. Surf’s up!

Endpoints

GET/POST surfreport/{:beachId}

Gets the surf conditions for a specific beach ID.

Parameters

Parameter Use Description Type of data
{beachId} Required Refers to the ID for the beach you want to look up. Number
days Optional The number of days to include in the response. Default is 3. Max 10. Integer
time Optional The time you want the report for. Integer. ISO 8601 format. Example: 20180915T155300+0500

Sample request

https://api.openweathermap.org/data/2.5/surfreport/12345?zip=95050&appid=APIKEY&days=1

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

Sample response

{
    "surfreport": [
        {
            "beach": "Santa Cruz",
            "monday": {
                "1pm": {
                    "tide": 5,
                    "wind": 15,
                    "watertemp": 80,
                    "surf_height": 5,
	          "riptide":  "moderate",
                    "recommendation": "Carve it up, brah! The waves are crankin' wild out there."
                },
                "2pm": {
                    "tide": -1,
                    "wind": 1,
                    "watertemp": 50,
                    "surf_height": 3,
	         "riptide": extreme
                    "recommendation": "Waves are foam and frothy but rideable in places. Gravitate to the impact zone, due, and hang loose."
                },
                "3pm": {
                    "tide": -1,
                    "wind": 10,
                    "watertemp": 65,
                    "surf_height": 1,
                    "recommendation": "Scene is blown out. Bail inland and chill on the beach instead or you’ll the one who’ll be shredded, due."
                }
                ...
            }
        }
    ]
}

Response definitions

The following table describes each item in the response.

Response item Description Data type
beach The beach you selected based on the beach ID in the request. The beach name is the official name as described in the National Park Service Geodatabase. String
{day} The day(s) of the week requested. object
{time} The time for the conditions. string
tide The level of tide at the beach for a specific day and time. Tide is the distance inland that the water rises to, and can be a positive or negative number. When the tide is out, the number is negative. When the tide is in, the number is positive. The 0 point reflects the line when the tide is neither going in nor out but is in transition between the two states. String
wind The wind speed at the beach. Wind affects the surf height and general wave conditions. Wind speeds of more than 15 make surf conditions undesirable because the wind creates white caps and choppy waters. Int
watertemp The temperature of the water. Water temperatures below 70 usually require you to wear a wetsuit. With temperatures below 60, you will need at least a 3mm wetsuit and preferably booties to stay warm. String
surfheight The height of the waves, returned in either feet or centimeters depending on the units you specify. A surf height of 3 feet is the minimum size needed for surfing. If the surf height exceeds 10 feet, it is not safe to surf. Map
recommendation An overall recommendation based on a combination of the various factors (wind, watertemp, surfheight), etc. String

Answers

You can view the answer key here: What’s wrong with this topic answer key.

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.

35% Complete

35/165 pages complete. Only 130 more pages to go.