openapi: 3.0.3
info:
  title: AITBC Ecosystem Registry API
  description: Public registry API for certified AITBC partners, SDKs, and integrations
  version: 1.0.0
  contact:
    name: AITBC Ecosystem Team
    email: ecosystem@aitbc.io
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://registry.aitbc.io/api/v1
    description: Production server
  - url: https://staging-registry.aitbc.io/api/v1
    description: Staging server

paths:
  /partners:
    get:
      summary: List certified partners
      description: Retrieve a paginated list of all certified partners
      tags:
        - Partners
      parameters:
        - name: level
          in: query
          schema:
            type: string
            enum: [bronze, silver, gold]
          description: Filter by certification level
        - name: language
          in: query
          schema:
            type: string
          description: Filter by SDK language
        - name: category
          in: query
          schema:
            type: string
            enum: [payment, erp, analytics, infrastructure]
          description: Filter by partner category
        - name: status
          in: query
          schema:
            type: string
            enum: [active, suspended, expired]
          description: Filter by certification status
        - name: page
          in: query
          schema:
            type: integer
            default: 1
          description: Page number
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
          description: Items per page
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  partners:
                    type: array
                    items:
                      $ref: '#/components/schemas/PartnerSummary'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  filters:
                    type: object
                    description: Applied filters

  /partners/{partnerId}:
    get:
      summary: Get partner details
      description: Retrieve detailed information about a certified partner
      tags:
        - Partners
      parameters:
        - name: partnerId
          in: path
          required: true
          schema:
            type: string
          description: Unique partner identifier
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerDetail'
        '404':
          $ref: '#/components/responses/NotFound'

  /partners/{partnerId}/certification:
    get:
      summary: Get certification details
      description: Retrieve certification information for a partner
      tags:
        - Certification
      parameters:
        - name: partnerId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Certification'
        '404':
          $ref: '#/components/responses/NotFound'

  /partners/{partnerId}/verify:
    get:
      summary: Verify certification
      description: Verify if a partner's certification is valid
      tags:
        - Certification
      parameters:
        - name: partnerId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Verification result
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid:
                    type: boolean
                  level:
                    type: string
                    enum: [bronze, silver, gold]
                  expires_at:
                    type: string
                    format: date-time
                  verification_id:
                    type: string

  /sdks:
    get:
      summary: List certified SDKs
      description: Retrieve a list of all certified SDKs
      tags:
        - SDKs
      parameters:
        - name: language
          in: query
          schema:
            type: string
            enum: [python, java, javascript, typescript, go, rust]
          description: Filter by programming language
        - name: version
          in: query
          schema:
            type: string
          description: Filter by SDK version
        - name: level
          in: query
          schema:
            type: string
            enum: [bronze, silver, gold]
          description: Filter by certification level
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  sdks:
                    type: array
                    items:
                      $ref: '#/components/schemas/SDKSummary'

  /sdks/{sdkId}:
    get:
      summary: Get SDK details
      description: Retrieve detailed information about a certified SDK
      tags:
        - SDKs
      parameters:
        - name: sdkId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SDKDetail'

  /search:
    get:
      summary: Search registry
      description: Search for partners, SDKs, and integrations
      tags:
        - Search
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
          description: Search query
        - name: type
          in: query
          schema:
            type: string
            enum: [partner, sdk, integration, all]
            default: all
          description: Search target type
        - name: level
          in: query
          schema:
            type: string
            enum: [bronze, silver, gold]
          description: Filter by certification level
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/SearchResult'
                  total:
                    type: integer
                  query:
                    type: string

  /stats:
    get:
      summary: Registry statistics
      description: Get overall registry statistics
      tags:
        - Statistics
      responses:
        '200':
          description: Statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistryStats'

  /badges/{partnerId}/{level}.svg:
    get:
      summary: Get certification badge
      description: Retrieve SVG badge for certified partner
      tags:
        - Badges
      parameters:
        - name: partnerId
          in: path
          required: true
          schema:
            type: string
        - name: level
          in: path
          required: true
          schema:
            type: string
            enum: [bronze, silver, gold]
      responses:
        '200':
          description: SVG badge
          content:
            image/svg+xml:
              schema:
                type: string

