Deepen PracticeOrdered learning track

Learn Ai Code Documentation Agent Memory Part 028 Api Design And Openapi Contracts

[]9 min read1678 words

In This Lesson

1. Tujuan Part Ini 2. API Sebagai Product Contract 3. API Design Principles

Lesson 2835 lesson track20–29 Deepen Practice

title: Learn AI Code Documentation & Agent Memory Platform - Part 028 description: API design and OpenAPI contracts untuk repository intelligence platform, meliputi repository scan, search, graph, docs, context packs, memory, jobs, audit, errors, pagination, versioning, security, and agent-friendly contracts. series: learn-ai-code-documentation-agent-memory seriesTitle: Learn AI Code Documentation & Agent Memory Platform order: 28 partTitle: API Design and OpenAPI Contracts tags:

ai
api-design
openapi
rest-api
code-intelligence
documentation
agent-memory
platform-architecture date: 2026-07-02

Part 028 — API Design and OpenAPI Contracts

1. Tujuan Part Ini

Part 027 membahas workers dan jobs. Sekarang kita membahas cara mengekspos platform ke client: API design and OpenAPI contracts.

Platform ini akan digunakan oleh:

web UI,
CLI,
internal services,
MCP server,
AI agents,
CI/CD checks,
review workflows,
dashboards.

API harus stabil, typed, secure, auditable, versioned, dan mudah diintegrasikan.

Target part ini:

mendesain API surface untuk repository intelligence platform,
menentukan resource model,
membuat prinsip REST/OpenAPI,
mendesain request/response envelope,
mendesain error model,
mendesain pagination, filtering, sorting,
mengekspos jobs/workflows secara asynchronous,
membuat API untuk search, graph, docs, context, memory,
menjaga permission dan provenance,
menyiapkan OpenAPI-first workflow.

2. API Sebagai Product Contract

API bukan hanya jalan menuju database.

API adalah kontrak antara platform dan consumer.

Consumer butuh tahu:

endpoint apa yang ada,
input valid,
response shape,
error codes,
auth requirements,
pagination,
idempotency,
versioning,
rate limits,
deprecation policy.

2.1 API Consumers

Consumer	Need
Web UI	rich status, docs, review
CLI	scriptable commands
MCP server	typed tool execution
AI agent	predictable structured results
CI/CD	pass/fail checks
Admin dashboard	health, jobs, audit
Other service	integration via stable contract

3. API Design Principles

3.1 Resource-Oriented

Use nouns/resources:

/repositories
/repository-snapshots
/search
/graph/neighborhood
/documents
/context-packs
/memory-records
/jobs

3.2 Async for Heavy Operations

Repository scan, doc generation, reindexing, and maintenance should create jobs/workflows.

3.3 Explicit Scope

Requests should specify repository, snapshot, branch, commit, or target.

3.4 Evidence-Aware

Responses that make knowledge claims should include evidence or evidence references.

3.5 Permission-Safe

Never return unauthorized artifact metadata.

3.6 Versioned

API version in path or header.

Example:

/api/v1/repositories

3.7 Stable Error Model

Errors must be machine-readable.

3.8 OpenAPI-First

Write OpenAPI contract before implementation for public/core APIs.

4. API Surface Overview

apiGroups:
  repositories:
    - register repository
    - scan repository
    - get snapshots
    - get file inventory
  search:
    - hybrid search
    - exact symbol/file/API lookup
  graph:
    - neighborhood
    - impact
    - diff
    - flow
  documents:
    - list/get docs
    - generate draft
    - evaluate quality
    - review/publish workflow
  context:
    - assemble context pack
    - get context pack
  memory:
    - list/retrieve memory
    - create candidate
    - review candidate
    - revalidate memory
  jobs:
    - get job status
    - cancel job
    - retry job
  workflows:
    - start workflow
    - get workflow run
  audit:
    - query audit events
  admin:
    - health
    - processor versions
    - retention

5. Common API Envelope

5.1 Response Envelope

{
  "status": "ok",
  "data": {},
  "warnings": [],
  "meta": {
    "requestId": "req_01J...",
    "apiVersion": "v1"
  }
}

