JSONPlaceholder REST API — Comments

naftiko: "1.0.0-alpha2"

info:
  label: "JSONPlaceholder REST API — Comments"
  description: >-
    Comments — the JSONPlaceholder comments surface. 6 operations. Lead
    operation: List Comments. Self-contained Naftiko capability covering one
    JSONPlaceholder business surface.
  tags:
    - JSONPlaceholder
    - Comments
    - Fake REST
  created: "2026-05-29"
  modified: "2026-05-29"

binds:
  - namespace: env
    keys:
      JSONPLACEHOLDER_BASE_URL: JSONPLACEHOLDER_BASE_URL

capability:

  consumes:
    - type: http
      namespace: "jsonplaceholder-comments"
      baseUri: "https://jsonplaceholder.typicode.com"
      description: "JSONPlaceholder Comments surface. No authentication required."
      resources:
        - name: "comments"
          path: "/comments"
          operations:
            - name: "listComments"
              method: GET
              description: "List all 500 comments; optional query filters."
              inputParameters:
                - name: "postId"
                  in: query
                  type: integer
                  required: false
                  description: "Filter comments by post id."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
            - name: "createComment"
              method: POST
              description: "Create a new comment (simulated)."
              inputParameters:
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Comment payload."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "comment"
          path: "/comments/{id}"
          operations:
            - name: "getComment"
              method: GET
              description: "Get a single comment by id."
              inputParameters:
                - name: "id"
                  in: path
                  type: integer
                  required: true
                  description: "Comment identifier (1-500)."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
            - name: "replaceComment"
              method: PUT
              description: "Replace a comment in full (simulated)."
              inputParameters:
                - name: "id"
                  in: path
                  type: integer
                  required: true
                  description: "Comment identifier."
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Full replacement payload."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
            - name: "updateComment"
              method: PATCH
              description: "Partially update a comment (simulated)."
              inputParameters:
                - name: "id"
                  in: path
                  type: integer
                  required: true
                  description: "Comment identifier."
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Partial update payload."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
            - name: "deleteComment"
              method: DELETE
              description: "Delete a comment (simulated)."
              inputParameters:
                - name: "id"
                  in: path
                  type: integer
                  required: true
                  description: "Comment identifier."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."

  exposes:
    - type: rest
      namespace: "jsonplaceholder-comments-rest"
      port: 8080
      description: "REST adapter for JSONPlaceholder Comments."
      resources:
        - path: "/v1/comments"
          name: "comments"
          description: "List and create comments."
          operations:
            - method: GET
              name: "listComments"
              description: "List all comments."
              call: "jsonplaceholder-comments.listComments"
              with:
                "postId": "rest.postId"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: "createComment"
              description: "Create a new comment (simulated)."
              call: "jsonplaceholder-comments.createComment"
              with:
                "body": "rest.body"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: "/v1/comments/{id}"
          name: "comment"
          description: "Read, replace, update, or delete a single comment."
          operations:
            - method: GET
              name: "getComment"
              description: "Get a single comment by id."
              call: "jsonplaceholder-comments.getComment"
              with:
                "id": "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: PUT
              name: "replaceComment"
              description: "Replace a comment in full (simulated)."
              call: "jsonplaceholder-comments.replaceComment"
              with:
                "id": "rest.id"
                "body": "rest.body"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: PATCH
              name: "updateComment"
              description: "Partially update a comment (simulated)."
              call: "jsonplaceholder-comments.updateComment"
              with:
                "id": "rest.id"
                "body": "rest.body"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: DELETE
              name: "deleteComment"
              description: "Delete a comment (simulated)."
              call: "jsonplaceholder-comments.deleteComment"
              with:
                "id": "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      namespace: "jsonplaceholder-comments-mcp"
      port: 9090
      transport: http
      description: "MCP adapter for JSONPlaceholder Comments."
      tools:
        - name: "list-comments"
          description: "List all comments, optionally filtered by postId."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "jsonplaceholder-comments.listComments"
          with:
            "postId": "tools.postId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: "create-comment"
          description: "Create a new comment (simulated)."
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: "jsonplaceholder-comments.createComment"
          with:
            "body": "tools.body"
          outputParameters:
            - type: object
              mapping: "$."
        - name: "get-comment"
          description: "Get a single comment by id."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "jsonplaceholder-comments.getComment"
          with:
            "id": "tools.id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: "replace-comment"
          description: "Replace a comment in full (simulated)."
          hints:
            readOnly: false
            destructive: false
            idempotent: true
          call: "jsonplaceholder-comments.replaceComment"
          with:
            "id": "tools.id"
            "body": "tools.body"
          outputParameters:
            - type: object
              mapping: "$."
        - name: "update-comment"
          description: "Partially update a comment (simulated)."
          hints:
            readOnly: false
            destructive: false
            idempotent: true
          call: "jsonplaceholder-comments.updateComment"
          with:
            "id": "tools.id"
            "body": "tools.body"
          outputParameters:
            - type: object
              mapping: "$."
        - name: "delete-comment"
          description: "Delete a comment (simulated)."
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: "jsonplaceholder-comments.deleteComment"
          with:
            "id": "tools.id"
          outputParameters:
            - type: object
              mapping: "$."