JSONPlaceholder REST API — Todos

naftiko: "1.0.0-alpha2"

info:
  label: "JSONPlaceholder REST API — Todos"
  description: >-
    Todos — the JSONPlaceholder todo-list surface. 6 operations. Lead
    operation: List Todos. Self-contained Naftiko capability covering one
    JSONPlaceholder business surface.
  tags:
    - JSONPlaceholder
    - Todos
    - 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-todos"
      baseUri: "https://jsonplaceholder.typicode.com"
      description: "JSONPlaceholder Todos surface. No authentication required."
      resources:
        - name: "todos"
          path: "/todos"
          operations:
            - name: "listTodos"
              method: GET
              description: "List all 200 todos; optional query filters."
              inputParameters:
                - name: "userId"
                  in: query
                  type: integer
                  required: false
                  description: "Filter todos by owning user id."
                - name: "completed"
                  in: query
                  type: boolean
                  required: false
                  description: "Filter todos by completion state."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
            - name: "createTodo"
              method: POST
              description: "Create a new todo (simulated)."
              inputParameters:
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Todo payload."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "todo"
          path: "/todos/{id}"
          operations:
            - name: "getTodo"
              method: GET
              description: "Get a single todo by id."
              inputParameters:
                - name: "id"
                  in: path
                  type: integer
                  required: true
                  description: "Todo identifier (1-200)."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
            - name: "replaceTodo"
              method: PUT
              description: "Replace a todo in full (simulated)."
              inputParameters:
                - name: "id"
                  in: path
                  type: integer
                  required: true
                  description: "Todo identifier."
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Full replacement payload."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
            - name: "updateTodo"
              method: PATCH
              description: "Partially update a todo (simulated)."
              inputParameters:
                - name: "id"
                  in: path
                  type: integer
                  required: true
                  description: "Todo identifier."
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Partial update payload."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
            - name: "deleteTodo"
              method: DELETE
              description: "Delete a todo (simulated)."
              inputParameters:
                - name: "id"
                  in: path
                  type: integer
                  required: true
                  description: "Todo identifier."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."

  exposes:
    - type: rest
      namespace: "jsonplaceholder-todos-rest"
      port: 8080
      description: "REST adapter for JSONPlaceholder Todos."
      resources:
        - path: "/v1/todos"
          name: "todos"
          description: "List and create todos."
          operations:
            - method: GET
              name: "listTodos"
              description: "List all todos."
              call: "jsonplaceholder-todos.listTodos"
              with: { "userId": "rest.userId", "completed": "rest.completed" }
              outputParameters: [{ type: object, mapping: "$." }]
            - method: POST
              name: "createTodo"
              description: "Create a new todo (simulated)."
              call: "jsonplaceholder-todos.createTodo"
              with: { "body": "rest.body" }
              outputParameters: [{ type: object, mapping: "$." }]
        - path: "/v1/todos/{id}"
          name: "todo"
          description: "Read, replace, update, or delete a single todo."
          operations:
            - method: GET
              name: "getTodo"
              description: "Get a single todo by id."
              call: "jsonplaceholder-todos.getTodo"
              with: { "id": "rest.id" }
              outputParameters: [{ type: object, mapping: "$." }]
            - method: PUT
              name: "replaceTodo"
              description: "Replace a todo in full (simulated)."
              call: "jsonplaceholder-todos.replaceTodo"
              with: { "id": "rest.id", "body": "rest.body" }
              outputParameters: [{ type: object, mapping: "$." }]
            - method: PATCH
              name: "updateTodo"
              description: "Partially update a todo (simulated)."
              call: "jsonplaceholder-todos.updateTodo"
              with: { "id": "rest.id", "body": "rest.body" }
              outputParameters: [{ type: object, mapping: "$." }]
            - method: DELETE
              name: "deleteTodo"
              description: "Delete a todo (simulated)."
              call: "jsonplaceholder-todos.deleteTodo"
              with: { "id": "rest.id" }
              outputParameters: [{ type: object, mapping: "$." }]

    - type: mcp
      namespace: "jsonplaceholder-todos-mcp"
      port: 9090
      transport: http
      description: "MCP adapter for JSONPlaceholder Todos."
      tools:
        - name: "list-todos"
          description: "List all todos, optionally filtered by userId and completed."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "jsonplaceholder-todos.listTodos"
          with: { "userId": "tools.userId", "completed": "tools.completed" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "create-todo"
          description: "Create a new todo (simulated)."
          hints: { readOnly: false, destructive: false, idempotent: false }
          call: "jsonplaceholder-todos.createTodo"
          with: { "body": "tools.body" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "get-todo"
          description: "Get a single todo by id."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "jsonplaceholder-todos.getTodo"
          with: { "id": "tools.id" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "replace-todo"
          description: "Replace a todo in full (simulated)."
          hints: { readOnly: false, destructive: false, idempotent: true }
          call: "jsonplaceholder-todos.replaceTodo"
          with: { "id": "tools.id", "body": "tools.body" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "update-todo"
          description: "Partially update a todo (simulated)."
          hints: { readOnly: false, destructive: false, idempotent: true }
          call: "jsonplaceholder-todos.updateTodo"
          with: { "id": "tools.id", "body": "tools.body" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "delete-todo"
          description: "Delete a todo (simulated)."
          hints: { readOnly: false, destructive: true, idempotent: true }
          call: "jsonplaceholder-todos.deleteTodo"
          with: { "id": "tools.id" }
          outputParameters: [{ type: object, mapping: "$." }]