openapi: 3.0.3
info:
  title: JSONPlaceholder REST Albums Photos API
  description: 'JSONPlaceholder is a free, no-auth fake REST API for prototyping, testing, and teaching. It exposes six relational resources — posts, comments, albums, photos, todos, and users — over standard REST routes (GET, POST, PUT, PATCH, DELETE). Write operations are simulated: the service responds as though the change succeeded, but no data is persisted on the server. The service is powered by the open-source json-server engine, also by typicode.'
  version: 1.0.0
  contact:
    name: typicode
    url: https://github.com/typicode/jsonplaceholder
  license:
    name: MIT
    url: https://github.com/typicode/jsonplaceholder/blob/master/LICENSE
  x-generated-from: documentation
  x-last-validated: '2026-05-29'
servers:
- url: https://jsonplaceholder.typicode.com
  description: Public production endpoint (no authentication required)
tags:
- name: Photos
  description: 5000 sample photos belonging to albums
paths:
  /albums/{id}/photos:
    parameters:
    - name: id
      in: path
      required: true
      description: Album identifier.
      schema:
        type: integer
      example: 1
    get:
      operationId: listAlbumPhotos
      summary: JSONPlaceholder List Album Photos
      description: Returns all photos belonging to a single album.
      tags:
      - Photos
      responses:
        '200':
          description: Array of photos for the album.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Photo'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /photos:
    get:
      operationId: listPhotos
      summary: JSONPlaceholder List Photos
      description: Returns all 5000 sample photos. Supports filtering by any field via query parameters (e.g. `?albumId=1`).
      tags:
      - Photos
      parameters:
      - name: albumId
        in: query
        description: Filter photos by owning album id.
        required: false
        schema:
          type: integer
        example: 1
      responses:
        '200':
          description: Array of photos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Photo'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createPhoto
      summary: JSONPlaceholder Create Photo
      description: Creates a new photo (simulated).
      tags:
      - Photos
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhotoInput'
      responses:
        '201':
          description: Created photo (simulated).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Photo'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /photos/{id}:
    parameters:
    - name: id
      in: path
      required: true
      description: Photo identifier (1-5000).
      schema:
        type: integer
      example: 1
    get:
      operationId: getPhoto
      summary: JSONPlaceholder Get Photo
      description: Returns a single photo by id.
      tags:
      - Photos
      responses:
        '200':
          description: A single photo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Photo'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: replacePhoto
      summary: JSONPlaceholder Replace Photo
      description: Replaces a photo in full (simulated).
      tags:
      - Photos
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Photo'
      responses:
        '200':
          description: Updated photo (simulated).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Photo'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updatePhoto
      summary: JSONPlaceholder Update Photo
      description: Partially updates a photo (simulated).
      tags:
      - Photos
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhotoInput'
      responses:
        '200':
          description: Updated photo (simulated).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Photo'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deletePhoto
      summary: JSONPlaceholder Delete Photo
      description: Deletes a photo (simulated).
      tags:
      - Photos
      responses:
        '200':
          description: Deletion accepted (simulated).
          content:
            application/json:
              schema:
                type: object
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Photo:
      type: object
      description: A sample photo belonging to an album.
      required:
      - id
      - albumId
      - title
      - url
      - thumbnailUrl
      properties:
        id:
          type: integer
          description: Unique photo identifier (1-5000).
          example: 1
        albumId:
          type: integer
          description: Identifier of the album this photo belongs to.
          example: 1
        title:
          type: string
          description: Photo title / caption.
          example: accusamus beatae ad facilis cum similique qui sunt
        url:
          type: string
          format: uri
          description: Full-size image URL (placeholder service).
          example: https://via.placeholder.com/600/92c952
        thumbnailUrl:
          type: string
          format: uri
          description: Thumbnail image URL (placeholder service).
          example: https://via.placeholder.com/150/92c952
    PhotoInput:
      type: object
      description: Payload for creating or partially updating a photo.
      properties:
        albumId:
          type: integer
          description: Identifier of the album this photo belongs to.
          example: 1
        title:
          type: string
          description: Photo title / caption.
          example: A new photo
        url:
          type: string
          format: uri
          description: Full-size image URL.
          example: https://via.placeholder.com/600/abcdef
        thumbnailUrl:
          type: string
          format: uri
          description: Thumbnail image URL.
          example: https://via.placeholder.com/150/abcdef