Numbers API — Date

naftiko: "1.0.0-alpha2"

info:
  label: "Numbers API — Date"
  description: >-
    Numbers API — Date. 2 operations. Lead operation: return a historical fact
    about a specific day of year (`/{month}/{day}/date`), or pull a random
    date fact (`/random/date`). Self-contained Naftiko capability covering one
    Numbers API business surface.
  tags:
    - Numbers API
    - Date
    - Calendar
  created: "2026-05-30"
  modified: "2026-05-30"

binds: []

capability:

  consumes:
    - type: http
      namespace: "numbers-date"
      baseUri: "http://numbersapi.com"
      description: "Numbers API — Date business capability. Self-contained, no shared references."
      resources:
        - name: "month-day-date"
          path: "/{month}/{day}/date"
          operations:
            - name: "getDateFact"
              method: GET
              description: "Return a historical fact about a specific day of year."
              inputParameters:
                - name: "month"
                  in: path
                  type: integer
                  required: true
                  description: "Month number, 1-12."
                - name: "day"
                  in: path
                  type: integer
                  required: true
                  description: "Day-of-month number, 1-31."
                - 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: "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-date"
          path: "/random/date"
          operations:
            - name: "getRandomDateFact"
              method: GET
              description: "Return a random date fact (a fact tied to a day of year)."
              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: "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-date-rest"
      port: 8080
      description: "REST adapter for Numbers API — Date. One Spectral-compliant resource per consumed operation, prefixed with /v1."
      resources:
        - path: "/v1/numbers/dates/{month}/{day}"
          name: "month-day-date"
          description: "REST surface for day-of-year facts."
          operations:
            - method: GET
              name: "getDateFact"
              description: "Return a historical fact about a specific day of year."
              call: "numbers-date.getDateFact"
              with:
                month: "rest.month"
                day: "rest.day"
                json: "rest.json"
                fragment: "rest.fragment"
                notfound: "rest.notfound"
                default: "rest.default"
                callback: "rest.callback"
                write: "rest.write"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: "/v1/numbers/dates/random"
          name: "random-date"
          description: "REST surface for random date facts."
          operations:
            - method: GET
              name: "getRandomDateFact"
              description: "Return a random date fact."
              call: "numbers-date.getRandomDateFact"
              with:
                json: "rest.json"
                fragment: "rest.fragment"
                notfound: "rest.notfound"
                default: "rest.default"
                callback: "rest.callback"
                write: "rest.write"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      namespace: "numbers-date-mcp"
      port: 9090
      transport: http
      description: "MCP adapter for Numbers API — Date. One tool per consumed operation, routed inline through this capability's consumes block."
      tools:
        - name: "get-date-fact"
          description: "Return a historical fact about a specific day of year."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "numbers-date.getDateFact"
          with:
            month: "tools.month"
            day: "tools.day"
            json: "tools.json"
            fragment: "tools.fragment"
            notfound: "tools.notfound"
            default: "tools.default"
            callback: "tools.callback"
            write: "tools.write"
          outputParameters:
            - type: object
              mapping: "$."
        - name: "get-random-date-fact"
          description: "Return a random date fact."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "numbers-date.getRandomDateFact"
          with:
            json: "tools.json"
            fragment: "tools.fragment"
            notfound: "tools.notfound"
            default: "tools.default"
            callback: "tools.callback"
            write: "tools.write"
          outputParameters:
            - type: object
              mapping: "$."