APIs.io Compare Keyword Coverage

arazzo: 1.0.1
info:
  title: APIs.io Compare Keyword Coverage
  summary: Run two keyword searches against APIs.io and compare how many APIs the index holds for each term.
  description: >-
    A landscape-sizing flow for the APIs.io registry. The workflow searches the
    index for a primary keyword and an alternate keyword, captures the total
    page count and top match for each, and branches on which term has broader
    coverage in the index. This is useful for deciding which topic or category
    is better represented before drilling into individual APIs. Each search
    inlines its full request, including the required API key header, so the
    comparison is self-describing.
  version: 1.0.0
sourceDescriptions:
- name: searchApi
  url: ../openapi/apis-io-search-api-openapi.yml
  type: openapi
workflows:
- workflowId: compare-keyword-coverage
  summary: Compare APIs.io index coverage between two keywords by total page count.
  description: >-
    Searches the APIs.io index for a primary and an alternate keyword, reads the
    total page count for each, and branches on which keyword returns more pages
    of results.
  inputs:
    type: object
    required:
    - primaryKeyword
    - alternateKeyword
    - apiKey
    properties:
      primaryKeyword:
        type: string
        description: The first keyword to size coverage for.
      alternateKeyword:
        type: string
        description: The second keyword to compare against the first.
      limit:
        type: string
        description: The number of results to return per page.
        default: "50"
      apiKey:
        type: string
        description: The APIs.io API key sent in the x-api-key header.
  steps:
  - stepId: searchPrimary
    description: >-
      Search the index for the primary keyword and read the total page count and
      top match.
    operationId: search
    parameters:
    - name: x-api-key
      in: header
      value: $inputs.apiKey
    - name: search
      in: query
      value: $inputs.primaryKeyword
    - name: limit
      in: query
      value: $inputs.limit
    - name: page
      in: query
      value: "0"
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      primaryTotalPages: $response.body#/meta/totalPages
      primaryTopApi: $response.body#/data/0/name
      primaryResults: $response.body#/data
  - stepId: searchAlternate
    description: >-
      Search the index for the alternate keyword and read its total page count
      and top match, then branch on which keyword has broader coverage.
    operationId: search
    parameters:
    - name: x-api-key
      in: header
      value: $inputs.apiKey
    - name: search
      in: query
      value: $inputs.alternateKeyword
    - name: limit
      in: query
      value: $inputs.limit
    - name: page
      in: query
      value: "0"
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      alternateTotalPages: $response.body#/meta/totalPages
      alternateTopApi: $response.body#/data/0/name
      alternateResults: $response.body#/data
    onSuccess:
    - name: primaryBroader
      type: end
      criteria:
      - condition: $steps.searchPrimary.outputs.primaryTotalPages >= $response.body#/meta/totalPages
    - name: alternateBroader
      type: end
      criteria:
      - condition: $steps.searchPrimary.outputs.primaryTotalPages < $response.body#/meta/totalPages
  outputs:
    primaryTotalPages: $steps.searchPrimary.outputs.primaryTotalPages
    primaryTopApi: $steps.searchPrimary.outputs.primaryTopApi
    alternateTotalPages: $steps.searchAlternate.outputs.alternateTotalPages
    alternateTopApi: $steps.searchAlternate.outputs.alternateTopApi