openapi: 3.0.3
info:
  title: An API of Ice and Fire books API
  description: An API of Ice and Fire is a free, open REST API providing comprehensive Game of Thrones and A Song of Ice and Fire data including books, characters, and houses from George R.R. Martin's universe. No authentication is required. The API offers structured, quantified data about the HBO series and book series covering all named characters, their allegiances, relationships, book appearances, TV season appearances, and details on every noble house and published book in the series.
  version: 1.0.0
  contact:
    name: Joakim Skoog
    url: https://github.com/joakimskoog
  license:
    name: MIT
    url: https://github.com/joakimskoog/AnApiOfIceAndFire/blob/master/LICENSE.md
  termsOfService: https://anapioficeandfire.com/
servers:
- url: https://www.anapioficeandfire.com/api
  description: Production server
tags:
- name: books
  description: Books from the A Song of Ice and Fire series
paths:
  /:
    get:
      summary: API root
      description: Returns the root resource listing all top-level endpoints.
      operationId: getRoot
      tags:
      - books
      responses:
        '200':
          description: Root resource with links to books, characters, and houses.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RootResource'
              example:
                books: https://www.anapioficeandfire.com/api/books
                characters: https://www.anapioficeandfire.com/api/characters
                houses: https://www.anapioficeandfire.com/api/houses
  /books:
    get:
      summary: List books
      description: Returns a paginated list of all books in the A Song of Ice and Fire series. Results support filtering by name, fromReleaseDate, and toReleaseDate.
      operationId: listBooks
      tags:
      - books
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/pageSize'
      - name: name
        in: query
        description: Filter books by name (case-sensitive, partial match).
        required: false
        schema:
          type: string
        example: A Game of Thrones
      - name: fromReleaseDate
        in: query
        description: Filter books released on or after this date (ISO 8601).
        required: false
        schema:
          type: string
          format: date-time
        example: '1996-01-01T00:00:00'
      - name: toReleaseDate
        in: query
        description: Filter books released on or before this date (ISO 8601).
        required: false
        schema:
          type: string
          format: date-time
        example: '2020-12-31T00:00:00'
      responses:
        '200':
          description: A paginated list of books.
          headers:
            Link:
              description: Hypermedia pagination links (first, prev, next, last) using RFC 5988 format.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Book'
  /books/{id}:
    get:
      summary: Get a book
      description: Returns a single book resource by its numeric ID.
      operationId: getBook
      tags:
      - books
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: A book resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
        '404':
          description: Book not found.
components:
  schemas:
    RootResource:
      type: object
      description: Root resource containing links to the top-level collections.
      properties:
        books:
          type: string
          format: uri
          description: URL to the books collection.
        characters:
          type: string
          format: uri
          description: URL to the characters collection.
        houses:
          type: string
          format: uri
          description: URL to the houses collection.
    Book:
      type: object
      description: A book published in the A Song of Ice and Fire series.
      properties:
        url:
          type: string
          format: uri
          description: The canonical URL of this book resource.
        name:
          type: string
          description: The name of the book.
          example: A Game of Thrones
        isbn:
          type: string
          description: ISBN-13 of the book.
          example: 978-0553103540
        authors:
          type: array
          description: List of authors who wrote this book.
          items:
            type: string
          example:
          - George R. R. Martin
        numberOfPages:
          type: integer
          description: Total number of pages in the book.
          example: 694
        publisher:
          type: string
          description: Publisher of the book.
          example: Bantam Books
        country:
          type: string
          description: Country of origin for the original publication.
          example: United States
        mediaType:
          type: string
          description: Media type (e.g. Hardcover, Paperback).
          example: Hardcover
        released:
          type: string
          format: date-time
          description: Release date of the book (ISO 8601).
          example: '1996-08-01T00:00:00'
        characters:
          type: array
          description: URLs of characters who appear in this book.
          items:
            type: string
            format: uri
        povCharacters:
          type: array
          description: URLs of characters with point-of-view chapters in this book.
          items:
            type: string
            format: uri
  parameters:
    id:
      name: id
      in: path
      required: true
      description: Numeric identifier of the resource.
      schema:
        type: integer
        minimum: 1
      example: 1
    pageSize:
      name: pageSize
      in: query
      required: false
      description: Number of results per page (max 50).
      schema:
        type: integer
        minimum: 1
        maximum: 50
        default: 10
      example: 10
    page:
      name: page
      in: query
      required: false
      description: Page number for pagination (1-based).
      schema:
        type: integer
        minimum: 1
        default: 1
      example: 1
externalDocs:
  description: Official API Documentation (GitHub Wiki)
  url: https://github.com/joakimskoog/AnApiOfIceAndFire/wiki