5.2 Error Envelope

{
  "status": "error",
  "error": {
    "code": "permission_denied",
    "message": "You do not have access to the requested repository.",
    "retryable": false,
    "details": {}
  },
  "meta": {
    "requestId": "req_01J...",
    "apiVersion": "v1"
  }
}

5.3 Partial Response

{
  "status": "partial",
  "data": {},
  "warnings": [
    {
      "code": "partial_index",
      "message": "Vector index is still building for this snapshot."
    }
  ],
  "meta": {}
}

6. Error Model

6.1 Standard Error Codes

Code	Meaning	Retry
`invalid_input`	schema/validation error	no
`permission_denied`	access denied	no
`not_found`	resource not found	no/maybe
`ambiguous_target`	multiple matches	no
`snapshot_not_indexed`	indexing unavailable	yes
`index_partial`	partial data available	maybe
`rate_limited`	too many requests	yes
`timeout`	operation timed out	yes
`conflict`	state conflict	no
`quality_gate_failed`	generated artifact failed gate	no/maybe
`sensitive_content_blocked`	content cannot be returned	no
`unsupported_operation`	not supported	no
`internal_error`	unexpected error	maybe

6.2 Error Detail Example

{
  "code": "ambiguous_target",
  "message": "Multiple symbols named OrderService were found.",
  "retryable": false,
  "details": {
    "candidates": [
      {
        "qualifiedName": "com.acme.order.OrderService",
        "repositoryId": "order-service"
      },
      {
        "qualifiedName": "com.acme.billing.OrderService",
        "repositoryId": "billing-service"
      }
    ]
  }
}

Do not include candidates user cannot access.

7. Authentication and Authorization

7.1 Authentication

API should derive user/principal from token/session.

Do not accept principal as trusted request body.

7.2 Authorization

Every handler checks:

tenant,
repository access,
artifact visibility,
tool/action permission,
write/review permission.

7.3 Auth Context

Internal service may receive:

authContext:
  tenantId: acme
  principalId: user_123
  accessVersion: authz_v42

7.4 Derived Artifact Visibility

Generated docs/context/memory inherit source visibility.

8. Pagination, Filtering, Sorting

8.1 Cursor Pagination

Prefer cursor pagination for large collections.

Request:

GET /api/v1/repositories?limit=50&cursor=...

Response:

{
  "data": {
    "items": [],
    "nextCursor": "cursor_..."
  }
}

8.2 Filtering

Use query params for simple filters:

GET /api/v1/documents?repositoryId=order-service&docType=module_doc&state=active

Use POST search for complex queries.

8.3 Sorting

sort=-updatedAt
sort=title

8.4 Limit Caps

Always cap limits.

limit:
  default: 50
  maximum: 200

9. Idempotency

9.1 Idempotent Create Operations

For operations that create jobs or drafts, accept idempotency key.

Header:

Idempotency-Key: docgen-order-validation-6f41ab2

9.2 Response

If same request repeated:

{
  "status": "ok",
  "data": {
    "jobId": "job_existing",
    "idempotentReplay": true
  }
}

9.3 Use Cases

scan repository,
generate doc draft,
create memory candidate,
publish document,
start workflow.

10. Repository APIs

10.1 Register Repository

POST /api/v1/repositories

Request:

{
  "provider": "github",
  "displayName": "order-service",
  "remoteUrl": "https://example.invalid/acme/order-service.git",
  "defaultBranch": "main",
  "ownerTeam": "team-order-platform"
}

Response:

{
  "status": "ok",
  "data": {
    "repositoryId": "repo_order_service"
  }
}

10.2 Start Scan

POST /api/v1/repositories/{repositoryId}/scans

Request:

{
  "branch": "main",
  "commitSha": "6f41ab2",
  "mode": "incremental"
}

Response:

{
  "status": "ok",
  "data": {
    "scanRunId": "scan_01J",
    "snapshotId": "snap_6f41ab2",
    "jobId": "job_01J"
  }
}

10.3 Get Snapshot

GET /api/v1/repository-snapshots/{snapshotId}

Response includes stage status.

10.4 List Files

