Numbers API — Trivia

naftiko: "1.0.0-alpha2"

info:
  label: "Numbers API — Trivia"
  description: >-
    Numbers API — Trivia. 3 operations. Lead operation: return a trivia fact
    about a supplied integer (`/{number}` and `/{number}/trivia`), or pull a
    random trivia fact from the catalog (`/random/trivia`). Self-contained
    Naftiko capability covering one Numbers API business surface.
  tags:
    - Numbers API
    - Trivia
    - Numbers
  created: "2026-05-30"
  modified: "2026-05-30"

binds: []

capability:

  consumes:
    - type: http
      namespace: "numbers-trivia"
      baseUri: "http://numbersapi.com"
      description: "Numbers API — Trivia business capability. Self-contained, no shared references."
      resources:
        - name: "number-trivia-default"
          path: "/{number}"
          operations:
            - name: "getTrivia"
              method: GET
              description: "Return a trivia fact about a supplied integer (default endpoint)."
              inputParameters:
                - name: "number"
                  in: path
                  type: string
                  required: true
                  description: "Integer to look up, or the keyword `random`."
                - name: "json"
                  in: query
                  type: boolean
                  required: false
                  description: "Return the fact as a JSON object instead of plain text."
                - name: "fragment"
                  in: query
                  type: boolean
                  required: false
                  description: "Return as a sentence fragment (lowercase, no terminal punctuation)."
                - name: "notfound"
                  in: query
                  type: string
                  required: false
                  description: "Behavior when no fact exists: default, floor, or ceil."
                - name: "default"
                  in: query
                  type: string
                  required: false
                  description: "Custom message when no fact exists."
                - name: "min"
                  in: query
                  type: integer
                  required: false
                  description: "Minimum value for random-number selection."
                - name: "max"
                  in: query
                  type: integer
                  required: false
                  description: "Maximum value for random-number selection."
                - name: "callback"
                  in: query
                  type: string
                  required: false
                  description: "JSONP callback function name."
                - name: "write"
                  in: query
                  type: boolean
                  required: false
                  description: "Wrap the response in document.write()."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "number-trivia"
          path: "/{number}/trivia"
          operations:
            - name: "getTriviaFact"
              method: GET
              description: "Return a trivia fact about a supplied integer (explicit trivia type)."
              inputParameters:
                - name: "number"
                  in: path
                  type: string
                  required: true
                  description: "Integer to look up, or the keyword `random`."
                - name: "json"
                  in: query
                  type: boolean
                  required: false
                  description: "Return the fact as a JSON object."
                - name: "fragment"
                  in: query
                  type: boolean
                  required: false
                  description: "Return as a sentence fragment."
                - name: "notfound"
                  in: query
                  type: string
                  required: false
                  description: "Not-found behavior."
                - name: "default"
                  in: query
                  type: string
                  required: false
                  description: "Custom default message."
                - name: "min"
                  in: query
                  type: integer
                  required: false
                  description: "Random min."
                - name: "max"
                  in: query
                  type: integer
                  required: false
                  description: "Random max."
                - name: "callback"
                  in: query
                  type: string
                  required: false
                  description: "JSONP callback."
                - name: "write"
                  in: query
                  type: boolean
                  required: false
                  description: "Wrap response in document.write()."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "random-trivia"
          path: "/random/trivia"
          operations:
            - name: "getRandomTriviaFact"
              method: GET
              description: "Return a random trivia fact."
              inputParameters:
                - name: "json"
                  in: query
                  type: boolean
                  required: false
                  description: "Return the fact as a JSON object."
                - name: "fragment"
                  in: query
                  type: boolean
                  required: false
                  description: "Return as a sentence fragment."
                - name: "notfound"
                  in: query
                  type: string
                  required: false
                  description: "Not-found behavior."
                - name: "default"
                  in: query
                  type: string
                  required: false
                  description: "Custom default message."
                - name: "min"
                  in: query
                  type: integer
                  required: false
                  description: "Lower bound for random selection."
                - name: "max"
                  in: query
                  type: integer
                  required: false
                  description: "Upper bound for random selection."
                - name: "callback"
                  in: query
                  type: string
                  required: false
                  description: "JSONP callback."
                - name: "write"
                  in: query
                  type: boolean
                  required: false
                  description: "Wrap response in document.write()."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."

  exposes:
    - type: rest
      namespace: "numbers-trivia-rest"
      port: 8080
      description: "REST adapter for Numbers API — Trivia. One Spectral-compliant resource per consumed operation, prefixed with /v1."
      resources:
        - path: "/v1/numbers/{number}/trivia-default"
          name: "number-trivia-default"
          description: "REST surface for default trivia lookup."
          operations:
            - method: GET
              name: "getTrivia"
              description: "Return a trivia fact about a supplied integer (default endpoint)."
              call: "numbers-trivia.getTrivia"
              with:
                number: "rest.number"
                json: "rest.json"
                fragment: "rest.fragment"
                notfound: "rest.notfound"
                default: "rest.default"
                min: "rest.min"
                max: "rest.max"
                callback: "rest.callback"
                write: "rest.write"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: "/v1/numbers/{number}/trivia"
          name: "number-trivia"
          description: "REST surface for explicit trivia lookup."
          operations:
            - method: GET
              name: "getTriviaFact"
              description: "Return a trivia fact about a supplied integer."
              call: "numbers-trivia.getTriviaFact"
              with:
                number: "rest.number"
                json: "rest.json"
                fragment: "rest.fragment"
                notfound: "rest.notfound"
                default: "rest.default"
                min: "rest.min"
                max: "rest.max"
                callback: "rest.callback"
                write: "rest.write"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: "/v1/numbers/random/trivia"
          name: "random-trivia"
          description: "REST surface for random trivia."
          operations:
            - method: GET
              name: "getRandomTriviaFact"
              description: "Return a random trivia fact."
              call: "numbers-trivia.getRandomTriviaFact"
              with:
                json: "rest.json"
                fragment: "rest.fragment"
                notfound: "rest.notfound"
                default: "rest.default"
                min: "rest.min"
                max: "rest.max"
                callback: "rest.callback"
                write: "rest.write"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      namespace: "numbers-trivia-mcp"
      port: 9090
      transport: http
      description: "MCP adapter for Numbers API — Trivia. One tool per consumed operation, routed inline through this capability's consumes block."
      tools:
        - name: "get-trivia"
          description: "Return a trivia fact about a supplied integer (default endpoint)."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "numbers-trivia.getTrivia"
          with:
            number: "tools.number"
            json: "tools.json"
            fragment: "tools.fragment"
            notfound: "tools.notfound"
            default: "tools.default"
            min: "tools.min"
            max: "tools.max"
            callback: "tools.callback"
            write: "tools.write"
          outputParameters:
            - type: object
              mapping: "$."
        - name: "get-trivia-fact"
          description: "Return a trivia fact about a supplied integer."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "numbers-trivia.getTriviaFact"
          with:
            number: "tools.number"
            json: "tools.json"
            fragment: "tools.fragment"
            notfound: "tools.notfound"
            default: "tools.default"
            min: "tools.min"
            max: "tools.max"
            callback: "tools.callback"
            write: "tools.write"
          outputParameters:
            - type: object
              mapping: "$."
        - name: "get-random-trivia"
          description: "Return a random trivia fact."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "numbers-trivia.getRandomTriviaFact"
          with:
            json: "tools.json"
            fragment: "tools.fragment"
            notfound: "tools.notfound"
            default: "tools.default"
            min: "tools.min"
            max: "tools.max"
            callback: "tools.callback"
            write: "tools.write"
          outputParameters:
            - type: object
              mapping: "$."