Documenting an Endpoint

The following is a direct lift from Tom Johnson's A new endpoint to document permission pending

Here are some rough, unformatted notes on the endpoint such as you might find in a development area. The following shows how to take notes on an endpoint and develop them into a decent endpoint.

Note: opencamping.org is a fictitious API site.

Internal Wiki page: "Camping Report API"

The new endpoint is /campingreport/{campsiteId}. This endpoint is for campers who want to check things like rain chances and temperature to determine whether they should head out to a camping location. {campsiteId} is retrieved from a list of camping sites.

Optional parameters:

If you include the hour, then you only get back the campsite 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 temperature, rain chances, and overall recommendation.

Sample endpoint with parameters:

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

The campingreport response contains these elements:

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

Sample format:

The following is a sample response from the campingreport/{campsiteId} endpoint:
{                     
    "campingreport": [
        {
            "campsite": "Coldspring",
            "monday": {
                "temp_low": 328.15,
                "wind_velocity": 2,
                "wind_direction": 175,
                "temp_high": 348.15,
                "rain_chance": 15,
                "recommendation": "Go camping!"
            },
            "tuesday": {
                "temp_low": 338.15,
                "wind_velocity": 4,
                "wind_direction": 175,
                "temp_high": 358.15,
                "rain_chance": 25,
                "recommendation": "Camping conditions okay, not great."
            },
            "wednesday": {
                "temp_low": 341.15,
                "wind_velocity": 15,
                "wind_direction": 316,
                "temp_high": 351.15,
                "rain_chance": 85,
                "recommendation": "No camping today; find some other activity."
            },
        }
    ]
}

rain_chance will refer to rain chances for that day.

Although users can enter campsite names, the repoprt includes only certain campsite names. Users can look to see which campsites are available from our website at http://example.com/campingreport/campsites_available. The campsite names must be url encoded when passed in the endpoint as query strings.

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.

Information and programs provided by admin@mcmassociates.io.