GET /api/v1/repository-snapshots/{snapshotId}/files?pathPrefix=src/main/java

11. Source and Symbol APIs

11.1 Get File Span

GET /api/v1/repositories/{repositoryId}/files/{path}?commitSha=6f41ab2&startLine=12&endLine=144

Path should be URL-encoded.

Response:

{
  "data": {
    "path": "src/main/java/com/acme/order/OrderValidator.java",
    "commitSha": "6f41ab2",
    "language": "java",
    "startLine": 12,
    "endLine": 144,
    "content": "...",
    "trustBoundary": "untrusted_repository_content"
  }
}

11.2 Resolve Symbol

POST /api/v1/symbols/resolve

Request:

{
  "repositoryId": "order-service",
  "commitSha": "6f41ab2",
  "query": {
    "qualifiedName": "com.acme.order.OrderValidator.validate"
  }
}

Response:

{
  "data": {
    "symbol": {
      "symbolInstanceId": "sym_01J",
      "qualifiedName": "com.acme.order.OrderValidator.validate",
      "kind": "method",
      "path": "src/main/java/com/acme/order/OrderValidator.java",
      "span": {
        "startLine": 12,
        "endLine": 144
      },
      "confidence": 0.94
    }
  }
}

12. Search APIs

12.1 Hybrid Search

POST /api/v1/search

Request:

{
  "scope": {
    "repositoryId": "order-service",
    "commitSha": "6f41ab2"
  },
  "query": {
    "text": "where are validation rules registered?",
    "intent": "code_location"
  },
  "filters": {
    "includeDocs": true,
    "includeMemory": true,
    "chunkTypes": ["method_chunk", "doc_section_chunk", "memory_chunk"]
  },
  "maxResults": 10
}

Response:

{
  "data": {
    "retrievalRunId": "ret_01J",
    "results": [
      {
        "rank": 1,
        "artifactType": "chunk",
        "artifactId": "chunk_rule_registry",
        "title": "RuleRegistry",
        "path": "src/main/java/com/acme/order/validation/RuleRegistry.java",
        "score": 0.91,
        "reasons": [
          "semantic match",
          "same module",
          "primary source evidence"
        ],
        "evidence": [
          {
            "evidenceId": "E1",
            "type": "file_span",
            "path": "src/main/java/com/acme/order/validation/RuleRegistry.java",
            "lines": [10, 88]
          }
        ]
      }
    ]
  }
}

12.2 Exact Search

POST /api/v1/search/exact

For symbols, paths, endpoints, config keys.

13. Graph APIs

13.1 Neighborhood

POST /api/v1/graph/neighborhood

Request:

{
  "scope": {
    "repositoryId": "order-service",
    "commitSha": "6f41ab2"
  },
  "target": {
    "type": "symbol",
    "id": "sym_order_validator_validate"
  },
  "traversal": {
    "maxDepth": 2,
    "edgeTypes": ["CALLS", "TESTS", "DOCUMENTED_BY", "READS_CONFIG"],
    "maxNodes": 40
  }
}

Response:

{
  "data": {
    "nodes": [],
    "edges": [],
    "warnings": []
  }
}

13.2 Graph Diff

POST /api/v1/graph/diff

Request:

{
  "repositoryId": "order-service",
  "fromSnapshotId": "snap_old",
  "toSnapshotId": "snap_new"
}

13.3 Impact Analysis

POST /api/v1/graph/impact

Request:

{
  "change": {
    "repositoryId": "order-service",
    "fromCommit": "6f41ab2",
    "toCommit": "9ab812c",
    "changedArtifacts": [
      {
        "type": "file",
        "path": "src/main/java/com/acme/order/validation/OrderValidator.java"
      }
    ]
  }
}

Response includes affected symbols, tests, docs, memory, and confidence.

14. Context Pack APIs

14.1 Assemble Context Pack

POST /api/v1/context-packs

Request:

{
  "task": {
    "type": "generate_module_doc",
    "description": "Generate docs for order validation module"
  },
  "target": {
    "type": "module",
    "repositoryId": "order-service",
    "path": "src/main/java/com/acme/order/validation"
  },
  "source": {
    "branch": "main",
    "commitSha": "6f41ab2"
  },
  "options": {
    "maxTokens": 12000,
    "includeTests": true,
    "includeDocs": true,
    "includeMemory": true
  }
}

