3. API design principles for CAE analytics

CAE analytics platforms rarely expose a single API style. A solver job submission endpoint, a mesh metadata query, and a real-time convergence stream have fundamentally different latency, payload, and coupling requirements. Choosing the wrong protocol for a given interaction produces either over-engineered infrastructure or brittle clients. This section establishes the design principles that govern protocol selection and interface specification across a CAE analytics service surface.

Matching Protocol to Interaction Pattern

The four interface technologies in scope are not competitors; they occupy distinct roles in a production CAE data service.

REST remains the correct default for resource-oriented CRUD: managing simulation projects, uploading result archives, retrieving material libraries, and exposing coarse-grained analytics endpoints. Its strengths are cacheability, ubiquitous tooling, and human-readable payloads. Its weakness is chatty access patterns — fetching a 200-part assembly's per-part stress summary via REST typically requires either N requests or a bespoke aggregate endpoint.

gRPC targets high-frequency, low-latency, strongly typed communication. In CAE contexts this means solver progress streaming, co-simulation coupling interfaces, and bulk transfer of field data (nodal displacements, element stresses) between services. Protocol Buffers give compact binary payloads and generated client stubs in C++, Python, and Java — languages that dominate CAE toolchains. Bidirectional streaming is the decisive capability: a transient thermal solver can push time-step results while the client pushes adaptive mesh refinement directives over one connection.

GraphQL solves the aggregation and over-fetching problem. A single query can retrieve a project's metadata, its three most recent run summaries, and the convergence status of each, without the client knowing which backend service owns each field. This suits engineering dashboards and reporting layers where the client shape varies by user role.

OpenAPI is not a transport but a specification language. It describes REST interfaces formally, enabling code generation, contract testing, and documentation. It is the governance layer that keeps a REST surface consistent as teams add endpoints.

REST Design Principles for CAE Resources

A CAE analytics REST surface should model domain entities as stable resource hierarchies. A workable URI structure:

GET    /api/v1/projects/{projectId}/simulations
POST   /api/v1/projects/{projectId}/simulations
GET    /api/v1/simulations/{simId}/runs
GET    /api/v1/runs/{runId}/results/summary
POST   /api/v1/runs/{runId}/results/fields   (initiate field data export)
GET    /api/v1/materials?category=composite&limit=50

Key principles: use nouns for resources, HTTP verbs for operations, and avoid verbs in paths. Pagination must be explicit — CAE result sets are large, so every collection endpoint should accept limit and cursor parameters and return a nextCursor field. Long-running operations (solver runs, field exports) should return 202 Accepted with a status resource URI rather than blocking the connection.

Versioning belongs in the path (/api/v1/) for major breaking changes. Within a version, additive changes — new optional fields, new endpoints — are safe. Removing or renaming a field is a breaking change requiring a version increment.

gRPC Service Contracts for Solver Communication

A representative gRPC service definition for solver progress streaming:

service SolverService {
  rpc SubmitJob (JobRequest) returns (JobHandle);
  rpc StreamProgress (JobHandle) returns (stream ProgressUpdate);
  rpc ExchangeCouplingData (stream CouplingFrame) returns (stream CouplingFrame);
}

message ProgressUpdate {
  string job_id = 1;
  int32 step = 2;
  double residual_l2 = 3;
  double wall_time_s = 4;
  enum Status { QUEUED = 0; RUNNING = 1; CONVERGED = 2; DIVERGED = 3; }
  Status status = 5;
}

Design rules for gRPC in CAE: keep messages flat where possible to reduce serialization overhead; use stream for any interaction producing more than a few updates per second; define explicit status enums rather than boolean flags; and never reuse field numbers after removal — mark them reserved. For coupling interfaces, bidirectional streaming with a fixed frame schema (nodal coordinates, field values, time stamp) keeps both solvers synchronized without polling.

GraphQL for Analytics Aggregation

GraphQL earns its place when a dashboard must combine data from multiple backend services in one round trip. A query for a project overview:

query ProjectOverview($id: ID!) {
  project(id: $id) {
    name
    simulations(last: 3) {
      name
      runs {
        status
        residualFinal
        wallTimeSeconds
      }
    }
  }
}

Design cautions: GraphQL's flexibility can produce expensive queries against large result stores. Enforce query depth limits, require pagination arguments on list fields, and use persisted queries in production so the server only executes pre-approved operations. Do not expose raw field-data arrays through GraphQL — those belong in gRPC or a file download endpoint.

OpenAPI as the Governance Contract

Every REST endpoint should be described in an OpenAPI 3.1 document. The specification is the source of truth for client generation, mock servers, and contract tests. A minimal path definition:

paths:
  /runs/{runId}/results/summary:
    get:
      operationId: getRunSummary
      parameters:
        - name: runId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Run summary metrics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunSummary'
        '404':
          description: Run not found

Governance practices: validate the spec in CI with a linter (e.g., Spectral) to enforce naming conventions and required error schemas; generate server stubs and client SDKs from the spec rather than hand-writing them; and treat any spec change as a reviewable pull request. This prevents the common failure where documentation drifts from implementation.

Cross-Cutting Design Rules

• Consistent error model: All protocols should return a structured error with a machine-readable code, a human message, and a correlation ID. For REST, use RFC 9457 Problem Details.
• Idempotency: Job submission and field export endpoints must accept an idempotency key so retries do not create duplicate solver runs.
• Authentication: Use OAuth 2.0 / OIDC tokens across all protocols. gRPC carries them in metadata; REST in the Authorization header; GraphQL in the same header.
• Observability: Propagate a trace context (W3C Trace Context) through REST headers, gRPC metadata, and GraphQL extensions so a single analytics request can be traced across services.
• Timeouts and deadlines: gRPC deadlines must be set on every call; REST clients should set connect and read timeouts; GraphQL servers should enforce a maximum execution time.

These principles are not independent. A production CAE analytics platform typically exposes REST + OpenAPI for management, gRPC for solver and field-data paths, and GraphQL for the dashboard aggregation layer — with shared authentication, error semantics, and tracing binding them into one coherent surface.