api-feature

description	Imported skill api_feature from openai
name	api_feature
signature	5ac3e41507ad34c1a18d3c964a431c464fdaa1593bda96e5cf00b169a4ee46c6
source	/a0/tmp/skills_research/openai/skills/.curated/notion-spec-to-implementation/examples/api-feature.md

Example: API Feature Implementation

User Request

"Create an implementation plan for the User Profile API spec"

Workflow Execution

Step 1: Fetch Specification

Notion:notion-search
query: "User Profile API spec"
query_type: "internal"

Found: "User Profile API Specification" in Engineering Specs

Notion:notion-fetch
id: "user-profile-api-spec-page-id"

Step 2: Parse Specification

Spec Content Extracted:

# User Profile API Specification

## Overview
RESTful API for user profile management

## Requirements

### Functional
- FR-1: Get user profile by ID
- FR-2: Update user profile (name, bio, avatar)
- FR-3: Upload profile avatar
- FR-4: Get user's public profile (limited fields)
- FR-5: Search users by name

### Non-Functional
- NFR-1: Response time < 200ms (p95)
- NFR-2: Support 1000 concurrent users
- NFR-3: Avatar upload < 5MB
- NFR-4: GDPR compliant (data portability)

## API Endpoints

GET /api/v1/users/:id
PUT /api/v1/users/:id
POST /api/v1/users/:id/avatar
GET /api/v1/users/:id/public
GET /api/v1/users/search

## Data Model
- id (UUID)
- email (string, unique)
- name (string)
- bio (text, max 500 chars)
- avatar_url (string)
- created_at (timestamp)
- updated_at (timestamp)

## Security
- Authentication: JWT bearer token
- Authorization: Users can only update own profile
- Rate limiting: 100 req/min per user

## Acceptance Criteria
- AC-1: All endpoints return proper HTTP status codes
- AC-2: Validation errors return 400 with error details
- AC-3: Unauthorized access returns 401
- AC-4: Rate limit exceeded returns 429
- AC-5: Avatar images stored in S3

Step 3: Create Implementation Plan

Notion:notion-create-pages

parent: { page_id: "engineering-plans-parent-id" }

pages: [{
  properties: {
    "title": "Implementation Plan: User Profile API"
  },
  content: "[Implementation plan]"
}]

Implementation Plan Created:

# Implementation Plan: User Profile API

## Overview
Build RESTful API for user profile management with CRUD operations, avatar upload, and search functionality.

## Linked Specification
<mention-page url="...">User Profile API Specification</mention-page>

## Requirements Summary

### Functional Requirements
- ✅ Get user profile (authenticated)
- ✅ Update profile fields (name, bio)
- ✅ Upload avatar with image processing
- ✅ Public profile view (limited fields)
- ✅ User search by name

### Non-Functional Requirements
- **Performance**: < 200ms response time (p95)
- **Scalability**: 1000 concurrent users
- **Storage**: Avatar files < 5MB to S3
- **Compliance**: GDPR data portability

### Acceptance Criteria
- All endpoints with proper status codes
- Input validation with error details
- JWT authentication required
- Rate limiting enforced
- Avatars stored in S3

## Technical Approach

### Architecture
- **Framework**: Express.js (Node.js)
- **Database**: PostgreSQL
- **Storage**: AWS S3 for avatars
- **Cache**: Redis for profile data
- **Search**: PostgreSQL full-text search


 : Stateless auth, scales horizontally
 : Offload storage, CDN integration ready
 : Reduce DB load for frequently accessed profiles
 : Token bucket algorithm, per-user limits




: Set up core infrastructure

:
 [ ] Setup database schema
 [ ] Configure S3 bucket
 [ ] Setup Redis cache
 [ ] Create API scaffolding

: Working skeleton with DB, storage, cache ready  
: 2 days


: Implement main CRUD operations

:
 [ ] Implement GET user profile
 [ ] Implement PUT update profile
 [ ] Add input validation
 [ ] Add JWT authentication middleware
 [ ] Implement rate limiting