Response:

{
  "data": {
    "contextPackId": "ctx_01J",
    "qualityStatus": "pass_with_warnings",
    "estimatedTokens": 11200,
    "warnings": [
      {
        "code": "missing_adr",
        "message": "No ADR found for retry behavior."
      }
    ],
    "resourceUri": "context-pack://ctx_01J"
  }
}

14.2 Get Context Pack

GET /api/v1/context-packs/{contextPackId}

Can return metadata by default and content if requested.

GET /api/v1/context-packs/{id}?includeContent=true

15. Document APIs

15.1 List Documents

GET /api/v1/documents?repositoryId=order-service&docType=module_doc&state=active

15.2 Get Document

GET /api/v1/documents/{documentId}

15.3 Generate Document Draft

POST /api/v1/document-drafts

Request:

{
  "docType": "module_doc",
  "target": {
    "repositoryId": "order-service",
    "type": "module",
    "path": "src/main/java/com/acme/order/validation"
  },
  "source": {
    "commitSha": "6f41ab2"
  },
  "contextPackId": "ctx_01J",
  "options": {
    "outputFormat": "mdx",
    "requireCitations": true,
    "includeMermaid": true
  }
}

Response:

{
  "data": {
    "generationRunId": "docgenrun_01J",
    "documentId": "doc_01J",
    "state": "generated_draft",
    "qualityReportId": "qr_01J",
    "reviewRequired": true
  }
}

15.4 Evaluate Document Quality

POST /api/v1/documents/{documentId}/quality-evaluations

15.5 Create Review Request

POST /api/v1/documents/{documentId}/review-requests

15.6 Publish Document

POST /api/v1/documents/{documentId}/publish

Should require permission and possibly approval state.

16. Memory APIs

16.1 Search/Retrieve Memory

POST /api/v1/memory/search

Request:

{
  "target": {
    "type": "module",
    "repositoryId": "order-service",
    "path": "src/main/java/com/acme/order/validation"
  },
  "taskType": "code_change",
  "maxRecords": 10
}

Response:

{
  "data": {
    "records": [
      {
        "memoryId": "mem_rule_registry",
        "type": "repo_convention",
        "statement": "Validation rules are registered through RuleRegistry.",
        "state": "active",
        "confidence": 0.84,
        "evidence": []
      }
    ]
  }
}

16.2 Create Memory Candidate

POST /api/v1/memory-candidates

Request:

{
  "type": "repo_convention",
  "statement": "Validation rules should be added through RuleRegistry.",
  "scope": {
    "repositoryId": "order-service",
    "modulePath": "src/main/java/com/acme/order/validation"
  },
  "evidenceIds": ["E1", "E2"],
  "reason": "Observed during module documentation generation."
}

Response:

{
  "data": {
    "candidateId": "memcand_01J",
    "state": "candidate",
    "reviewRequired": true
  }
}

16.3 Review Memory Candidate

POST /api/v1/memory-candidates/{candidateId}/review

Request:

{
  "decision": "approve",
  "comment": "Correct and useful."
}

16.4 Revalidate Memory

POST /api/v1/memory-records/{memoryId}/revalidate

17. Job APIs

17.1 Get Job

GET /api/v1/jobs/{jobId}

Response:

{
  "data": {
    "jobId": "job_01J",
    "jobType": "parse_file",
    "status": "running",
    "attempts": 1,
    "progress": {
      "current": 320,
      "total": 1000,
      "unit": "files"
    }
  }
}

17.2 Cancel Job

POST /api/v1/jobs/{jobId}/cancel

17.3 Retry Job

POST /api/v1/jobs/{jobId}/retry

Should be restricted.

17.4 List Jobs

GET /api/v1/jobs?repositoryId=order-service&status=failed

18. Workflow APIs

18.1 Start Workflow

POST /api/v1/workflow-runs

Request:

{
  "workflowName": "generate_module_documentation",
  "input": {
    "repositoryId": "order-service",
    "modulePath": "src/main/java/com/acme/order/validation",
    "commitSha": "6f41ab2"
  }
}

Response:

{
  "data": {
    "workflowRunId": "wf_01J",
    "status": "running"
  }
}

18.2 Get Workflow Run

GET /api/v1/workflow-runs/{workflowRunId}

Response includes steps, artifacts, warnings.

18.3 Workflow Events

Optional streaming endpoint:

GET /api/v1/workflow-runs/{workflowRunId}/events

19. Audit APIs

19.1 Query Audit Events

GET /api/v1/audit-events?targetType=document&targetId=doc_01J

19.2 Restrictions

Audit APIs should be admin/security restricted.

19.3 Safe Response

Do not include raw sensitive payload unless explicitly allowed.

20. Health and Admin APIs

20.1 Platform Health

GET /api/v1/health

20.2 Index Health

GET /api/v1/repositories/{repositoryId}/index-health

20.3 Docs Health

GET /api/v1/repositories/{repositoryId}/docs-health

20.4 Memory Health

GET /api/v1/repositories/{repositoryId}/memory-health

20.5 Processor Versions

GET /api/v1/admin/processor-versions

Admin only.

21. OpenAPI Contract Structure

21.1 Recommended Files

openapi/
  platform-api.yaml
  components/
    schemas.yaml
    parameters.yaml
    responses.yaml
    errors.yaml
    security.yaml

21.2 Tags

Use tags:

tags:
  - Repositories
  - Snapshots
  - Search
  - Graph
  - ContextPacks
  - Documents
  - Memory
  - Jobs
  - Workflows
  - Audit
  - Admin

21.3 Common Components

components:
  schemas:
    ErrorResponse:
    Warning:
    EvidenceRef:
    Scope:
    Pagination:
    JobStatus:
    QualityReport:

22. OpenAPI Schema Example

22.1 EvidenceRef Schema

EvidenceRef:
  type: object
  required:
    - evidenceId
    - type
  properties:
    evidenceId:
      type: string
    type:
      type: string
      enum:
        - file_span
        - document_span
        - graph_edge
        - graph_path
        - schema_pointer
        - memory
    repositoryId:
      type: string
    commitSha:
      type: string
    path:
      type: string
    lines:
      type: array
      minItems: 2
      maxItems: 2
      items:
        type: integer

22.2 Warning Schema

Warning:
  type: object
  required:
    - code
    - message
  properties:
    code:
      type: string
    message:
      type: string
    details:
      type: object
      additionalProperties: true

22.3 Error Schema

ErrorResponse:
  type: object
  required:
    - status
    - error
  properties:
    status:
      type: string
      enum: [error]
    error:
      $ref: '#/components/schemas/Error'

23. API Versioning

23.1 Path Versioning

/api/v1/...

Simple and explicit.

23.2 Schema Versioning

Resources may include schema version:

{
  "schemaVersion": "context-pack.v1"
}

23.3 Deprecation

OpenAPI can mark deprecated operations.

Response warning:

{
  "code": "deprecated_endpoint",
  "message": "This endpoint will be removed after 2027-01-01."
}

23.4 Breaking Changes

Require new version for:

renamed fields,
changed semantics,
removed enum values,
changed error behavior.

24. Agent-Friendly API Design

AI agents need structured, small, explainable responses.

24.1 Agent-Friendly Features

explicit artifact IDs,
resource URIs,
evidence refs,
warnings,
confidence,
next suggested action,
bounded result size.

24.2 Example

{
  "data": {
    "results": [],
    "nextActions": [
      {
        "action": "get_file_span",
        "reason": "Read the primary source evidence before drafting."
      }
    ]
  }
}

24.3 Avoid

huge unstructured blobs,
hidden side effects,
ambiguous errors,
implicit global scope,
returning stale docs without warning.

25. CI/CD API Usage

25.1 PR Documentation Check

POST /api/v1/graph/impact

Then:

POST /api/v1/documents/stale-checks

25.2 CI Response