components:
  schemas:
    PartnerSummary:
      type: object
      properties:
        id:
          type: string
          description: Unique partner identifier
        name:
          type: string
          description: Partner company name
        logo_url:
          type: string
          description: URL to partner logo
        description:
          type: string
          description: Brief partner description
        website:
          type: string
          format: uri
          description: Partner website URL
        certification_level:
          type: string
          enum: [bronze, silver, gold]
          description: Current certification level
        category:
          type: string
          enum: [payment, erp, analytics, infrastructure]
          description: Partner category
        languages:
          type: array
          items:
            type: string
          description: Supported programming languages
        certified_at:
          type: string
          format: date-time
          description: Certification date
        expires_at:
          type: string
          format: date-time
          description: Certification expiration date

    PartnerDetail:
      allOf:
        - $ref: '#/components/schemas/PartnerSummary'
        - type: object
          properties:
        contact_email:
          type: string
          format: email
          description: Contact email
        support_url:
          type: string
          format: uri
          description: Support documentation URL
        documentation_url:
          type: string
          format: uri
          description: API documentation URL
        github_url:
          type: string
          format: uri
          description: GitHub repository URL
        integration_count:
          type: integer
          description: Number of certified integrations
        test_results:
          type: object
          properties:
            api_compliance:
              type: object
              properties:
                score:
                  type: number
                  minimum: 0
                  maximum: 100
                tests_run:
                  type: integer
                tests_passed:
                  type: integer
            security:
              type: object
              properties:
                score:
                  type: number
                  minimum: 0
                  maximum: 100
                vulnerabilities_found:
                  type: integer
                critical_issues:
                  type: integer
            performance:
              type: object
              properties:
                avg_response_time:
                  type: number
                throughput:
                  type: number
                uptime:
                  type: number

    Certification:
      type: object
      properties:
        id:
          type: string
          description: Certification ID
        partner_id:
          type: string
          description: Partner ID
        level:
          type: string
          enum: [bronze, silver, gold]
          description: Certification level
        status:
          type: string
          enum: [active, suspended, expired]
          description: Certification status
        issued_at:
          type: string
          format: date-time
          description: Issue date
        expires_at:
          type: string
          format: date-time
          description: Expiration date
        test_results:
          type: object
          description: Test suite results
        security_report:
          type: object
          description: Security validation report
        criteria_met:
          type: array
          items:
            type: string
          description: List of certification criteria met

    SDKSummary:
      type: object
      properties:
        id:
          type: string
          description: SDK identifier
        name:
          type: string
          description: SDK name
        language:
          type: string
          description: Programming language
        version:
          type: string
          description: Latest version
        partner_id:
          type: string
          description: Partner ID
        partner_name:
          type: string
          description: Partner name
        certification_level:
          type: string
          enum: [bronze, silver, gold]
        download_url:
          type: string
          format: uri
          description: Download URL
        documentation_url:
          type: string
          format: uri
          description: Documentation URL
        certified_at:
          type: string
          format: date-time

    SDKDetail:
      allOf:
        - $ref: '#/components/schemas/SDKSummary'
        - type: object
          properties:
            description:
              type: string
              description: SDK description
            repository_url:
              type: string
              format: uri
              description: Source repository URL
            package_name:
              type: string
              description: Package name (pip, npm, maven)
            dependencies:
              type: array
              items:
                type: string
              description: Key dependencies
            supported_versions:
              type: array
              items:
                type: string
              description: Supported AITBC API versions
            installation_command:
              type: string
              description: Installation command
            quick_start:
              type: string
              description: Quick start code snippet

    SearchResult:
      type: object
      properties:
        type:
          type: string
          enum: [partner, sdk, integration]
          description: Result type
        id:
          type: string
          description: Item ID
        name:
          type: string
          description: Item name
        description:
          type: string
          description: Item description
        certification_level:
          type: string
          enum: [bronze, silver, gold]
        url:
          type: string
          format: uri
          description: Item URL
        relevance_score:
          type: number
          description: Search relevance score

    Pagination:
      type: object
      properties:
        page:
          type: integer
          description: Current page
        limit:
          type: integer
          description: Items per page
        total:
          type: integer
          description: Total items
        pages:
          type: integer
          description: Total pages
        has_next:
          type: boolean
          description: Has next page
        has_prev:
          type: boolean
          description: Has previous page

    RegistryStats:
      type: object
      properties:
        total_partners:
          type: integer
          description: Total certified partners
        total_sdks:
          type: integer
          description: Total certified SDKs
        certification_breakdown:
          type: object
          properties:
            bronze:
              type: integer
            silver:
              type: integer
            gold:
              type: integer
        language_breakdown:
          type: object
          additionalProperties:
            type: integer
          description: Number of SDKs per language
        category_breakdown:
          type: object
          additionalProperties:
            type: integer
          description: Number of partners per category
        last_updated:
          type: string
          format: date-time
          description: Last update timestamp

  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              message:
                type: string

    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              message:
                type: string
              details:
                type: object

  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authenticated endpoints

security:
  - ApiKeyAuth: []

tags:
  - name: Partners
    description: Partner management and lookup
  - name: SDKs
    description: SDK information and downloads
  - name: Certification
    description: Certification verification and details
  - name: Search
    description: Registry search functionality
  - name: Statistics
    description: Registry statistics and metrics
  - name: Badges
    description: Certification badges