openapi.yaml

openapi: 3.0.3
info:
  title: Alt-text Backend API
  description: |-
    This is the Alt-text Backend API based on the OpenAPI 3.0 specification.
  contact:
    email: da.cruz@aol.com
  version: 1.0.11
externalDocs:
  description: Find out more about Alt-text
  url: https://github.com/EbookFoundation/alt-text
tags:
  - name: Books
    description: Everything regarding books
  - name: Images
    description: Everything regarding images
paths:
  /books:
    get:
      tags:
        - Books
      summary: Get a list of books.
      description: Get a list of book objects given various options.
      operationId: getBooks
      parameters:
        - name: titleQ
          in: query
          description: String to match the title to.
          required: false
          explode: true
          schema:
            type: string
        - name: limit
          in: query
          description: Max number of books to return.
          required: false
          explode: true
          schema:
            type: integer
        - name: skip
          in: query
          description: Number of books to skip.
          required: false
          explode: true
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Book'
        '500':
          description: Internal Server Error
    post:
      tags:
        - Books
      summary: Add a book.
      description: Submit a new book for analyzation and store results in database.
      operationId: addBook
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: Id of the book (optional).
                title:
                  type: string
                  description: Title of the book.
                book:
                  type: string
                  description: Zip file of the book.
                  format: binary
                cover:
                  type: string
                  description: Cover image for the book (optional).
                  format: binary
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
        '500':
          description: Internal Server Error
  /books/{bookid}:
    parameters:
      - name: bookid
        in: path
        description: Id of the book.
        required: true
        explode: true
        schema:
          type: string
          example: "123e4567-e89b-12d3-a456-426614174000"
    get:
      tags:
        - Books
      summary: Get a book.
      description: Get a book object with basic information by its id.
      operationId: getBook
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
        '500':
          description: Internal Server Error
    patch:
      tags:
        - Books
      summary: Update a book's metadata.
      description: Update a book's metadata by its id.
      operationId: updateBook
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                title:
                  type: string
                  description: Title of the book (optional).
                cover:
                  type: string
                  description: Cover image for the book (optional).
                  format: binary
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
            application/xml:
              schema:
                $ref: '#/components/schemas/Book'
        '500':
          description: Internal Server Error
    put:
      tags:
      - Books
      summary: Re-analyze an entire book.
      description: Re-analyze an entire book and overwrite current image data by its id.
      operationId: analyzeBook
      parameters:
        - name: missingOnly
          in: query
          description: If analyzing on upload, whether to analyze only the images without alt-text.
          required: false
          explode: true
          schema:
            type: boolean
            example: true
            default: true
        - name: waitForAnalysis
          in: query
          description: Whether to wait for the analysis to complete before returning a response.
          required: false
          explode: true
          schema:
            type: boolean
            example: false
            default: false
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
        '500':
          description: Internal Server Error
    delete:
      tags:
        - Books
      summary: Delete a book.
      description: Delete a book by its id.
      operationId: deleteBook
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
        '500':
          description: Internal Server Error
  /books/{bookid}/export:
    parameters:
      - name: bookid
        in: path
        description: Id of the book.
        required: true
        explode: true
        schema:
          type: string
          example: "123e4567-e89b-12d3-a456-426614174000"
      - name: name
        in: query
        description: Alternative name for file download. 
        required: false
        explode: true
        schema:
          type: string
          default: "{bookid}"
          example: "harry_potter"
    get:
      tags:
        - Books
      summary: Export a book.
      description: Get a zip download of a book with current alt placed into images.
      operationId: exportBook
      responses:
        '200':
          description: Successful operation
          content:
            application/zip:
              schema:
                type: string
                example: |-
                  content of the file
        '500':
          description: Internal Server Error
  /books/{bookid}/images:
    parameters:
      - name: bookid
        in: path
        description: Id of the book.
        required: true
        explode: true
        schema:
          type: string
          example: "123e4567-e89b-12d3-a456-426614174000"
    get:
      tags:
        - Images
      summary: Get images in a book.
      description: Get a list of images in a book by its id.
      operationId: imagesFromBook
      parameters:
        - name: srcQ
          in: query
          description: String to match the title to.
          required: false
          explode: true
          schema:
            type: string
        - name: limit
          in: query
          description: Max number of images to return.
          required: false
          explode: true
          schema:
            type: integer
        - name: skip
          in: query
          description: Number of images to skip.
          required: false
          explode: true
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Image'
        '500':
          description: Internal Server Error
  /books/{bookid}/image:
    parameters:
      - name: bookid
        in: path
        description: Id of the book.
        required: true
        explode: true
        schema:
          type: string
          example: "123e4567-e89b-12d3-a456-426614174000"
      - name: src
        in: query
        description: Src of the image.
        required: true
        explode: true
        schema:
          type: string
          example: "images/cover.png"
    get:
      tags:
        - Images
      summary: Get an image by src given a book.
      description: Get an image information by src name given a book id.
      operationId: getImageBySrc
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Image'
        '500':
          description: Internal Server Error
    patch:
      tags:
        - Images
      summary: Update an image's metadata.
      description: Update an image's related data (e.g. alt, beforeContext, afterContext).
      operationId: updateImageBySrc
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                alt:
                  type: string
                  description: New alt-text for the image (optional).
                beforeContext:
                  type: string
                  description: New beforeContext for the image (optional).
                afterContext:
                  type: string
                  description: New afterContext for the image (optional).
                additionalContext:
                  type: string
                  description: New additionalContext for the image (optional).
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Image'
        '500':
          description: Internal Server Error
    put:
      tags:
        - Images
      summary: Re-analyze an image.
      description: Generate an image's alt-text (written to genAlt field in image object).
      operationId: analyzeImageBySrc
      parameters:
        - name: waitForAnalysis
          in: query
          description: Whether to wait for the analysis to complete before returning a response (default = false).
          required: false
          explode: true
          schema:
            type: boolean
            example: false
            default: false
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Image'
        '500':
          description: Internal Server Error
  /images/{hash}:
    parameters:
      - name: hash
        in: path
        description: Hash value of the image.
        required: true
        explode: true
        schema:
          type: string
    get:
      tags:
        - Images
      summary: Get images by hash.
      description: Get a list of images from any book by its hash.
      operationId: getImagesByHash
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Image'
        '500':
          description: Internal Server Error
  
components:
  schemas:
    Book:
      type: object
      properties:
        id:
          type: string
          example: "123e4567-e89b-12d3-a456-426614174000"
        title:
          type: string
          example: "Diary of an Oxygen Thief"
        size:
          type: string
          example: "1.16MB"
        status:
          type: string
          example: "processing"
          enum: ["available", "processing", "deleted"]
          default: "available"
        numImages:
          type: integer
          example: 4
    Image:
      type: object
      properties:
        bookid:
          type: string
          example: "123e4567-e89b-12d3-a456-426614174000"
        src:
          type: string
          example: "images/cover.png"
        hash:
          type: string
          example: ""
        status:
          type: string
          example: "processing"
          enum: ["available", "processing", "deleted"]
          default: "available"
        alt:
          type: string
          example: ""
          default: "originalAlt"
        originalAlt:
          type: string
          example: ""
        genAlt:
          type: string
          example: ""
          default: ""
        genImageCaption:
          type: string
          example: ""
          default: ""
        ocr:
          type: string
          example: ""
          default: ""
        beforeContext:
          type: string
          example: ""
        afterContext:
          type: string
          example: ""
        additionalContext:
          type: string
          example: ""
          default: ""