{
  "data": {
    "status": "warn",
    "findings": [
      {
        "type": "doc_stale_risk",
        "path": "docs/order-validation.md",
        "reason": "OrderValidator.java changed"
      }
    ]
  }
}

25.3 Blocking Policy

CI should block only configured severe findings.

26. API Security Checklist

26.1 Input

schema validation,
length limits,
enum restrictions,
path traversal protection,
id format validation,
no raw SQL/unsafe query.

26.2 AuthZ

repository access,
artifact access,
action permission,
admin scope,
tenant isolation.

26.3 Output

permission-filtered results,
redacted content,
no hidden repo metadata leaks,
sensitivity labels,
untrusted content markers.

26.4 Rate Limits

per user,
per tenant,
per endpoint group,
special limits for generation/embedding.

27. API Observability

27.1 Metrics

request count,
latency,
error rate,
status code,
endpoint,
tenant,
rate limited count,
authz denied count.

27.2 Tracing

Propagate:

X-Request-Id
X-Correlation-Id
Workflow-Run-Id
Retrieval-Run-Id

27.3 Logging

Structured safe logs.

Do not log raw code/doc content by default.

28. Contract Testing

28.1 OpenAPI Validation

Validate:

spec syntax,
examples,
schema refs,
response shapes.

28.2 Provider Tests

Implementation response matches OpenAPI.

28.3 Consumer Tests

MCP server/CLI/UI generated clients compile and pass.

28.4 Backward Compatibility

Detect breaking changes in CI.

29. API Anti-Patterns

29.1 One Endpoint to Rule Them All

POST /api/run

Hard to type, secure, document, and evolve.

29.2 No Async Jobs

Long requests timeout.

29.3 No Evidence in Response

Knowledge becomes ungrounded.

29.4 Returning Unauthorized Metadata

Security leak.

29.5 Unbounded Search Results

Bad for performance and agents.

29.6 No Error Codes

Clients cannot recover.

29.7 No Versioning

Clients break unexpectedly.

29.8 OpenAPI After Implementation

Contract drifts from real behavior.

30. Practical Exercise

Design OpenAPI contract for core platform APIs.

30.1 Output

Create:

openapi/platform-api.yaml
openapi/components/schemas.yaml
api-design.md
error-catalog.yaml
pagination.md
idempotency.md
authz-rules.md
contract-tests.yaml

30.2 Required Endpoints

Include:

POST /repositories
POST /repositories/{id}/scans
GET /repository-snapshots/{id}
POST /search
POST /graph/neighborhood
POST /graph/impact
POST /context-packs
POST /document-drafts
POST /documents/{id}/quality-evaluations
POST /memory-candidates
GET /jobs/{id}
POST /workflow-runs

30.3 Acceptance Criteria

endpoints are versioned,
request/response schemas defined,
errors standardized,
pagination defined,
async operations return job/run IDs,
evidence refs included,
permission behavior documented,
OpenAPI examples provided,
contract tests defined.

31. Summary

API design and OpenAPI contracts make the platform usable and stable for humans, agents, and internal systems.

Key points:

API is a product contract,
heavy operations should be asynchronous,
scope and source version must be explicit,
knowledge responses should include evidence and warnings,
permission filtering must happen before output,
errors must be machine-readable,
pagination and limits are mandatory,
idempotency is required for create/generation operations,
OpenAPI-first improves implementation and client reliability,
agent-friendly APIs are structured, bounded, explainable, and safe.

Part berikutnya starts the Safety, Security, and Governance phase with Security Threat Model: how to reason about data leakage, prompt injection, tool misuse, supply-chain risk, multi-tenant isolation, secrets, and AI-specific abuse paths.

Lesson Recap

You just completed lesson 28 in deepen practice. Use the series map if you want to review the broader track, or continue directly into the next lesson while the context is still warm.

Back To Series Next Lesson

Continue The Track

Keep the momentum while the lesson is still fresh. Move backward for review or continue forward into the next concept.

Previous Lesson

Lesson 27

Learn Ai Code Documentation Agent Memory Part 027 Indexing Workers And Jobs

Next Lesson

Lesson 29

Learn Ai Code Documentation Agent Memory Part 029 Security Threat Model