API README Author
1. Overview
This process creates a complete README.md file for an API using only a textual description of that API. The generated README follows the sections most commonly found in software‑engineered API documentation and includes example code snippets in popular languages.
2. Business Value
A well‑written README is often the first point of contact for developers, partners, and internal stakeholders. By automatically producing a polished, consistent README from a plain‑text description, teams save time, reduce documentation gaps, and improve the onboarding experience for anyone consuming the API.
3. Operational Context
-
When to run – Whenever a new API is designed, an existing API is updated, or a project needs a fresh public‑facing documentation page.
-
Who uses it – Software Engineers, Tech Leads, and CTOs who need a ready‑to‑publish README for internal or external distribution.
-
How often – Typically once per API version release, or whenever the API description changes significantly.
4. Inputs
| Name/Label | Type | Details Provided |
|---|
| API Description Text | Free‑form text | A complete textual description of the API. The description should include the API name, purpose, base URL (if known), authentication method, list of endpoints with HTTP methods, request parameters, response formats, error handling, rate‑limit information, and any other relevant details. The text can be a copy‑paste of an OpenAPI spec, a design document, or a narrative summary. |
Only this single input is required. All other information needed for the README will be derived from it or from common knowledge about API documentation.
5. Outputs
| Name/Label | Contents | Formatting Rules |
|---|
| API README Document | A markdown‑formatted document (README.md) that contains: | |
| • Title and short description• Table of contents• Installation / setup instructions• Authentication guide• Detailed endpoint list (method, path, description, parameters, responses)• Example code snippets (cURL, Python, JavaScript)• Error handling information• Rate‑limit details• Contribution guidelines• License notice• Contact information | Use standard GitHub‑flavored markdown. Headings follow the hierarchy #, ##, ###, etc. Code blocks are fenced with triple backticks and language identifiers. Lists are bulleted or numbered as appropriate. No placeholder identifiers (e.g., “<API_KEY>”) remain; replace them with clear, descriptive placeholders such as YOUR_API_KEY. |
6. Detailed Plan & Execution Steps
-
Receive the API description text – Accept the free‑form description as the sole input.
-
Extract core metadata – Identify the API name, short tagline, base URL, and overall purpose.
-
Determine authentication method – Look for keywords such as “API key”, “OAuth 2.0”, “Bearer token”, or “Basic Auth”. If the method is not mentioned, note “Authentication details not provided – add manually.”
-
Parse endpoint information – For each endpoint, capture:
-
HTTP method (GET, POST, etc.)
-
Path (e.g., /users/{id})
-
Brief description of its purpose
-
Required and optional request parameters (name, type, location)
-
Expected response status codes and payload structure
-
Example request/response bodies if supplied.
-
Gather auxiliary details – Look for sections on error handling, rate limits, versioning, and contact/support information. If any are missing, add a note indicating the omission.
-
Research missing standards – When the description references a common standard (e.g., OAuth 2.0) but does not provide details, perform a brief web lookup to include a concise, accurate explanation of that standard.
-
Compose the README skeleton – Use a predefined markdown template that contains all standard sections. Insert the extracted metadata into the appropriate placeholders.
-
Generate example code – For each major endpoint, create three short examples:
-
A cURL command line call.
-
A Python snippet using the requests library.
-
A JavaScript snippet using fetch. Use generic placeholder values (YOUR_API_KEY, example_id, etc.) that the reader can replace.
-
Apply markdown style guidelines – Ensure consistent heading levels, line breaks, bullet formatting, and code‑block syntax.
-
Perform a completeness check – Verify that every required README section is present and that all extracted endpoints appear in the “API Endpoints” table.
-
Output the final markdown – Return the fully assembled README.md content as plain text.
7. Validation & Quality Checks
-
Section Presence – Confirm that the README includes each of the required sections listed in the output definition.
-
Endpoint Accuracy – Cross‑check every endpoint listed in the README against the source description for matching method, path, and parameters.
-
Code Snippet Syntax – Ensure that cURL commands start with curl, Python snippets import requests, and JavaScript snippets use fetch. No stray characters or missing backticks.
-
Placeholder Clarity – All placeholder values must be clearly marked (e.g., YOUR_API_KEY) and described in a “Replace with your own values” note.
-
Readability – Run a spell‑check and verify that sentences are concise and free of jargon not explained in the Glossary.
-
Error Handling – If any required piece of information (e.g., authentication method) is missing from the input, the process must add a highlighted “TODO” note in the relevant section instead of failing silently.
8. Special Rules / Edge Cases
| Situation | Handling |
|---|
| Missing authentication details | Insert a placeholder section titled “Authentication” with a brief note: “Authentication method not specified – please update this section with the appropriate details.” |
| No explicit base URL | Use https://api.example.com as a generic placeholder and annotate “Replace with actual base URL.” |
| Only a high‑level narrative, no endpoint list | Create a “TODO: Add endpoint details” block under the “API Endpoints” section and flag the output for manual review. |
| Multiple API versions described | Choose the most recent version (identified by a version number or date) and note the version used in the README title. |
| Unsupported language request | If the description asks for code examples in a language not covered by the template, provide only the three default languages and add a note encouraging the author to add additional examples. |
| Extremely long description | Summarize repetitive sections, keeping the README concise (ideally under 2,000 words). Include a “Full Specification” link if a separate document exists. |
If any validation check fails, the process should stop, return a clear error message indicating the missing or malformed element, and suggest corrective action.
9. Example
Input (API Description Text)
Task Manager API
Version: 1.2.0
Base URL: https://api.taskmanager.com/v1
Purpose: Provides CRUD operations for tasks and projects.
Authentication: API key passed as header `X-API-Key`.
Endpoints:
1. GET /tasks
- Description: Retrieve a list of all tasks.
- Query parameters:
* limit (integer, optional) – max number of tasks to return.
* offset (integer, optional) – pagination offset.
- Responses:
* 200 OK – JSON array of task objects.
* 401 Unauthorized – missing or invalid API key.
2. POST /tasks
- Description: Create a new task.
- Body (JSON):
* title (string, required)
* description (string, optional)
* dueDate (ISO‑8601 date, optional)
- Responses:
* 201 Created – JSON of the created task.
* 400 Bad Request – validation errors.
* 401 Unauthorized.
3. GET /tasks/{id}
- Description: Get details of a single task.
- Path parameter: id (UUID, required)
- Responses:
* 200 OK – JSON task object.
* 404 Not Found – task does not exist.
* 401 Unauthorized.
Error format: JSON object with fields `code` (integer) and `message` (string).
Rate limit: 100 requests per minute per API key.
Contact: support@taskmanager.com
License: MIT
Output (API README Document)
# Task Manager API
**Version:** 1.2.0
**Base URL:** `https://api.taskmanager.com/v1`
A simple RESTful API for managing tasks and projects. It supports creating, retrieving, updating, and deleting tasks.
---
## Table of Contents
- [Installation](#installation)
- [Authentication](#authentication)
- [API Endpoints](#api-endpoints)
- [Error Handling](#error-handling)
- [Rate Limiting](#rate-limiting)
- [Examples](#examples)
- [Contributing](#contributing)
- [License](#license)
- [Support](#support)
---
## Installation
No client library is required. You can call the API directly with HTTP tools such as `curl`, or from any programming language that can make HTTP requests.
---
## Authentication
All requests must include your API key in the `X-API-Key` header.
```http
X-API-Key: YOUR_API_KEY
Replace YOUR_API_KEY with the key provided to you by Task Manager.
API Endpoints
| Method | Path | Description |
|---|
| GET | /tasks | Retrieve a list of all tasks. |
| POST | /tasks | Create a new task. |
| GET | /tasks/{id} | Get details of a single task. |
GET /tasks
Query Parameters
| Parameter | Type | Required | Description |
|---|
limit | integer | optional | Max number of tasks to return. |
offset | integer | optional | Pagination offset. |
Responses
-
200 OK – JSON array of task objects.
-
401 Unauthorized – Missing or invalid API key.
Example (cURL)
curl -X GET "https://api.taskmanager.com/v1/tasks?limit=10&offset=0" \
-H "X-API-Key: YOUR_API_KEY"
Example (Python)
import requests
url = "https://api.taskmanager.com/v1/tasks"
headers = {"X-API-Key": "YOUR_API_KEY"}
params = {"limit": 10, "offset": 0}
response = requests.get(url, headers=headers, params=params)
print(response.json())
Example (JavaScript)
fetch("https://api.taskmanager.com/v1/tasks?limit=10&offset=0", {
method: "GET",
headers: {
"X-API-Key": "YOUR_API_KEY"
}
})
.then(res => res.json())
.then(data => console.log(data));
POST /tasks
Request Body (JSON)
{
"title": "Buy groceries",
"description": "Milk, Bread, Eggs",
"dueDate": "2025-01-15T00:00:00Z"
}
Responses
-
201 Created – JSON of the created task.
-
400 Bad Request – Validation errors.
-
401 Unauthorized – Missing or invalid API key.
Example (cURL)
curl -X POST "https://api.taskmanager.com/v1/tasks" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{"title":"Buy groceries","description":"Milk, Bread, Eggs","dueDate":"2025-01-15T00:00:00Z"}'
Example (Python)
import requests
url = "https://api.taskmanager.com/v1/tasks"
headers = {
"Content-Type": "application/json",
"X-API-Key": "YOUR_API_KEY"
}
payload = {
"title": "Buy groceries",
"description": "Milk, Bread, Eggs",
"dueDate": "2025-01-15T00:00:00Z"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
Example (JavaScript)
fetch("https://api.taskmanager.com/v1/tasks", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": "YOUR_API_KEY"
},
body: JSON.stringify({
title: "Buy groceries",
description: "Milk, Bread, Eggs",
dueDate: "2025-01-15T00:00:00Z"
})
})
.then(res => res.json())
.then(data => console.log(data));
GET /tasks/{id}
Path Parameter
| Parameter | Type | Required | Description |
|---|
id | UUID | required | Identifier of the task to retrieve. |
Responses
-
200 OK – JSON task object.
-
404 Not Found – Task does not exist.
-
401 Unauthorized – Missing or invalid API key.
Example (cURL)
curl -X GET "https://api.taskmanager.com/v1/tasks/123e4567-e89b-12d3-a456-426614174000" \
-H "X-API-Key: YOUR_API_KEY"
(Python and JavaScript examples follow the same pattern as above.)
Error Handling
All error responses follow this JSON structure:
{
"code": 401,
"message": "Invalid API key."
}
-
code – HTTP status code.
-
message – Human‑readable description of the error.
Rate Limiting
The API allows 100 requests per minute per API key. Exceeding this limit returns a 429 Too Many Requests response.
Examples
Full example scripts for each language are available in the examples/ directory of the repository.
Contributing
We welcome contributions! Please fork the repository, make your changes, and open a pull request. Follow the standard GitHub flow and ensure your code passes all linting checks.
License
This project is licensed under the MIT License. See the LICENSE file for details.
Support
If you have questions or need assistance, email support@taskmanager.com.
## Appendix A – FAQ
**Q1: I don’t have an API key yet. What should I do?**
A: Contact the API provider (support email listed in the README) to request an API key. Until you have one, you can still view the documentation but cannot make authenticated calls.
**Q2: Can I use the README for a private internal API?**
A: Yes. Replace the public contact information with your internal support channel and adjust the license section accordingly.
**Q3: My API uses OAuth 2.0 instead of an API key. How should I modify the README?**
A: Replace the “Authentication” section with an OAuth 2.0 flow description (e.g., client‑credentials or authorization‑code). Include the token endpoint URL and example `Authorization: Bearer <TOKEN>` header.
**Q4: The generated code snippets are in Python 2. Should I upgrade them?**
A: The SOP always generates Python 3 snippets using the `requests` library. If you need a different version, edit the examples manually.
**Q5: How do I add additional languages for the examples?**
A: Extend the “Examples” section by following the same pattern as the existing snippets. Use the appropriate language‑specific HTTP client and keep placeholder values consistent.
**Q6: My API has pagination via `next` links instead of `limit/offset`.**
A: Update the endpoint description to reflect the pagination method and adjust the example calls to follow the `next` URL returned in responses.
**Q7: The README is too long. Can I shorten it?**
A: Keep the mandatory sections (Installation, Authentication, API Endpoints, Error Handling, License). Optional sections like “Contributing” or “Examples” can be trimmed or moved to separate files.
**Q8: Where should I store the generated README?**
A: Place it at the root of your repository as `README.md`. GitHub will automatically render it on the project’s main page.
## Appendix B – Glossary
| Term | Definition |
|------|------------|
| **API** | Application Programming Interface – a set of rules that allows software programs to communicate with each other. |
| **README** | A markdown file that provides an overview, usage instructions, and other essential information about a software project. |
| **Endpoint** | A specific URL path combined with an HTTP method (GET, POST, etc.) that performs an operation in the API. |
| **Authentication** | The process of verifying the identity of a client making a request to the API, typically using an API key, token, or credentials. |
| **cURL** | A command‑line tool for transferring data with URLs, commonly used to test HTTP APIs. |
| **JSON** | JavaScript Object Notation – a lightweight data‑interchange format that is easy for humans to read and write. |
| **Rate Limit** | A restriction on the number of API requests a client can make within a given time window. |
| **OAuth 2.0** | An open standard for access delegation, commonly used for token‑based authentication. |
| **UUID** | Universally Unique Identifier – a 128‑bit number used to uniquely identify information in computer systems. |
| **MIT License** | A permissive open‑source license that allows reuse with minimal restrictions. |
## Appendix C – Z
### C1. Standard README Section Checklist
1. **Title** – API name and version.
2. **Short Description** – One‑sentence purpose statement.
3. **Table of Contents** – Links to each major heading.
4. **Installation / Prerequisites** – Tools, libraries, or environment variables needed.
5. **Authentication** – Detailed steps to obtain and use credentials.
6. **Base URL** – The root URL for all endpoints.
7. **API Endpoints** – Table summarizing each endpoint, followed by detailed subsections.
8. **Request / Response Formats** – Parameter tables, JSON schema snippets, status codes.
9. **Error Handling** – Common error structure and examples.
10. **Rate Limiting** – Limits per time unit and handling of `429` responses.
11. **Examples** – cURL, Python, JavaScript (or other language) snippets for key operations.
12. **Contributing** – Guidelines for external contributors (branching model, code style).
13. **License** – Legal terms governing use and distribution.
14. **Support / Contact** – Email or issue tracker link.
### C2. Markdown Style Guide
- **Headings** – Use `#` for the main title, `##` for top‑level sections, `###` for subsections.
- **Lists** – Bulleted lists for unordered items (`-` or `*`). Numbered lists for ordered steps.
- **Code Blocks** – Triple backticks with language identifier (`bash`, `python`, `javascript`).
- **Inline Code** – Single backticks for short identifiers (e.g., `X-API-Key`).
- **Links** – Use `[link text](URL)` syntax.
- **Tables** – Pipe (`|`) separated columns, header row followed by a separator row (`---`).
- **Line Length** – Aim for ≤ 120 characters per line for readability.
- **Emphasis** – Use `**bold**` for section headings inside tables, `*italic*` sparingly.
### C3. Example Code Templates
#### cURL Template
```bash
curl -X {METHOD} "https://api.example.com{PATH}{QUERY_STRING}" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{BODY}'
-
Replace {METHOD} with GET, POST, etc.
-
{PATH} is the endpoint path (e.g., /tasks).
-
{QUERY_STRING} includes any ?key=value pairs; leave empty if none.
-
{BODY} is a JSON payload for POST/PUT requests; omit the -d line for GET/DELETE.
Python (requests) Template
import requests
url = "https://api.example.com{PATH}{QUERY_STRING}"
headers = {
"Content-Type": "application/json",
"X-API-Key": "YOUR_API_KEY"
}
payload = {BODY_DICT} # Use a Python dict for JSON bodies
response = requests.{method_lower}(url, headers=headers, json=payload)
print(response.status_code)
print(response.json())
-
Set {method_lower} to get, post, put, etc.
-
payload can be omitted for methods that do not send a body.
JavaScript (fetch) Template
fetch("https://api.example.com{PATH}{QUERY_STRING}", {
method: "{METHOD}",
headers: {
"Content-Type": "application/json",
"X-API-Key": "YOUR_API_KEY"
},
body: JSON.stringify({BODY_OBJECT}) // Omit for GET/DELETE
})
.then(res => {
if (!res.ok) throw new Error(`HTTP ${res.status}`);
return res.json();
})
.then(data => console.log(data))
.catch(err => console.error(err));
- Replace
{BODY_OBJECT} with a JavaScript object literal representing the request payload.
C4. Common Error Response Patterns
| Status Code | Typical Meaning | Example JSON |
|---|
400 | Bad request – validation failed | { "code": 400, "message": "Missing required field title." } |
401 | Unauthorized – missing/invalid credentials | { "code": 401, "message": "Invalid API key." } |
404 | Not found – resource does not exist | { "code": 404, "message": "Task not found." } |
429 | Too many requests – rate limit exceeded | { "code": 429, "message": "Rate limit exceeded. Try again later." } |
500 | Internal server error – unexpected condition | { "code": 500, "message": "Unexpected error. Contact support." } |
C5. License Boilerplate (MIT)
MIT License
Copyright (c) {YEAR} {YOUR_ORGANIZATION}
Permission is hereby granted, free of charge, to any person obtaining a copy
...
Replace {YEAR} and {YOUR_ORGANIZATION} with the appropriate values.
C6. Contribution Guidelines Snapshot
-
Fork the repository.
-
Create a feature branch (git checkout -b feature/your-feature).
-
Write clean, lint‑compliant code.
-
Add or update tests.
-
Ensure README.md reflects any new endpoints or changes.
-
Submit a pull request with a clear description of the changes.
.*