: Working CRUD operations with auth  
: 3 days


: Avatar management with S3

:
 [ ] Implement avatar upload endpoint
 [ ] Add image validation (size, format)
 [ ] Process and resize images
 [ ] Upload to S3 with signed URLs

: Avatar upload/update functionality  
: 2 days


: Complete remaining features

:
 [ ] Implement user search
 [ ] Implement public profile endpoint
 [ ] Add search indexing
 [ ] Optimize search queries

: Search and public profiles working  
: 2 days


: Production-ready quality

:
 [ ] Write unit tests
 [ ] Write integration tests
 [ ] Performance testing
 [ ] Security audit
 [ ] API documentation

: Tested, documented, production-ready API  
: 3 days




 AWS S3 bucket created ✅
 Redis instance available ✅
 PostgreSQL database provisioned ✅


 JWT authentication service (exists)
 User database table (exists)
 Logging infrastructure (exists)


None currently




 : Medium
 : Medium
 : Use background job queue for processing, return signed upload URL immediately


 : Low
 : Medium
 : Implement retry logic with exponential backoff, fallback to local storage temporarily


 : Low
 : Low
 : Use proven library (express-rate-limit with Redis store)


 : Medium
 : Medium
 : Add database indexes, consider Elasticsearch if needed later



| Milestone | Target Date | Status |
|-----------|-------------|--------|
| Phase 1 Complete | Oct 16 | ⏳ Planned |
| Phase 2 Complete | Oct 19 | ⏳ Planned |
| Phase 3 Complete | Oct 21 | ⏳ Planned |
| Phase 4 Complete | Oct 23 | ⏳ Planned |
| Phase 5 Complete | Oct 26 | ⏳ Planned |
|  |  | ⏳ Planned |

: 12 working days (~2.5 weeks)




 [ ] All 5 endpoints implemented and working
 [ ] Response time < 200ms (p95) verified in load testing
 [ ] Handles 1000 concurrent users
 [ ] All acceptance criteria met
 [ ] Test coverage > 80%
 [ ] Security scan passed
 [ ] API documentation complete


 [ ] User profile updates functional
 [ ] Avatar uploads working reliably
 [ ] Search returns relevant results in < 500ms
 [ ] Zero critical bugs in first week




 User Profile API Specification (original spec)
 Authentication Service Docs
 AWS S3 Setup Guide


 User Authentication API (similar pattern)
 File Upload Service (avatar upload reference)


 Express.js best practices
 AWS S3 SDK documentation
 PostgreSQL full-text search guide




 Phase 1: ⏳ Not Started
 Phase 2: ⏳ Not Started
 Phase 3: ⏳ Not Started
 Phase 4: ⏳ Not Started
 Phase 5: ⏳ Not Started

: 0% complete

Step 4: Find Task Database

Notion:notion-search
query: "Tasks database"
query_type: "internal"

Found: "Engineering Tasks" database

Step 5: Fetch Task Database Schema

Notion:notion-fetch
id: "tasks-database-id"

Schema retrieved:

• Data source: collection://tasks-db-uuid
• Properties: Name (title), Status (select), Priority (select), Related Tasks (relation), Story Points (number), Tags (multi_select)

Step 6: Create Implementation Tasks

Now create tasks for Phase 1:

Task 1: Setup database schema

Notion:notion-create-pages

parent: { data_source_id: "collection://tasks-db-uuid" }

