APIs

Use apis to sync repository-owned API specification files as API groups in UIGraph.

Supported API types

• openapi
• graphql
• grpc

Minimal config

apis:
  - name: booking-openapi
    type: openapi
    path: ./specs/openapi.yaml

Each entry requires:

• name
• type
• path

What the CLI does

For each API entry, the CLI:

1. validates the type
2. checks that path exists
3. reads the spec file as raw content
4. sends the API group metadata and file content to the gateway

If a file does not exist, validation fails before sync.

Multiple APIs example

apis:
  - name: rest-api
    type: openapi
    path: ./specs/openapi.yaml

  - name: graphql-api
    type: graphql
    path: ./specs/schema.graphql

  - name: grpc-api
    type: grpc
    path: ./specs/service.proto

OpenAPI and test linkage

If you want API test cases to link to a specific operation, include:

• apiGroupName in the test case
• operationId in the test case
• matching operationId values in the OpenAPI document

Example:

apis:
  - name: storefront-api
    type: openapi
    path: ./.uigraph/openapi/storefront-sample.yaml

testPacks:
  - name: auth-smoke
    type: smoke
    testCases:
      - type: api
        title: Login returns 200
        order: 1
        apiGroupName: storefront-api
        operationId: loginUser
        expectedStatusCode: 200

Path tips

• Use repository-relative paths in .uigraph.yaml.
• Keep API specs versioned with code.
• Prefer stable file locations to reduce CI failures.

Recommended usage

• keep one API group name stable per spec file
• store OpenAPI, GraphQL, and gRPC artifacts next to the code they document
• add operationId values to OpenAPI specs when you want downstream test-case linking
• use dry-run in CI to catch missing file paths early