Skip to main content

API Uploads: Zip Structure and OAS Basics

Import APIs into the portal by uploading a structured ZIP. This keeps metadata, docs, and OpenAPI specs together for each tenant.

API Uploads: Zip Structure and OAS Basics​

  • Download the sample ZIP, swap in your own OpenAPI/doc files, re-zip, and upload for a quick import.
  • Zip layout:
    • overview.json (required): API metadata (name, slug, version, summary, links) and pointers to spec/docs.
    • openapi.(json|yaml) (required): Valid OAS 3.x spec referenced by overview.json.
    • other files (optional): Markdown/HTML referenced by overview.json (e.g., overview.md, changelog.md). Refer sample below
  • Tips:
    • Keep slugs unique per tenant; ensure paths in overview.json match the zip.
    • Trim oversized examples in the spec; include servers for accurate base URLs.

Zip folder layout​

  • overview.json (required): Core metadata for the API (name, slug, version, summary, tags, pricing, links).
  • openapi.(json|yaml|yml) or spec.json/yaml: OpenAPI 3.x spec referenced by overview.json.
  • other files (optional): Markdown or HTML content referenced by overview.json (e.g., overview.md, changelog.md).
  • sdks/ (optional): SDK files or links if you include SDK metadata.

Example:

my-api.zip
└── my-api/
    ├── overview.json
    ├── petstore-openapi.yaml
    ├── overview.md
    ├── changelog.json
    ├── endpoints.json
    ├── pricing.json
    ├── versions.json
    ├── sdks.json
    ├── sdk-java.zip
    ├── sdk-python.zip

overview.json essentials​

  • name, slug, version
  • description/summary
  • openApiSpec: path to your spec file (e.g., openapi.yaml)
  • Optional: tags, category, pricing, sdks, endpoints, documentation paths

OpenAPI upload basics​

  • Provide a valid OAS 3.x document (openapi key) in JSON or YAML.
  • Include servers for accurate base URLs; keep paths minimal for faster imports.
  • If you reference external files, bundle them inside the zip (relative paths).

Upload tips​

  • Keep slugs unique per tenant.
  • Ensure file paths in overview.json match the zip structure.
  • Validate the OAS before upload; strip huge example payloads to reduce size.
  • Use tenant-specific tokens/headers when calling the upload endpoint.***

Sample bundle: what each file does​

  • overview.json (required): Root metadata (name, slug, version, summary, tags, category) plus pointers to docs, pricing, endpoints, and the OpenAPI spec.
  • overview.md: Long-form intro/overview page linked from overview.json.
  • petstore-openapi.yaml: The OpenAPI 3.x spec for your API; referenced by overview.json.openApiSpec.
  • endpoints.json: Optional structured endpoint list for cards/try-it sections; supplements the spec summary.
  • pricing.json: Optional pricing tiers (plans, quotas, features, CTA links) shown in pricing widgets.
  • changelog.json: Optional release history (version, date, notes) powering changelog views.
  • versions.json: Optional version selector data (labels, base URLs, docs links) if you support multiple live versions.
  • sdks.json: Optional SDK metadata (name, language, links, asset filenames).
  • sdk-java.zip, sdk-python.zip: Optional SDK artifacts referenced from sdks.json (e.g., downloadable client libraries).