API Reference in READMEs — Complete Guide

In this tutorial, you will learn about API Reference in READMEs. We cover key concepts, practical examples, and best practices to help you master this topic.

API reference documentation in READMEs covers the essential functions, classes, parameters, and return values without overwhelming readers. Learn to write concise API docs that are comprehensive enough to use independently but brief enough to scan in under a minute.

What You'll Learn

How to structure API reference in a README, what to include versus what to link to full docs, how to document functions with parameters and return values, how to use tables for quick reference, and how to keep the reference section scannable.

Why It Matters

Many developers use the README as their primary API reference. If your README API section is clear and complete, they never need to visit your documentation site. If it is missing or confusing, they abandon the project or open unnecessary issues.

Real-World Use

The axios README includes a complete API reference section covering the request config, response schema, and all methods. It is comprehensive enough for most use cases but concise enough to navigate. Developers rarely need the full documentation site.

API Reference Structure

flowchart TD
  A[API Reference] --> B[Core Functions]
  A --> C[Options / Config]
  A --> D[Types / Interfaces]
  A --> E[Error Types]
  B --> F[Function signatures]
  B --> G[Parameters]
  B --> H[Return values]
  C --> I[Configuration object]
  C --> J[Default values]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Function Documentation

Document each public function with its signature, parameters, and return type.

## API

### `parseFile(path, options?)`

Parses a CSV file and returns all rows as an array of objects.

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| path | `string \| URL` | — | Path or URL to the CSV file |
| options | `ParseOptions` | `{}` | Optional parsing configuration |

**Returns:** `Promise<Row[]>`

**Example:**
```<a href="/programming-languages/typescript/">TypeScript</a>
import { parseFile } from "fastcsv";

const rows = await parseFile("data.csv", {
  delimiter: ",",
  encoding: "utf-8",
});
console.log(rows[0]); // { name: 'Alice', age: 30 }

## Options Documentation

Document the configuration object with all available options.

```typescript
### `ParseOptions`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| delimiter | `string` | `","` | Column delimiter character |
| encoding | `string` | `"utf-8"` | File encoding |
| header | `boolean` | `true` | First row is header |
| skipEmptyLines | `boolean` | `true` | Skip empty lines |
| maxRows | `number` | `Infinity` | Maximum rows to parse |
| transform | `(value, column) => any` | — | Transform function per cell |

Class Documentation

For object-oriented APIs, document classes with their methods.

### `CSVParser`

Creates a reusable CSV parser instance.

```typescript
const parser = new CSVParser({ delimiter: ",", header: true });

Methods

parseFile(path) Parses a file and returns rows.

parseString(text) Parses a CSV string and returns rows.

parseStream(readable) Parses a readable stream and returns rows as they arrive.

Example

import { CSVParser } from "fastcsv";

const parser = new CSVParser({ header: true });
const rows = parser.parseString("name,age\nAlice,30\nBob,25");
console.log(rows);

// Expected output:
// [{ name: 'Alice', age: 30 }, { name: 'Bob', age: 25 }]

## Error Documentation

Document the error types the API can throw.

```typescript
### Errors

The library throws typed errors that you can catch and handle:

| Error | When Thrown |
|-------|-------------|
| `FileNotFoundError` | The specified file does not exist |
| `ParseError` | The CSV content is malformed |
| `EncodingError` | The file encoding is not supported |

**Example:**

```typescript
import { parseFile, ParseError, FileNotFoundError } from "fastcsv";

try {
  const rows = await parseFile("missing.csv");
} catch (error) {
  if (error instanceof FileNotFoundError) {
    console.error("File not found. Check the path.");
  } else if (error instanceof ParseError) {
    console.error("CSV <a href="/compiler-design/syntax-analysis/">Parsing</a> failed:", error.message);
  }
}

## Linking to Full Documentation

For complete details, link to the full documentation site.

```markdown
## API Reference

This section covers the most commonly used API features.

For the complete API reference, including advanced options, streaming,
and performance tuning, see the [full documentation](https://fastcsv.dev/docs/api).

---

### Core Functions

...

Common Mistakes

1. No API Reference

A README with installation and usage but no API reference forces developers to guess at available functions and options.

2. Incomplete Documentation

Documenting some functions but not others. Every public API function should appear in the reference.

3. No Type Information

Functions without parameter types and return types. Developers need to know what types to pass and expect.

4. No Default Values

Options without documented defaults force developers to guess.

5. Trying to Be Too Complete

Including every internal function and private method in the README. Only document the public API.

6. No Examples in API Doc

Function signatures without usage examples. The API reference should include brief examples for each function.

7. Outdated API Reference

API reference that describes old parameter names or removed functions. Update the reference with every release.

Practice Questions

1. What should every function in the API reference include?

Function signature, parameter names with types and defaults, return type, description, and a usage example.

2. How do you balance completeness and brevity in a README API reference?

Include all public API functions but keep each entry concise. Use tables for parameters and options. Link to full documentation for advanced details.

3. Why include error types in the API reference?

Error types help developers build robust error handling. Without documented error types, developers use generic catch blocks without knowing what to handle.

4. What is the difference between README API reference and full documentation site?

The README reference is concise and covers the essentials. The full documentation site provides comprehensive coverage with advanced examples, performance guides, and Migration guides.

5. Challenge: Write the API reference section for a library with 4 public functions, 2 types/interfaces, and 2 error types. Include parameter tables, return types, and usage examples for each function.

FAQ

Mini Project: API Reference Section

Write the complete API reference section for a fictional library with 5 public functions, 3 configuration options, and 2 error types. Use tables for parameters and options, include return types, and provide usage examples for each function.

What's Next

API reference covers the functions. Now learn to document configuration with Configuration Documentation. Then explore Contributing Guide.