API Documentation | Sync Docs with Development

API documentation must stay synchronized with development. GitScrum includes doc updates in definitions of done and versions documentation with API releases.

4 min read

How to manage technical documentation for APIs?

Manage API documentation by including doc updates in API task definitions of done, storing documentation drafts in NoteVault during development, versioning docs with API releases, and creating separate doc review tasks. Use labels to identify tasks affecting public APIs that require documentation updates.

API documentation labels

Label	Purpose
api:public	Public API - docs required
api:internal	Internal API
docs:required	Documentation update needed
docs:breaking	Breaking change - needs attention
docs:example	Example code update
docs:generated	Auto-generated docs

API task with documentation

## API: Add User Preferences Endpoint

### Endpoint Design
- GET /api/v1/users/{id}/preferences
- PUT /api/v1/users/{id}/preferences

### Development
- [ ] Implement endpoints
- [ ] Add tests
- [ ] Code review

### Documentation (Required for public API)
- [ ] OpenAPI spec updated
- [ ] Request/response examples
- [ ] Error codes documented
- [ ] Authentication requirements
- [ ] Rate limits noted
- [ ] Changelog entry

Definition of Done:
- [ ] Docs reviewed by tech writer
- [ ] Examples tested and working

API documentation workflow:

API design - Spec in NoteVault before coding

Development - Build endpoint

Draft docs - Update OpenAPI/docs during dev

Code review - Include doc changes in PR

Doc review - Tech writer or peer review

Integration - Merge code + docs together

Publish - Update public documentation

Announce - Changelog, developer notification

NoteVault API documentation

# API Documentation

## Endpoints Overview

### Users API
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | /api/v1/users | List users |
| GET | /api/v1/users/{id} | Get user |
| POST | /api/v1/users | Create user |
| PUT | /api/v1/users/{id} | Update user |

## Authentication
All endpoints require Bearer token authentication.

## Rate Limits
- Standard: 100 requests/minute
- Premium: 1000 requests/minute

## Error Codes
| Code | Message | Resolution |
|------|---------|------------|
| 401 | Unauthorized | Check API key |
| 429 | Rate limited | Wait and retry |
| 500 | Server error | Contact support |

## Versioning
- Current: v1
- Deprecated: none
- Breaking changes: 90-day notice

## Changelog

### 2025-01-27 - v1.5.0
- Added: User preferences endpoints
- Changed: Rate limits increased
- Deprecated: None

Documentation quality checklist

[ ] All endpoints documented
[ ] Request/response examples included
[ ] Examples are tested and working
[ ] Error codes explained
[ ] Authentication described
[ ] Rate limits documented
[ ] Versioning clear
[ ] Changelog updated