JSONPlaceholder REST API — Photos

naftiko: "1.0.0-alpha2"

info:
  label: "JSONPlaceholder REST API — Photos"
  description: >-
    Photos — the JSONPlaceholder photos surface (5000 placeholder images
    grouped into 100 albums). 6 operations. Lead operation: List Photos.
    Self-contained Naftiko capability covering one JSONPlaceholder business
    surface.
  tags:
    - JSONPlaceholder
    - Photos
    - 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-photos"
      baseUri: "https://jsonplaceholder.typicode.com"
      description: "JSONPlaceholder Photos surface. No authentication required."
      resources:
        - name: "photos"
          path: "/photos"
          operations:
            - name: "listPhotos"
              method: GET
              description: "List all 5000 photos; optional query filters."
              inputParameters:
                - name: "albumId"
                  in: query
                  type: integer
                  required: false
                  description: "Filter photos by owning album id."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
            - name: "createPhoto"
              method: POST
              description: "Create a new photo (simulated)."
              inputParameters:
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Photo payload."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "photo"
          path: "/photos/{id}"
          operations:
            - name: "getPhoto"
              method: GET
              description: "Get a single photo by id."
              inputParameters:
                - name: "id"
                  in: path
                  type: integer
                  required: true
                  description: "Photo identifier (1-5000)."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
            - name: "replacePhoto"
              method: PUT
              description: "Replace a photo in full (simulated)."
              inputParameters:
                - name: "id"
                  in: path
                  type: integer
                  required: true
                  description: "Photo identifier."
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Full replacement payload."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
            - name: "updatePhoto"
              method: PATCH
              description: "Partially update a photo (simulated)."
              inputParameters:
                - name: "id"
                  in: path
                  type: integer
                  required: true
                  description: "Photo identifier."
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Partial update payload."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
            - name: "deletePhoto"
              method: DELETE
              description: "Delete a photo (simulated)."
              inputParameters:
                - name: "id"
                  in: path
                  type: integer
                  required: true
                  description: "Photo identifier."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."

  exposes:
    - type: rest
      namespace: "jsonplaceholder-photos-rest"
      port: 8080
      description: "REST adapter for JSONPlaceholder Photos."
      resources:
        - path: "/v1/photos"
          name: "photos"
          description: "List and create photos."
          operations:
            - method: GET
              name: "listPhotos"
              description: "List all photos."
              call: "jsonplaceholder-photos.listPhotos"
              with: { "albumId": "rest.albumId" }
              outputParameters: [{ type: object, mapping: "$." }]
            - method: POST
              name: "createPhoto"
              description: "Create a new photo (simulated)."
              call: "jsonplaceholder-photos.createPhoto"
              with: { "body": "rest.body" }
              outputParameters: [{ type: object, mapping: "$." }]
        - path: "/v1/photos/{id}"
          name: "photo"
          description: "Read, replace, update, or delete a single photo."
          operations:
            - method: GET
              name: "getPhoto"
              description: "Get a single photo by id."
              call: "jsonplaceholder-photos.getPhoto"
              with: { "id": "rest.id" }
              outputParameters: [{ type: object, mapping: "$." }]
            - method: PUT
              name: "replacePhoto"
              description: "Replace a photo in full (simulated)."
              call: "jsonplaceholder-photos.replacePhoto"
              with: { "id": "rest.id", "body": "rest.body" }
              outputParameters: [{ type: object, mapping: "$." }]
            - method: PATCH
              name: "updatePhoto"
              description: "Partially update a photo (simulated)."
              call: "jsonplaceholder-photos.updatePhoto"
              with: { "id": "rest.id", "body": "rest.body" }
              outputParameters: [{ type: object, mapping: "$." }]
            - method: DELETE
              name: "deletePhoto"
              description: "Delete a photo (simulated)."
              call: "jsonplaceholder-photos.deletePhoto"
              with: { "id": "rest.id" }
              outputParameters: [{ type: object, mapping: "$." }]

    - type: mcp
      namespace: "jsonplaceholder-photos-mcp"
      port: 9090
      transport: http
      description: "MCP adapter for JSONPlaceholder Photos."
      tools:
        - name: "list-photos"
          description: "List all photos, optionally filtered by albumId."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "jsonplaceholder-photos.listPhotos"
          with: { "albumId": "tools.albumId" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "create-photo"
          description: "Create a new photo (simulated)."
          hints: { readOnly: false, destructive: false, idempotent: false }
          call: "jsonplaceholder-photos.createPhoto"
          with: { "body": "tools.body" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "get-photo"
          description: "Get a single photo by id."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "jsonplaceholder-photos.getPhoto"
          with: { "id": "tools.id" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "replace-photo"
          description: "Replace a photo in full (simulated)."
          hints: { readOnly: false, destructive: false, idempotent: true }
          call: "jsonplaceholder-photos.replacePhoto"
          with: { "id": "tools.id", "body": "tools.body" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "update-photo"
          description: "Partially update a photo (simulated)."
          hints: { readOnly: false, destructive: false, idempotent: true }
          call: "jsonplaceholder-photos.updatePhoto"
          with: { "id": "tools.id", "body": "tools.body" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "delete-photo"
          description: "Delete a photo (simulated)."
          hints: { readOnly: false, destructive: true, idempotent: true }
          call: "jsonplaceholder-photos.deletePhoto"
          with: { "id": "tools.id" }
          outputParameters: [{ type: object, mapping: "$." }]