API Documentation Template

API Name
Base URL: https://api.example.com/v1/
Description: Provide a brief overview of the API’s purpose and functionality.

Authentication
Method: Explain the authentication mechanism used, e.g., API keys, OAuth2, etc.
 Header Example:
 {
 "Authorization": "Bearer YOUR_API_KEY"
 }
 Token Endpoint (if applicable): POST https://api.example.com/v1/auth/token
Request Body:
{
"client_id": "your_client_id",
"client_secret": "your_client_secret",
"grant_type": "client_credentials"
}

Endpoints
1. Endpoint Name
URL: GET /resource
Description: Briefly describe what this endpoint does.
Request Parameters:
Parameter Type Required Description
id string Yes Unique identifier for the resource.
limit number No Number of items to return.
Example Request:
curl -X GET "https://api.example.com/v1/resource?id=123&limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
Example Response:
{
"data": [
{
"id": "123",
"name": "Example Name",
"type": "Example Type"
}
],
"meta": {
"total": 100,
"limit": 10,
"offset": 0
}
}

2. Endpoint Name
URL: POST /resource
Description: Describe what this endpoint is for (e.g., creating a resource).
Request Body:
Field Type Required Description
name string Yes Name of the resource.
description string No A brief description of the resource.
Example Request:
curl -X POST "https://api.example.com/v1/resource" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "New Resource",
"description": "Detailed description"
}'
Example Response:
{
"id": "124",
"name": "New Resource",
"description": "Detailed description",
"created_at": "2025-01-02T12:00:00Z"
}

Error Codes
Code Message Description
400 Bad Request The request is invalid or missing parameters.
401 Unauthorized Authentication failed.
404 Not Found Resource not found.
500 Internal Server Error An unexpected error occurred on the server.

Rate Limits
Limit Value
Requests/Hour 1000
Requests/Day 50,000
Note: Use the X-RateLimit-Limit and X-RateLimit-Remaining headers to monitor usage.

Support
For issues or questions, contact support@example.com.
API Documentation Template

API Name
Base URL: https://api.weatherinfo.com/v1/
Description: This API provides real-time weather data, including current conditions,
forecasts, and historical weather trends.

Authentication
Method: The API uses API keys for authentication. Each request must include an Authorization
header with a valid API key.
 Header Example:
 {
 "Authorization": "Bearer abcd1234efgh5678"
 }
 Token Endpoint (if applicable): POST https://api.weatherinfo.com/v1/auth/token
Request Body:
{
"client_id": "weather_client_id",
"client_secret": "weather_client_secret",
"grant_type": "client_credentials"
}

Endpoints
1. Get Current Weather
URL: GET /weather/current
Description: Retrieves the current weather conditions for a specified location.
Request Parameters:
Parameter Type Required Description
location string Yes City name or latitude/longitude.
units string No Measurement units: metric or imperial. Defaults to metric.
Example Request:
curl -X GET "https://api.weatherinfo.com/v1/weather/current?location=Paris&units=metric" \
-H "Authorization: Bearer abcd1234efgh5678"
Example Response:
{
"location": "Paris",
"temperature": 18.5,
"humidity": 67,
"condition": "Cloudy"
}

2. Get Weather Forecast

URL: GET /weather/forecast
Description: Provides a 7-day weather forecast for a specified location.
Request Parameters:
Parameter Type Required Description
location string Yes City name or latitude/longitude.
Parameter Type Required Description
days number No Number of days to forecast (1-7). Defaults to 7.
Example Request:
curl -X GET "https://api.weatherinfo.com/v1/weather/forecast?location=London&days=5" \
-H "Authorization: Bearer abcd1234efgh5678"
Example Response:
{
"location": "London",
"forecast": [
{
"date": "2025-01-03",
"temperature": 8.3,
"condition": "Rain"
},
{
"date": "2025-01-04",
"temperature": 6.7,
"condition": "Cloudy"
}
]
}

Error Codes
Code Message Description
400 Bad Request The request is invalid or missing parameters.
401 Unauthorized Authentication failed or missing API key.
404 Not Found Requested resource or location not found.
500 Internal Server Error An unexpected error occurred on the server.

Rate Limits
Limit Value
Requests/Hour 1000
Requests/Day 50,000
Note: Use the X-RateLimit-Limit and X-RateLimit-Remaining headers to monitor usage.

Support
For issues or questions, contact support@weatherinfo.com.
Useful phrases, nouns, verbs, adverbs, and adjectives relevant to API documentation like the
one for a weather information API:
Phrases
1. "Base URL for accessing the API"
2. "Provide valid authentication credentials"
3. "Include the following in your request"
4. "Indicates the current weather conditions"
5. "Available in metric or imperial units"
6. "Response includes the following fields"
7. "Refer to the error codes table for details"
8. "Request failed due to missing parameters"
9. "Ensure proper API key usage"
10. "Daily rate limits exceeded"
Nouns
11. Endpoint
12. Authorization
13. Token
14. Parameter
15. Header
16. Forecast
17. Condition
18. Latitude/Longitude
19. Error
20. Limit
Verbs
21. Retrieve
22. Authenticate
23. Send
24. Include
25. Parse
Adverbs
26. Specifically
27. Accurately
28. Automatically
29. Rapidly
30. Clearly
Adjectives
31. Mandatory
32. Optional
33. Valid
34. Real-time
35. Predictive
API Documentation Template