pages: [{
  properties: {
    "Name": "Setup database schema for User Profile API",
    "Status": "To Do",
    "Priority": "High",
    "Related Tasks": ["impl-plan-page-id", "spec-page-id"],
    "Story Points": 3,
    "Tags": "backend, database, api"
  },
  content: "## Context\nImplementation task for <mention-page url=\"...\">User Profile API Specification</mention-page>\n\nPart of <mention-page url=\"...\">Implementation Plan: User Profile API</mention-page> - Phase 1\n\n## Objective\nCreate database schema for user profile storage\n\n## Requirements\nBased on spec data model:\n- id (UUID, primary key)\n- email (string, unique index)\n- name (string, not null)\n- bio (text, max 500 chars)\n- avatar_url (string, nullable)\n- created_at (timestamp)\n- updated_at (timestamp)\n\n## Acceptance Criteria\n- [ ] Migration file created\n- [ ] Schema includes all required fields\n- [ ] Indexes on email (unique) and name (search)\n- [ ] Constraints validated (bio length, email format)\n- [ ] Migration tested on dev database\n- [ ] Rollback migration created\n\n## Technical Approach\n```sql\nCREATE TABLE user_profiles (\n  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n  email VARCHAR(255) UNIQUE NOT NULL,\n  name VARCHAR(255) NOT NULL,\n  bio TEXT CHECK (length(bio) <= 500),\n  avatar_url TEXT,\n  created_at TIMESTAMP DEFAULT NOW(),\n  updated_at TIMESTAMP DEFAULT NOW()\n);\n\nCREATE INDEX idx_user_profiles_email ON user_profiles(email);\nCREATE INDEX idx_user_profiles_name ON user_profiles USING gin(to_tsvector('english', name));\n```\n\n## Dependencies\n- Blocked By: None\n- Blocks: All Phase 2 tasks\n\n## Estimated Effort\n3 story points (half day)\n"
}]

[Create similar tasks for all phases - 20 tasks total]

Step 7: Link Plan Back to Spec

Notion:notion-update-page
page_id: "user-profile-api-spec-page-id"
command: "insert_content_after"
selection_with_ellipsis: "## Acceptance Criteria..."
new_str: "

---

## Implementation

**Implementation Plan**: <mention-page url=\"...\">Implementation Plan: User Profile API</mention-page>

**Implementation Tasks**: See plan for full task breakdown (20 tasks across 5 phases)

**Status**: Planning complete, ready to start implementation
"

Summary Provided to User

## Implementation Plan Created ✅

### Plan Overview
- **Feature**: User Profile API
- **Duration**: 12 days (~2.5 weeks)
- **Phases**: 5 (Foundation → Core → Avatar → Search → Testing)
- **Tasks**: 20 tasks created
- **Target Launch**: October 28, 2025

### Implementation Phases

**Phase 1: Foundation** (2 days)
- Database schema
- S3 and Redis setup
- API scaffolding

**Phase 2: Core Endpoints** (3 days)
- GET/PUT user profile
- Authentication & validation
- Rate limiting

**Phase 3: Avatar Upload** (2 days)
- Image upload & validation
- S3 integration
- Image processing

**Phase 4: Search & Public Profile** (2 days)
- User search
- Public profile endpoint

**Phase 5: Testing & Optimization** (3 days)
- Unit & integration tests
- Performance testing
- Documentation

### Key Deliverables
- 5 REST API endpoints
- Avatar upload to S3
- User search functionality
- Comprehensive tests
- API documentation

### Links Created
✅ Plan page: <mention-page url="...">Implementation Plan: User Profile API</mention-page>
✅ Spec updated with plan link
✅ 20 tasks created in task database
✅ All tasks linked to plan and spec


 Review and approve plan
 Assign tasks to team members
 Begin Phase 1 (Foundation)
 Daily standups for progress tracking

Key Features Demonstrated

Spec Parsing

• Extracted requirements (functional & non-functional)
• Identified API endpoints
• Noted data model
• Captured acceptance criteria
• Understood security requirements

Implementation Planning

• Broke into logical phases
• Sequenced work appropriately (foundation → features → testing)
• Identified dependencies
• Estimated effort per phase
• Created realistic timeline

Task Creation

• Generated 20 specific tasks
• Each task has context, acceptance criteria, technical approach
• Tasks link to both spec and plan
• Proper dependencies noted

Bidirectional Linking

• Plan links to spec
• Spec updated to link to plan
• Tasks link to both
• Easy navigation between all artifacts

Perfect for: Feature implementation, API development, technical projects