# Lunch Money API Specifications and Documentation

This repository contains the official API specifications and documentation for the [Lunch Money](https://lunchmoney.app) API. Lunch Money is a delightfully simple personal finance and budgeting tool with a comprehensive developer API.

## Repository Structure

This repository is organized in a multi-version structure to support current and future API versions:

```
.
├── v2/                    # Version 2 API specific content
│   ├── spec/              # OpenAPI specification (YAML)
│   ├── docs/              # Version-specific documentation guides
│   └── images/            # Images used in documentation
├── docs/                  # Version-independent documentation
├── scripts/               # Build and publishing scripts
└── spec/                  # Generated directory (created during npm publish)
```

### Directory Details

#### `v2/spec/` - OpenAPI Specification
The OpenAPI 3.0 specification file (`lunch-money-api-v2.yaml`) defines the complete API contract:
- All available endpoints
- Request/response schemas
- Authentication requirements
- Error responses
- Example requests and responses

**This is the source of truth for the API.** Changes to the specification automatically update the interactive API documentation.

#### `v2/docs/` - Version-Specific Documentation Guides
Markdown files containing detailed guides and reference material specific to v2:
- `intro-to-v2.md` - Overview of the v2 API and key features
- `migration-guide.md` - Guide for migrating from v1 to v2
- `version-history.md` - Changelog of all API versions

These guides are written in Markdown and support custom rendering features (see below).

#### `v2/images/` - Documentation Assets
Images and screenshots used in the documentation guides.

#### `docs/` - Version-Independent Documentation
Shared documentation that applies across all API versions:
- `getting-started.md` - Quick start guide for new developers (applies to all API versions)
- `rate-limiting.md` - Rate limiting policies and best practices (applies to all API versions)
- Additional version-independent guides (e.g., pagination guidelines, general API concepts)

## OpenAPI Specification vs Documentation Guides

There are two types of content in this repository, each serving a different purpose:

### OpenAPI Specification (`v2/spec/lunch-money-api-v2.yaml`)
- **Purpose**: Machine-readable API contract
- **Format**: YAML (OpenAPI 3.0)
- **Used for**: 
  - Generating interactive API documentation
  - Code generation for SDKs and client libraries
  - API validation and testing
  - IDE autocomplete and type checking
- **Editable**: Yes - changes here automatically update the docs

The OpenAPI spec is the authoritative source for:
- Endpoint definitions (paths, methods, parameters)
- Request/response schemas
- Authentication requirements
- Status codes and error formats

### Documentation Guides (`v2/docs/*.md`)
- **Purpose**: Human-readable guides and tutorials
- **Format**: Markdown with custom extensions
- **Used for**:
  - Developer onboarding and tutorials
  - Best practices and patterns
  - Migration guides and changelogs
  - Conceptual explanations
- **Editable**: Yes - written in Markdown with support for custom features

The guides provide context, examples, and explanations that complement the technical specification.

## Custom Markdown Features

The documentation system supports custom rendering features that enhance Markdown files. These features are processed when the documentation is served and can be used in any Markdown file in the `v2/docs/` directory.

### Callouts

Callouts are styled information boxes for highlighting important information, warnings, or tips.

**Syntax:**
```markdown
> [!TYPE]
> Title (optional)
> 
> Content goes here. This can span multiple lines
> and include **markdown formatting**.
```

**Supported Types:**
- `[!NOTE]` - General information or notes (blue styling)
- `[!TIP]` - Helpful tips or best practices (green styling)
- `[!WARNING]` - Warnings or important cautions (yellow/orange styling)

**Example:**
```markdown
> [!NOTE]
> API Rate Limits
> 
> The API has a rate limit of 1000 requests per 5 minutes per IP address.
```

### Tabs

Tabs organize content into multiple tabbed sections, useful for showing different code examples, API versions, or alternative approaches.

**Syntax:**
```markdown
:::tabs
@tab Tab Label 1
Content for the first tab. This can include **markdown** and code blocks.

@tab Tab Label 2
Content for the second tab. You can have as many tabs as needed.
:::
```

**Example: Code Examples in Multiple Languages**
```markdown
:::tabs
@tab cURL
```bash
curl -X GET "https://api.lunchmoney.app/v2/transactions" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

@tab JavaScript
```javascript
const response = await fetch('https://api.lunchmoney.app/v2/transactions', {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN'
  }
});
```
:::
```

**Usage Notes:**
- Each tab must start with `@tab` followed by the tab label
- The first tab is active by default when the page loads
- Tab content can include any markdown, including code blocks, lists, callouts, tables, and links
- You can combine callouts and tabs in various ways

## Versioning

The Lunch Money API uses a modified version of SEMVER:

- **Major version**: The API version (currently 2)
- **Minor version**: The number of main endpoints (OpenAPI tags) the spec supports
- **Revision number**: The number of updates since the last endpoint was added

For example, version `2.8.2` means:
- API version 2
- 8 main endpoint groups
- 2 updates since the 8th endpoint was added

Details of each version can be found in [`v2/docs/version-history.md`](./v2/docs/version-history.md).

### Branch Naming Convention

Each API version is maintained on a branch named after the version number (e.g., `v2.8.2`). The `main` branch typically tracks the most recent version.

## Using This Repository

### As an npm Package

This repository is published as `@lunchmoney/v2-api-spec` on npm for lightweight consumption:

```bash
npm install @lunchmoney/v2-api-spec
```

After installation, you can access:
- OpenAPI spec: `node_modules/@lunchmoney/v2-api-spec/spec/lunch-money-api-v2.yaml`
- Version history: `node_modules/@lunchmoney/v2-api-spec/spec/version-history.md`

### As a Git Repository

You can clone this repository directly:

```bash
git clone https://github.com/lunch-money/api-specs.git
cd api-specs
```

Or add it as a submodule to your project:

```bash
git submodule add https://github.com/lunch-money/api-specs.git specs/v2
```

## Contributing

We welcome contributions to improve the API documentation! When contributing:

1. **For API reference changes**: Update the OpenAPI specification in `v2/spec/lunch-money-api-v2.yaml`
2. **For documentation**: Update the relevant Markdown files in `v2/docs/`
3. **Version updates**: Update `v2/docs/version-history.md` with your changes
4. Create a pull request with a clear description of your changes

Please ensure that:
- OpenAPI spec changes are valid YAML and conform to OpenAPI 3.0
- Documentation follows the existing style and uses the custom Markdown features appropriately

## Resources

- [Lunch Money Website](https://lunchmoney.app)
- [Interactive API Documentation](https://alpha.lunchmoney.dev/v2/docs)
- [API Status](https://status.lunchmoney.app)