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 to standardize development practices across the Grid API project. The new documentation covers versioning strategy (date-based API versioning with semver SDKs), naming conventions (plural resources, prefixed IDs, camelCase fields), service patterns (state machines with mermaid diagrams, resource actions, pagination), OpenAPI best practices (discriminators, validation, documentation), error handling structure, and tooling (Stainless SDK patterns, Redocly CLI usage).

• Establishes clear conventions for directory structure, file naming, and resource organization
• Documents breaking vs non-breaking changes with SDK implications
• Provides state machine patterns with visual mermaid diagrams for lifecycle documentation
• Standardizes error codes by HTTP status with SCREAMING_SNAKE_CASE convention
• Includes practical examples for discriminators, pagination, and SDK usage

Confidence Score: 4/5

• Safe to merge - documentation-only PR with minor issues already flagged
• This is a documentation-only PR adding comprehensive API design guidelines. The content is thorough, well-structured, and provides valuable standardization. Previous review threads have already identified the few minor issues (markdown formatting, TBD section, grammar). No code changes, no breaking changes, minimal risk.
• No files require special attention - the flagged issues are minor formatting/grammar fixes

Important Files Changed

Filename	Overview
openapi/README.md	Comprehensive API design documentation added with best practices for versioning, naming, patterns, and tooling

Sequence Diagram

sequenceDiagram
    participant Dev as Developer
    participant Doc as README.md
    participant Team as Team Members
    participant Impl as Implementation
    
    Dev->>Doc: Add API design guidelines
    Doc->>Doc: Define versioning strategy
    Doc->>Doc: Document naming conventions
    Doc->>Doc: Specify OpenAPI patterns
    Doc->>Doc: Describe error handling
    Doc->>Doc: Include SDK examples
    Team->>Doc: Consult guidelines
    Doc->>Team: Provide standards & patterns
    Team->>Impl: Apply consistent practices
    Impl->>Impl: Follow documented patterns

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]

_{1 file reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

[pengying]

Merge activity

• Feb 5, 3:17 AM UTC: A user started a stack merge that includes this pull request via Graphite.
• Feb 5, 3:17 AM UTC: @pengying merged this pull request with Graphite.