openapi: 3.0.3
info:
  title: An API of Ice And Fire Books API
  version: '1.0'
  description: An API of Ice And Fire is the world's greatest source for quantified and structured data from the universe of A Song of Ice and Fire (and the HBO series Game of Thrones). Three hypermedia resources — Books, Characters, and Houses — are exposed read-only over HTTPS, free of authentication, with RFC 5988 Link-header pagination, conditional caching (ETag / Last-Modified), and version selection via custom media types.
  termsOfService: https://github.com/joakimskoog/AnApiOfIceAndFire/blob/master/LICENSE.md
  contact:
    name: Joakim Skoog (maintainer)
    url: https://github.com/joakimskoog/AnApiOfIceAndFire
  license:
    name: BSD 3-Clause-like
    url: https://github.com/joakimskoog/AnApiOfIceAndFire/blob/master/LICENSE.md
  x-generated-from: documentation
  x-last-validated: '2026-05-30'
servers:
- url: https://anapioficeandfire.com/api
  description: Production
tags:
- name: Books
  description: Books in the A Song of Ice and Fire series.
paths:
  /books:
    get:
      operationId: listBooks
      summary: An API of Ice And Fire List Books
      description: List all books in the A Song of Ice and Fire series. Supports filtering by name and release-date range, plus RFC 5988 Link-header pagination.
      tags:
      - Books
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      - name: name
        in: query
        description: Filter books by exact book name.
        required: false
        schema:
          type: string
      - name: fromReleaseDate
        in: query
        description: Only include books released on or after this date (ISO 8601).
        required: false
        schema:
          type: string
          format: date
      - name: toReleaseDate
        in: query
        description: Only include books released on or before this date (ISO 8601).
        required: false
        schema:
          type: string
          format: date
      responses:
        '200':
          description: A paginated list of books.
          headers:
            Link:
              $ref: '#/components/headers/Link'
            ETag:
              $ref: '#/components/headers/ETag'
            Last-Modified:
              $ref: '#/components/headers/LastModified'
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Book'
              examples:
                ListBooks200Example:
                  summary: Default listBooks 200 response
                  x-microcks-default: true
                  value:
                  - url: https://anapioficeandfire.com/api/books/1
                    name: A Game of Thrones
                    isbn: 978-0553103540
                    authors:
                    - George R. R. Martin
                    numberOfPages: 694
                    publisher: Bantam Books
                    country: United States
                    mediaType: Hardcover
                    released: '1996-08-01T00:00:00'
                    characters:
                    - https://anapioficeandfire.com/api/characters/2
                    - https://anapioficeandfire.com/api/characters/12
                    - https://anapioficeandfire.com/api/characters/13
                    povCharacters:
                    - https://anapioficeandfire.com/api/characters/148
                    - https://anapioficeandfire.com/api/characters/208
                    - https://anapioficeandfire.com/api/characters/232
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/RateLimited'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /books/{id}:
    get:
      operationId: getBook
      summary: An API of Ice And Fire Get Book by ID
      description: Retrieve a single book by its numeric ID. Returns the full hypermedia book resource with absolute character and POV-character URLs.
      tags:
      - Books
      parameters:
      - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: The requested book.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Last-Modified:
              $ref: '#/components/headers/LastModified'
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
              examples:
                GetBook200Example:
                  summary: Default getBook 200 response
                  x-microcks-default: true
                  value:
                    url: https://anapioficeandfire.com/api/books/1
                    name: A Game of Thrones
                    isbn: 978-0553103540
                    authors:
                    - George R. R. Martin
                    numberOfPages: 694
                    publisher: Bantam Books
                    country: United States
                    mediaType: Hardcover
                    released: '1996-08-01T00:00:00'
                    characters:
                    - https://anapioficeandfire.com/api/characters/2
                    - https://anapioficeandfire.com/api/characters/12
                    - https://anapioficeandfire.com/api/characters/13
                    povCharacters:
                    - https://anapioficeandfire.com/api/characters/148
                    - https://anapioficeandfire.com/api/characters/208
                    - https://anapioficeandfire.com/api/characters/232
        '304':
          $ref: '#/components/responses/NotModified'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/RateLimited'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  responses:
    NotFound:
      description: The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotModified:
      description: The resource has not changed since the version identified by the client's If-None-Match or If-Modified-Since header.
    BadRequest:
      description: Malformed request — invalid query parameter or value.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: The caller has exceeded the per-IP daily rate limit of 20,000 requests. The window resets every 24 hours.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    Id:
      name: id
      in: path
      description: Numeric resource identifier.
      required: true
      schema:
        type: integer
        format: int32
        minimum: 1
      example: 1
    PageSize:
      name: pageSize
      in: query
      description: Items per page (default 10, max 50).
      required: false
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 50
        default: 10
      example: 10
    Page:
      name: page
      in: query
      description: Page number (1-indexed). Defaults to 1.
      required: false
      schema:
        type: integer
        format: int32
        minimum: 1
        default: 1
      example: 1
  headers:
    CacheControl:
      description: Cache-Control directives, typically including max-age.
      schema:
        type: string
    Link:
      description: RFC 5988 pagination links with `first`, `prev`, `next`, and `last` relations.
      schema:
        type: string
    ETag:
      description: Strong entity tag for conditional GETs via If-None-Match.
      schema:
        type: string
    LastModified:
      description: Last-modified timestamp for conditional GETs via If-Modified-Since.
      schema:
        type: string
  schemas:
    Book:
      type: object
      description: A book in the A Song of Ice and Fire series.
      properties:
        url:
          type: string
          format: uri
          description: Hypermedia self-link for this book.
          example: https://anapioficeandfire.com/api/books/1
        name:
          type: string
          description: Book title.
          example: A Game of Thrones
        isbn:
          type: string
          description: ISBN-10 or ISBN-13 identifier.
          example: 978-0553103540
        authors:
          type: array
          description: Author names.
          items:
            type: string
          example:
          - George R. R. Martin
        numberOfPages:
          type: integer
          format: int32
          description: Page count.
          example: 694
        publisher:
          type: string
          description: Publishing company.
          example: Bantam Books
        country:
          type: string
          description: Country of publication.
          example: United States
        mediaType:
          type: string
          description: Release format (e.g. Hardcover, Paperback).
          example: Hardcover
        released:
          type: string
          format: date-time
          description: Release date in ISO 8601 format.
          example: '1996-08-01T00:00:00'
        characters:
          type: array
          description: URLs of characters featured in the book.
          items:
            type: string
            format: uri
          example:
          - https://anapioficeandfire.com/api/characters/2
          - https://anapioficeandfire.com/api/characters/12
          - https://anapioficeandfire.com/api/characters/13
        povCharacters:
          type: array
          description: URLs of characters with POV chapters in the book.
          items:
            type: string
            format: uri
          example:
          - https://anapioficeandfire.com/api/characters/148
          - https://anapioficeandfire.com/api/characters/208
          - https://anapioficeandfire.com/api/characters/232
    Error:
      type: object
      description: Error response envelope.
      properties:
        message:
          type: string
          description: Human-readable error message.
          example: The requested resource could not be found.