Temp - dennisholee/notes GitHub Wiki

Updated REST API Guideline

This unified document establishes design standards for Entity Services and Aggregate Services, focusing on endpoint construction, nesting, and structural boundaries.

Core Endpoint Design Philosophy

  • Use nouns for resource names, never verbs.
  • Use lowercase letters with hyphens (kebab-case) for readability.
  • Use plural nouns for collections (e.g., /products, not /product).
  • Use query parameters for filtering, sorting, and pagination (e.g., ?page=2&sort=-date).

1. Entity Services (Domain & CRUD Operations)

Entity services own the primary data storage for a single domain object. They handle strict data validation, schema enforcement, and standard CRUD lifecycles.

Base Resource Construction

Construct endpoints around the raw data resource.
  • GET /products: Retrieve a paginated list of products.
  • POST /products: Create a new product.
  • GET /products/{id}: Fetch a specific product by its identifier.
  • PUT /products/{id}: Replace an entire product resource.
  • PATCH /products/{id}: Partially update specific fields of a product.
  • DELETE /products/{id}: Remove a specific product.

Nested Entity Resources

Use nesting only when a child resource has a strict lifecyle dependency on the parent resource (it cannot exist without it). Limit nesting to one level deep to maintain clean URLs.
  • GET /products/{id}/reviews: Fetch all reviews belonging to a specific product.
  • POST /products/{id}/reviews: Add a review to a specific product.
  • GET /products/{id}/reviews/{reviewId}: Fetch a specific review within a product.

2. Aggregate Services (Orchestration & Views)

Aggregate services own no primary database. They act as an orchestration layer (often structured as Backend-for-Frontend, or BFF), fetching, combining, and formatting data from multiple underlying Entity Services to satisfy specific user interfaces.

Base Resource Construction

Construct endpoints around client views, business summaries, or high-level workflow contexts rather than raw database nouns.
  • GET /customer-profiles/{customerId}: Aggregates data from User Account, Billing, and Order History entity services.
  • GET /order-checkouts/{checkoutId}: Combines data from Cart, Inventory Check, Tax, and Shipping entity services.
  • POST /registrations: Coordinates a workflow by calling the User, Wallet, and Notification entity services in sequence.

Nested Aggregate Resources

For aggregate services, nested endpoints represent specific sub-views, structural widgets, or segmented analytical contexts of the combined screen payload.
  • GET /customer-profiles/{id}/security-status: Aggregates multi-factor authentication (MFA) settings, recent login history, and active sessions.
  • GET /vendor-dashboards/{id}/metrics/monthly: Combines time-series performance data from Orders, Refunds, and Payouts entity services for a specific monthly view.

Architectural Differences Matrix

Architectural Feature | Entity Service | Aggregate Service -- | -- | -- Data Ownership | Single database, table, or microservice boundary. | No primary database; reads/writes via other APIs. Business Scope | Validates field rules (e.g., price must be > 0). | Handles cross-domain workflows and data stitching. Nesting Focus | Explicit parent-child lifecycle dependencies. | Complex UI sub-views or dashboard widgets. HTTP Verbs | Utilizes all CRUD verbs (GET, POST, PUT, PATCH, DELETE). | Primarily uses GET for views and POST for orchestration tasks. Performance Driver | Database indexing, write speeds, and localized caching. | Concurrent API calling, data merging, and payload minimization.
Would you like me to draft the JSON request and response payload specs to show exactly how data is structured in these nested endpoints?

⚠️ **GitHub.com Fallback** ⚠️