Sideko API Tooling Lifecycle

naftiko: "1.0.0-alpha1"

info:
  label: "Sideko API Tooling Lifecycle"
  description: >-
    Unified workflow capability for managing the complete API tooling lifecycle
    on the Sideko platform. Enables API platform teams to programmatically
    manage API projects, upload specifications, generate multi-language SDKs,
    deploy documentation sites, and run mock servers — all through a single
    unified interface. Designed for API platform engineers and DevOps teams
    automating their API developer experience pipeline.
  tags:
    - API Tooling
    - SDK Generation
    - Documentation
    - Mock Servers
    - Platform
    - Developer Experience
  created: "2026-05-02"
  modified: "2026-05-02"

binds:
  - namespace: env
    keys:
      SIDEKO_API_KEY: SIDEKO_API_KEY

capability:
  consumes:
    - import: sideko
      location: ./shared/sideko-api.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: sideko-tooling-api
      description: "Unified REST API for managing the complete Sideko API tooling lifecycle."
      resources:
        - path: /v1/projects
          name: projects
          description: "API project management"
          operations:
            - method: GET
              name: list-projects
              description: "List all API projects"
              call: "sideko.list-api-projects"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-project
              description: "Create a new API project"
              call: "sideko.create-api-project"
              with:
                name: "rest.name"
                description: "rest.description"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/projects/{projectId}
          name: project
          description: "Single API project operations"
          operations:
            - method: GET
              name: get-project
              description: "Get an API project by ID"
              call: "sideko.get-api-project"
              with:
                projectId: "rest.projectId"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: PUT
              name: update-project
              description: "Update an API project"
              call: "sideko.update-api-project"
              with:
                projectId: "rest.projectId"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: DELETE
              name: delete-project
              description: "Delete an API project"
              call: "sideko.delete-api-project"
              with:
                projectId: "rest.projectId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/projects/{projectId}/versions
          name: versions
          description: "API version management"
          operations:
            - method: GET
              name: list-versions
              description: "List API versions"
              call: "sideko.list-api-versions"
              with:
                projectId: "rest.projectId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/projects/{projectId}/sdks
          name: sdks
          description: "SDK generation jobs"
          operations:
            - method: GET
              name: list-sdks
              description: "List SDK generation jobs"
              call: "sideko.list-sdk-generations"
              with:
                projectId: "rest.projectId"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: generate-sdk
              description: "Trigger SDK generation"
              call: "sideko.trigger-sdk-generation"
              with:
                projectId: "rest.projectId"
                language: "rest.language"
                versionId: "rest.versionId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/projects/{projectId}/docs
          name: documentation
          description: "Documentation sites"
          operations:
            - method: GET
              name: list-docs
              description: "List documentation sites"
              call: "sideko.list-documentation-sites"
              with:
                projectId: "rest.projectId"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: deploy-docs
              description: "Deploy a documentation site"
              call: "sideko.deploy-documentation-site"
              with:
                projectId: "rest.projectId"
                versionId: "rest.versionId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/projects/{projectId}/mock-servers
          name: mock-servers
          description: "Mock server management"
          operations:
            - method: GET
              name: list-mock-servers
              description: "List mock servers"
              call: "sideko.list-mock-servers"
              with:
                projectId: "rest.projectId"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: deploy-mock-server
              description: "Deploy a mock server"
              call: "sideko.deploy-mock-server"
              with:
                projectId: "rest.projectId"
                versionId: "rest.versionId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/api-keys
          name: api-keys
          description: "API key management"
          operations:
            - method: GET
              name: list-api-keys
              description: "List API keys"
              call: "sideko.list-api-keys"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-api-key
              description: "Create a new API key"
              call: "sideko.create-api-key"
              with:
                name: "rest.name"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: sideko-tooling-mcp
      transport: http
      description: "MCP server for AI-assisted API tooling lifecycle management on the Sideko platform."
      tools:
        - name: list-api-projects
          description: "List all API projects in the Sideko organization"
          hints:
            readOnly: true
            openWorld: false
          call: "sideko.list-api-projects"
          outputParameters:
            - type: object
              mapping: "$."

        - name: create-api-project
          description: "Create a new API project in Sideko"
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: "sideko.create-api-project"
          with:
            name: "tools.name"
            description: "tools.description"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-api-project
          description: "Get details of a specific API project"
          hints:
            readOnly: true
            openWorld: false
          call: "sideko.get-api-project"
          with:
            projectId: "tools.projectId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: update-api-project
          description: "Update an existing API project name or description"
          hints:
            readOnly: false
            destructive: false
            idempotent: true
          call: "sideko.update-api-project"
          with:
            projectId: "tools.projectId"
            name: "tools.name"
            description: "tools.description"
          outputParameters:
            - type: object
              mapping: "$."

        - name: delete-api-project
          description: "Delete an API project and all its versions, SDKs, docs, and mock servers"
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: "sideko.delete-api-project"
          with:
            projectId: "tools.projectId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-api-versions
          description: "List all versions of an API project"
          hints:
            readOnly: true
            openWorld: false
          call: "sideko.list-api-versions"
          with:
            projectId: "tools.projectId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-sdk-generations
          description: "List SDK generation jobs for an API project"
          hints:
            readOnly: true
            openWorld: false
          call: "sideko.list-sdk-generations"
          with:
            projectId: "tools.projectId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: trigger-sdk-generation
          description: "Trigger SDK generation for a language (python, typescript, java, go, ruby, rust)"
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: "sideko.trigger-sdk-generation"
          with:
            projectId: "tools.projectId"
            language: "tools.language"
            versionId: "tools.versionId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-documentation-sites
          description: "List documentation sites deployed for an API project"
          hints:
            readOnly: true
            openWorld: false
          call: "sideko.list-documentation-sites"
          with:
            projectId: "tools.projectId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: deploy-documentation-site
          description: "Deploy or update an API documentation site for an API project version"
          hints:
            readOnly: false
            destructive: false
            idempotent: true
          call: "sideko.deploy-documentation-site"
          with:
            projectId: "tools.projectId"
            versionId: "tools.versionId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-mock-servers
          description: "List mock server instances for an API project"
          hints:
            readOnly: true
            openWorld: false
          call: "sideko.list-mock-servers"
          with:
            projectId: "tools.projectId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: deploy-mock-server
          description: "Deploy a mock server that simulates API responses for an API project version"
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: "sideko.deploy-mock-server"
          with:
            projectId: "tools.projectId"
            versionId: "tools.versionId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-api-keys
          description: "List all API keys for the Sideko organization"
          hints:
            readOnly: true
            openWorld: false
          call: "sideko.list-api-keys"
          outputParameters:
            - type: object
              mapping: "$."

        - name: create-api-key
          description: "Create a new Sideko API key"
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: "sideko.create-api-key"
          with:
            name: "tools.name"
          outputParameters:
            - type: object
              mapping: "$."