Skip to content

Contributor Docs

OpenAPI And Parity

This project now vendors the published Adobe Target Admin API OpenAPI document at:

  • spec/openapi/admin-api.openapi.json

It is pulled from the Adobe docs source referenced by:

  • https://developer.adobe.com/target/page-data/administer/admin-api/page-data.json

The vendored OpenAPI document is the canonical API contract for:

  • endpoint inventory
  • parameters
  • request bodies
  • response bodies
  • reusable schemas
  • operation identifiers

Implementation and test coverage metadata now lives at:

  • spec/openapi/implementation_coverage.yaml

Validation Checks

Current validation layers are:

  • OpenAPI structural validation
  • repo-specific OpenAPI guardrails such as unique operationId values
  • code-to-implementation-metadata parity for implemented endpoints

Useful commands:

uv run python scripts/pull_openapi_spec.py --check
uv run python scripts/validate_openapi_spec.py
uv run python scripts/generate_openapi_models.py --check
uv run python scripts/generate_openapi_operations.py --check
uv run python scripts/validate_openapi_coverage.py
uv run python scripts/check_openapi_parity.py
uv run python scripts/openapi_summary.py

Generated Pydantic models derived from the OpenAPI schemas live at:

  • packages/sdk/src/adobe_target_admin/generated/models.py
  • packages/sdk/src/adobe_target_admin/generated/operations.py

The model-generation helper normalizes the vendored Adobe spec before invoking datamodel-code-generator, and the operation metadata generator uses the same normalized OpenAPI view. Generation and validation therefore run against the same corrected view of the upstream document.

Implementation Registry

Implemented OpenAPI operationIds are derived from decorated resource methods in:

  • packages/sdk/src/adobe_target_admin/operations.py

When a new endpoint is implemented:

  1. update the implementation metadata status
  2. decorate the resource method with the matching OpenAPI operationId
  3. add request/behavior tests

OpenAPI Sync

The repo syncs the upstream Adobe-published OpenAPI document with:

  • scripts/pull_openapi_spec.py
  • .github/workflows/openapi-sync.yml

CI also checks that the vendored OpenAPI file is current and valid.