API Name
Base URL: https://api.weatherinfo.com/v1/
Description: This API provides real-time weather data, including current conditions,
forecasts, and historical weather trends.

Authentication
Method: The API uses API keys for authentication. Each request must include an Authorization
header with a valid API key.
 Header Example:
 {
 "Authorization": "Bearer abcd1234efgh5678"
 }
 Token Endpoint (if applicable): POST https://api.weatherinfo.com/v1/auth/token
Request Body:
{
"client_id": "weather_client_id",
"client_secret": "weather_client_secret",
"grant_type": "client_credentials"
}

Endpoints
1. Get Current Weather
URL: GET /weather/current
Description: Retrieves the current weather conditions for a specified location.
Request Parameters:
Parameter Type Required Description
location string Yes City name or latitude/longitude.
units string No Measurement units: metric or imperial. Defaults to metric.
Example Request:
curl -X GET "https://api.weatherinfo.com/v1/weather/current?location=Paris&units=metric" \
-H "Authorization: Bearer abcd1234efgh5678"
Example Response:
{
"location": "Paris",
"temperature": 18.5,
"humidity": 67,
"condition": "Cloudy"
}
 Phrase: "Indicates the current weather conditions."
 Noun: Temperature
 Verb: Retrieve
 Adverb: Specifically
 Adjective: Real-time

2. Get Weather Forecast

URL: GET /weather/forecast
Description: Provides a 7-day weather forecast for a specified location.
Request Parameters:
Parameter Type Required Description
location string Yes City name or latitude/longitude.
days number No Number of days to forecast (1-7). Defaults to 7.
Example Request:
curl -X GET "https://api.weatherinfo.com/v1/weather/forecast?location=London&days=5" \
-H "Authorization: Bearer abcd1234efgh5678"
Example Response:
{
"location": "London",
"forecast": [
{
"date": "2025-01-03",
"temperature": 8.3,
"condition": "Rain"
},
{
"date": "2025-01-04",
"temperature": 6.7,
"condition": "Cloudy"
}
]
}
 Phrase: "Response includes the following fields."
 Noun: Forecast
 Verb: Parse
 Adverb: Accurately
 Adjective: Predictive

Error Codes
Code Message Description
400 Bad Request The request is invalid or missing parameters.
401 Unauthorized Authentication failed or missing API key.
404 Not Found Requested resource or location not found.
500 Internal Server Error An unexpected error occurred on the server.
 Phrase: "Refer to the error codes table for details."
 Noun: Error
 Verb: Authenticate
 Adverb: Automatically
 Adjective: Mandatory

Rate Limits
Limit Value
Requests/Hour 1000
Requests/Day 50,000
Note: Use the X-RateLimit-Limit and X-RateLimit-Remaining headers to monitor usage.
 Phrase: "Daily rate limits exceeded."
  Noun: Limit
 Verb: Include
 Adverb: Clearly
 Adjective: Valid

Support
For issues or questions, contact support@weatherinfo.com.
 Phrase: "Ensure proper API key usage."
 Noun: Authorization
 Verb: Send
 Adverb: Rapidly
 Adjective: Optional
Suggested Topic for Practicing API Documentation Language with Software
Engineering Students
Topic: Designing and Documenting a Weather Data API
Activity Outline:
1. Scenario Setup:
o Ask students to imagine they are part of a team creating an API for a weather
application.
o They need to design and write documentation for the following endpoints:
 Get Current Weather: Fetches weather details for a specified city or
coordinates.
 Get 5-Day Forecast: Provides weather forecasts for the next 5 days.
2. Learning Goals:
o Practice using technical vocabulary and sentence structures relevant to API
documentation.
o Understand how to write clear and concise descriptions of endpoints, parameters,
and responses.
o Use phrases like "response includes the following fields" and "ensure proper API key
usage."
o Incorporate nouns, verbs, adverbs, and adjectives effectively.
3. Tasks:
o Write the Authentication section for the API.
o Describe the endpoints (e.g., URL, Description, Request Parameters, Example
Response).
o Create an Error Codes table and explain typical errors users might encounter.
4. Example Interaction:
o Use the provided template as a guide.
o Students can explain their choices to the class, justifying why they used specific
verbs, nouns, or adjectives.
This activity helps students engage with both API structure and technical communication,
making it a great fit for upper intermediate computer science students. Would you like me
to prepare detailed instructions or materials for this activity?