feat: adding API design guidelines

[pengying]

TL;DR

Added API design guidelines documentation to standardize our API development practices.

What changed?

Created a comprehensive README.md in the openapi directory that outlines best practices for API design, including:

• Directory structure and file naming conventions
• Versioning strategy and breaking change guidelines
• Naming conventions for resources, IDs, and fields
• Service patterns for states, actions, and resources
• OpenAPI best practices for documentation and validation
• HTTP methods and status code usage
• Pagination implementation details
• Error handling structure and guidelines
• Stainless SDK patterns and examples
• Redocly CLI usage for bundling and linting

[pengying]

• feat: adding API design guidelines #137 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[greptile-apps]

Greptile Overview

Greptile Summary

Added comprehensive API design guidelines documentation to standardize API development practices across the Grid API. The documentation covers:

• Directory structure and file naming conventions that align with current codebase organization
• Date-based versioning strategy (YYYY-MM-DD format) with clear breaking vs. non-breaking change definitions
• Naming conventions for resources, IDs, fields, and query parameters
• Service patterns for state machines, resource actions, and pagination (cursor-based with hasMore/nextCursor)
• OpenAPI best practices including discriminators for oneOf, validation rules, and documentation standards
• HTTP methods/status codes usage aligned with REST principles
• Structured error handling with aggregated error codes by HTTP status
• Stainless SDK integration patterns and Redocly CLI usage

The guidelines accurately reflect the existing codebase patterns (verified against actual openapi/ structure, pagination implementation in /customers, error schemas, and ID formats). One minor typo was identified and noted in the review comments.

Confidence Score: 5/5

• This PR is safe to merge with minimal risk - it only adds documentation without modifying any code or API specifications
• Score reflects that this is a documentation-only PR that adds valuable API design guidelines. The guidelines accurately reflect existing codebase patterns (verified against actual directory structure, pagination implementation, error schemas, and ID formats). Only one minor typo was found, which has already been noted in previous review threads.
• No files require special attention

Important Files Changed

Filename	Overview
openapi/README.md	Comprehensive API design guidelines documentation covering versioning, naming conventions, service patterns, pagination, error handling, and OpenAPI best practices

Sequence Diagram

sequenceDiagram
    participant Developer
    participant OpenAPI Spec
    participant Redocly CLI
    participant Stainless
    participant SDK

    Developer->>OpenAPI Spec: Edit files in openapi/ directory
    Note over Developer,OpenAPI Spec: Follow naming conventions<br/>Add descriptions & examples<br/>Define schemas & endpoints
    
    Developer->>Redocly CLI: npm run build:openapi
    Redocly CLI->>OpenAPI Spec: Bundle modular files
    Redocly CLI->>OpenAPI Spec: Generate openapi.yaml
    
    Developer->>Redocly CLI: npm run lint:openapi
    Redocly CLI->>OpenAPI Spec: Validate schema
    Redocly CLI-->>Developer: Report issues (if any)
    
    Developer->>Stainless: Release SDK version
    Stainless->>OpenAPI Spec: Read bundled spec
    Stainless->>Stainless: Detect breaking changes
    Stainless->>SDK: Generate SDK code
    Note over Stainless,SDK: Auto-pagination support<br/>Type-safe errors<br/>Code examples
    
    SDK-->>Developer: SDK with API reference examples

Loading

[greptile-apps]

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

typo: double space in "your API works"

Suggested change

	- Imagine you're teaching a customer how to use our API. How might you structure the API to make it easy to explain and understand?
	- Can integrators guess how your API works based on how other features work?

Prompt To Fix With AI

This is a comment left during a code review.
Path: openapi/README.md
Line: 12:12

Comment:
typo: double space in "your API  works"

```suggestion
- Can integrators guess how your API works based on how other features work?
```

How can I resolve this? If you propose a fix, please make it concise.