1. apidoc
2. documenting APIs
3. Documenting API endpoints

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 OpenWeatherMap team. The team is asking you to document a new endpoint. What do you cover, and how do you approach it?

• You have a new endpoint to document
• Wiki page with information about the new endpoint
• Next steps

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 endpoint as an “API” as well.)

“Here’s the wiki page that contains info about the new API,” the manager says. The information is scattered and random on the wiki page.

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, test logins, access protocols, or code names) or have sections that are out-of-date.

Ultimately, the information will be oriented towards 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

It’s now your task to sort through the information on this mock wiki 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, we will proceed section by section through an API reference topic.

Here’s the mock internal wiki page:

https://api.openweathermap.org/com/surfreport/123?&days=2&units=metrics&hour=1400

{
    "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"
                }
                ...

            }
        }
    ]
}

You can see that the information here is unstructured and hard to scan. By structuring the API reference information into five standard sections, the information will take more shape and be more readable.

Next steps

Let’s jump into the API reference tutorial overview for an overview of the five steps we’ll cover in creating the API reference topic for this new endpoint.