JokeAPI — Metadata

naftiko: "1.0.0-alpha2"

info:
  label: "JokeAPI — Metadata"
  description: >-
    JokeAPI — Metadata. 5 operations. Lead operation: JokeAPI List Categories.
    Self-contained Naftiko capability covering one JokeAPI business surface —
    describing the API surface itself (categories, flags, formats, languages,
    and human-name-to-ISO-code resolution).
  tags:
    - JokeAPI
    - Metadata
    - Discovery
  created: "2026-05-29"
  modified: "2026-05-29"

binds: []

capability:

  # ── 1. Consumes — the upstream HTTP API this capability speaks to ─────
  consumes:
    - type: http
      namespace: "jokeapi-metadata"
      baseUri: "https://v2.jokeapi.dev"
      description: "JokeAPI v2 — Metadata business capability. Self-contained, no shared references. No authentication required."
      resources:
        - name: "categories"
          path: "/categories"
          operations:
            - name: "getCategories"
              method: GET
              description: "List every joke category JokeAPI exposes, plus recognised category aliases."
              inputParameters:
                - name: "format"
                  in: query
                  type: string
                  required: false
                  description: "Response format: json, xml, yaml, or txt."
                - name: "lang"
                  in: query
                  type: string
                  required: false
                  description: "ISO 639-1 system language code."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "flags"
          path: "/flags"
          operations:
            - name: "getFlags"
              method: GET
              description: "List the blacklist flags consumers can pass to `?blacklistFlags`."
              inputParameters:
                - name: "format"
                  in: query
                  type: string
                  required: false
                  description: "Response format: json, xml, yaml, or txt."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "formats"
          path: "/formats"
          operations:
            - name: "getFormats"
              method: GET
              description: "List the response formats JokeAPI can return."
              inputParameters:
                - name: "format"
                  in: query
                  type: string
                  required: false
                  description: "Response format: json, xml, yaml, or txt."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "languages"
          path: "/languages"
          operations:
            - name: "getLanguages"
              method: GET
              description: "List the joke languages and the system languages JokeAPI supports."
              inputParameters:
                - name: "format"
                  in: query
                  type: string
                  required: false
                  description: "Response format: json, xml, yaml, or txt."
                - name: "lang"
                  in: query
                  type: string
                  required: false
                  description: "ISO 639-1 system language code."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "langcode"
          path: "/langcode/{language}"
          operations:
            - name: "getLangcode"
              method: GET
              description: "Resolve a human-readable language name (e.g. `german`) to its ISO 639-1 code."
              inputParameters:
                - name: "language"
                  in: path
                  type: string
                  required: true
                  description: "Human-readable language name in English."
                - name: "format"
                  in: query
                  type: string
                  required: false
                  description: "Response format: json, xml, yaml, or txt."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."

  # ── 2. REST exposer — required default ─────────────────────────────────
  exposes:
    - type: rest
      namespace: "jokeapi-metadata-rest"
      port: 8080
      description: "REST adapter for JokeAPI — Metadata. One Spectral-compliant resource per consumed operation, prefixed with /v1."
      resources:
        - path: "/v1/categories"
          name: "categories"
          description: "REST surface for joke categories."
          operations:
            - method: GET
              name: "getCategories"
              description: "List every joke category JokeAPI exposes, plus recognised category aliases."
              call: "jokeapi-metadata.getCategories"
              with:
                format: "rest.format"
                lang: "rest.lang"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: "/v1/flags"
          name: "flags"
          description: "REST surface for blacklist flags."
          operations:
            - method: GET
              name: "getFlags"
              description: "List the blacklist flags consumers can pass to `?blacklistFlags`."
              call: "jokeapi-metadata.getFlags"
              with:
                format: "rest.format"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: "/v1/formats"
          name: "formats"
          description: "REST surface for response formats."
          operations:
            - method: GET
              name: "getFormats"
              description: "List the response formats JokeAPI can return."
              call: "jokeapi-metadata.getFormats"
              with:
                format: "rest.format"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: "/v1/languages"
          name: "languages"
          description: "REST surface for languages."
          operations:
            - method: GET
              name: "getLanguages"
              description: "List the joke languages and the system languages JokeAPI supports."
              call: "jokeapi-metadata.getLanguages"
              with:
                format: "rest.format"
                lang: "rest.lang"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: "/v1/language-codes/{language}"
          name: "language-codes"
          description: "REST surface for human-name-to-ISO language code resolution."
          operations:
            - method: GET
              name: "getLangcode"
              description: "Resolve a human-readable language name (e.g. `german`) to its ISO 639-1 code."
              call: "jokeapi-metadata.getLangcode"
              with:
                language: "rest.language"
                format: "rest.format"
              outputParameters:
                - type: object
                  mapping: "$."

    # ── 3. MCP exposer — required default ────────────────────────────────
    - type: mcp
      namespace: "jokeapi-metadata-mcp"
      port: 9090
      transport: http
      description: "MCP adapter for JokeAPI — Metadata. One tool per consumed operation, routed inline through this capability's consumes block."
      tools:
        - name: "list-categories"
          description: "List every joke category JokeAPI exposes, plus recognised category aliases."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "jokeapi-metadata.getCategories"
          with:
            format: "tools.format"
            lang: "tools.lang"
          outputParameters:
            - type: object
              mapping: "$."
        - name: "list-flags"
          description: "List the blacklist flags consumers can pass to `?blacklistFlags`."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "jokeapi-metadata.getFlags"
          with:
            format: "tools.format"
          outputParameters:
            - type: object
              mapping: "$."
        - name: "list-formats"
          description: "List the response formats JokeAPI can return."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "jokeapi-metadata.getFormats"
          with:
            format: "tools.format"
          outputParameters:
            - type: object
              mapping: "$."
        - name: "list-languages"
          description: "List the joke languages and the system languages JokeAPI supports."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "jokeapi-metadata.getLanguages"
          with:
            format: "tools.format"
            lang: "tools.lang"
          outputParameters:
            - type: object
              mapping: "$."
        - name: "resolve-language-code"
          description: "Resolve a human-readable language name (e.g. `german`) to its ISO 639-1 code."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "jokeapi-metadata.getLangcode"
          with:
            language: "tools.language"
            format: "tools.format"
          outputParameters:
            - type: object
              mapping: "$."