JSONPlaceholder REST API — Albums

naftiko: "1.0.0-alpha2"

info:
  label: "JSONPlaceholder REST API — Albums"
  description: >-
    Albums — the JSONPlaceholder photo-album surface. 7 operations. Lead
    operation: List Albums. Self-contained Naftiko capability covering one
    JSONPlaceholder business surface.
  tags:
    - JSONPlaceholder
    - Albums
    - 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-albums"
      baseUri: "https://jsonplaceholder.typicode.com"
      description: "JSONPlaceholder Albums surface. No authentication required."
      resources:
        - name: "albums"
          path: "/albums"
          operations:
            - name: "listAlbums"
              method: GET
              description: "List all 100 albums; optional query filters."
              inputParameters:
                - name: "userId"
                  in: query
                  type: integer
                  required: false
                  description: "Filter albums by owning user id."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
            - name: "createAlbum"
              method: POST
              description: "Create a new album (simulated)."
              inputParameters:
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Album payload."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "album"
          path: "/albums/{id}"
          operations:
            - name: "getAlbum"
              method: GET
              description: "Get a single album by id."
              inputParameters:
                - name: "id"
                  in: path
                  type: integer
                  required: true
                  description: "Album identifier (1-100)."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
            - name: "replaceAlbum"
              method: PUT
              description: "Replace an album in full (simulated)."
              inputParameters:
                - name: "id"
                  in: path
                  type: integer
                  required: true
                  description: "Album identifier."
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Full replacement payload."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
            - name: "updateAlbum"
              method: PATCH
              description: "Partially update an album (simulated)."
              inputParameters:
                - name: "id"
                  in: path
                  type: integer
                  required: true
                  description: "Album identifier."
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Partial update payload."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
            - name: "deleteAlbum"
              method: DELETE
              description: "Delete an album (simulated)."
              inputParameters:
                - name: "id"
                  in: path
                  type: integer
                  required: true
                  description: "Album identifier."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "album-photos"
          path: "/albums/{id}/photos"
          operations:
            - name: "listAlbumPhotos"
              method: GET
              description: "List all photos belonging to a single album."
              inputParameters:
                - name: "id"
                  in: path
                  type: integer
                  required: true
                  description: "Album identifier."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."

  exposes:
    - type: rest
      namespace: "jsonplaceholder-albums-rest"
      port: 8080
      description: "REST adapter for JSONPlaceholder Albums."
      resources:
        - path: "/v1/albums"
          name: "albums"
          description: "List and create albums."
          operations:
            - method: GET
              name: "listAlbums"
              description: "List all albums."
              call: "jsonplaceholder-albums.listAlbums"
              with:
                "userId": "rest.userId"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: "createAlbum"
              description: "Create a new album (simulated)."
              call: "jsonplaceholder-albums.createAlbum"
              with:
                "body": "rest.body"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: "/v1/albums/{id}"
          name: "album"
          description: "Read, replace, update, or delete a single album."
          operations:
            - method: GET
              name: "getAlbum"
              description: "Get a single album by id."
              call: "jsonplaceholder-albums.getAlbum"
              with:
                "id": "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: PUT
              name: "replaceAlbum"
              description: "Replace an album in full (simulated)."
              call: "jsonplaceholder-albums.replaceAlbum"
              with:
                "id": "rest.id"
                "body": "rest.body"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: PATCH
              name: "updateAlbum"
              description: "Partially update an album (simulated)."
              call: "jsonplaceholder-albums.updateAlbum"
              with:
                "id": "rest.id"
                "body": "rest.body"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: DELETE
              name: "deleteAlbum"
              description: "Delete an album (simulated)."
              call: "jsonplaceholder-albums.deleteAlbum"
              with:
                "id": "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: "/v1/albums/{id}/photos"
          name: "album-photos"
          description: "List photos for a single album."
          operations:
            - method: GET
              name: "listAlbumPhotos"
              description: "List all photos belonging to a single album."
              call: "jsonplaceholder-albums.listAlbumPhotos"
              with:
                "id": "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      namespace: "jsonplaceholder-albums-mcp"
      port: 9090
      transport: http
      description: "MCP adapter for JSONPlaceholder Albums."
      tools:
        - name: "list-albums"
          description: "List all albums, optionally filtered by userId."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "jsonplaceholder-albums.listAlbums"
          with: { "userId": "tools.userId" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "create-album"
          description: "Create a new album (simulated)."
          hints: { readOnly: false, destructive: false, idempotent: false }
          call: "jsonplaceholder-albums.createAlbum"
          with: { "body": "tools.body" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "get-album"
          description: "Get a single album by id."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "jsonplaceholder-albums.getAlbum"
          with: { "id": "tools.id" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "replace-album"
          description: "Replace an album in full (simulated)."
          hints: { readOnly: false, destructive: false, idempotent: true }
          call: "jsonplaceholder-albums.replaceAlbum"
          with: { "id": "tools.id", "body": "tools.body" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "update-album"
          description: "Partially update an album (simulated)."
          hints: { readOnly: false, destructive: false, idempotent: true }
          call: "jsonplaceholder-albums.updateAlbum"
          with: { "id": "tools.id", "body": "tools.body" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "delete-album"
          description: "Delete an album (simulated)."
          hints: { readOnly: false, destructive: true, idempotent: true }
          call: "jsonplaceholder-albums.deleteAlbum"
          with: { "id": "tools.id" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "list-album-photos"
          description: "List all photos belonging to a single album."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "jsonplaceholder-albums.listAlbumPhotos"
          with: { "id": "tools.id" }
          outputParameters: [{ type: object, mapping: "$." }]