New API endpoint to document
Shift perspectives: Now you're the technical writer
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 you're a technical writer working with the Mashape weather API team. The team is asking you to document a new endpoint.
For this exercise, you could equally document a new endpoint for the Aeris Weather API, but since that API is already quite robust, we'll keep it simple and work with the more minimalist Mashape weather API.
You have a new endpoint to document
The project manager calls you over and says they have a new API for you to document for the next release. (By "API," the manager really just means a new endpoint to the existing API. Some APIs like Alchemy API even refer to each endpoint as an API.)
"Here's the wiki page that contains all the data," the manager says. The information is scattered and random on the wiki page. In reality, you probably wouldn't have all the information available that you need, but to facilitate the course scenario (you can't ask the "team" questions about this fictitious new endpoint), the page will help.
It's now your task to sort through the information on this page and create documentation from it.
Read through the wiki page to get a sense of the information. The upcoming topics will guide you through creating documentation for this new endpoint.
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 (time: feet)
- wind (time: kts)
- tide (time: feet)
- water temperature (time: 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"
}
// ... the other hours of the day are truncated here.
}
}
]
}
Negative numbers in the tide represent incoming tide.
The report won't include any details about riptide conditions.
Note that 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.
Essential sections in REST API documentation
In the next topics, you'll work on sorting this information out into eight common sections in REST API documentation:
- Resource description
- Endpoint
- Methods
- Parameters
- Request submission example
- Request response example
- Status and error codes
- Code samples
Create the basic structure for the endpoint documentation
Open up a new text file and create sections for each of these elements.
Each of your endpoints should follow this same pattern and structure. A common template helps increase consistency and familiarity/predictability with how users consume the information.
Although there are automated ways to publish API docs, we're focusing on content rather than tools in this course. For the sake of simplicity, try just using a text editor and Markdown syntax.