A new endpoint to document

Until this point, you’ve been acting as a developer with the task of integrating the weather data into your site. The point was to help you understand the type of information developers need and how they use APIs.

Now let’s shift perspectives. Now suppose you’re a technical writer working with the Mashape weather API team. The team is asking you to document a new endpoint.

You have a new endpoint to document

The project manager calls you over and says the team has a new endpoint for you to document for the next release. (Sometimes teams will also refer to each individual endpoint as an “API” as well.)

“Here’s the wiki page that contains all the data,” the manager says. The information is scattered and random on the wiki page.

It’s now your task to sort through the information on this page and create documentation from it. You can read through the mock wiki page below to get a sense of the information. In the upcoming topics, I will create documentation from this information as I proceed through each of the needed sections for an API reference topic.

Sorting out information

Most technical writers don’t start from scratch with documentation projects. Engineers usually dump essential information onto an internal wiki page (or they communicate the info during meetings). However, the information on the wiki page will likely be incomplete, and unnecessarily technical in places (like describing the database schema or high-level architectural workflows). The info might also include internal-only information (for example, including test logins, access protocols, or code names), or have sections that are out-of-date.

Ultimately, the information will be oriented toward other engineers on the same knowledge level as the team’s engineers. Your job as a technical writer will be to take this information and turn it into complete, accurate, usable information that communicates with your audience.

Wiki page with information about the new endpoint

Here’s the mock internal wiki page:

The wiki page: "Surf Report API"

The new endpoint is /surfreport/{beachId}. This is for surfers who want to check things like tide and wave conditions to determine whether they should head out to the beach to surf. {beachId} is retrieved from a list of beaches on our site.

Optional parameters:

  • Number of days: Max is 7. Default is 3. Optional.
  • Units: imperial or metric. With imperial, you get feet and knots. With metric, you get centimeters and kilometers per hour. Optional.
  • Time: time of the day corresponding to time zone of the beach you're inquiring about. Format is unix time, aka epoch. This is the milliseconds since 1970. Time zone is GMT or UTC. Optional.

If you include the hour, then you only get back the surf condition for the hour you specified. Otherwise you get back 3 days, with conditions listed out by hour for each day.

The response will include the surf height, the wind, temp, the tide, and overall recommendation.

Sample endpoint with parameters:

https://simple-weather.p.mashape.com/surfreport/123?&days=2&units=metrics&hour=1400

The response contains these elements:

surfreport:

  • surfheight (units: feet)
  • wind (units: kts)
  • tide (units: feet)
  • water temperature (units: F degrees)
  • recommendation - string ("Go surfing!", "Surfing conditions okay, not great", "Not today -- try some other activity.")

The recommendation is based on an algorithm that takes optimal surfing conditions, scores them in a rubric, and includes one of three responses.

Sample format:

{
    "surfreport": [
        {
            "beach": "Santa Cruz",
            "monday": {
                "1pm": {
                    "tide": 5,
                    "wind": 15,
                    "watertemp": 60,
                    "surfheight": 5,
                    "recommendation": "Go surfing!"
                },
                "2pm": {
                    "tide": -1,
                    "wind": 1,
                    "watertemp": 50,
                    "surfheight": 3,
                    "recommendation": "Surfing conditions are okay, not great"
                }
                ...

            }
        }
    ]
}

Negative numbers in the tide represent incoming tide.

The report won't include any details about riptide conditions.

Although users can enter beach names, there are only certain beaches included in the report. Users can look to see which beaches are available from our website at http://example.com/surfreport/beaches_available. The beach names must be url encoded when passed in the endpoint as query strings.

To switch from feet to metrics, users can add a query string of &units=metrics. Default is &units=imperial.

Here's an example of how developers might integrate this information.

If the query is malformed, you get error code 400 and an indication of the error.

Next steps

Jump into the API reference tutorial overview for an overview of the 5 steps we’ll cover in creating the API reference topic for this new endpoint.

18% Complete

18/91 pages complete. Only 73 more pages to go...

Get new posts delivered straight to your inbox.

Subscriber count: 4,285