swagger.yml

swagger: "2.0"
info:
  title: "Books"
  version: "1.1.0"
paths:
  /health:
    get:
      summary: "Returns API's health status"
      description: "Returns health status of the API and checks on dependent services"
      produces:
        - application/json
      responses:
        200:
          description: "Successfully returns OK status with checks of dependent services"
          schema:
            $ref: "#/definitions/Health"
        429:
          description: "Services warming up or degraded (at least one check in WARNING or CRITICAL status)"
        500:
          $ref: "#/definitions/500_error"
  /books/{id}:
    get:
      summary: "Return book's details"
      description: "Returns book's details for given id"
      produces:
        - application/json
      parameters:
        - $ref: "#/parameters/Book_id"
      responses:
        200:
          description: "Successfully returned a book"
          schema:
            $ref: "#/definitions/Book"
        400:
          description: "Resource not found"
        500:
          $ref: "#/definitions/500_error"
      deprecated: false
  /books:
    get:
      summary: "Returns a list of all books"
      description: "Returns a list of all books and the total number of books"
      produces:
        - application/json
      parameters:
        - $ref: "#/parameters/limit"
        - $ref: "#/parameters/offset"
      responses:
        200:
          description: "Successfully returned a list of all books"
          schema:
            type: object
            properties:
              count:
                description: "Number of books in the response"
                type: integer
              limit:
                description: "Number of books requested"
                type: integer
              offset:
                description: "Number of books into the list that the response starts at"
                type: integer
              total_count:
                description: "Total number of books"
                type: integer
              items:
                description: "list of books"
                type: array
                items:
                  $ref: "#/definitions/Book"
        500:
          $ref: "#/definitions/500_error"
    post:
      summary: "Adds a new book"
      description: "Add a new book to the list"
      parameters:
        - name: Books
          in: body
          schema:
            type: object
            required:
              - title
              - author
            properties:
              title:
                description: "Name of the book"
                type: string
              author:
                description: "Author of the book"
                type: string
              synopsis:
                description: "Brief summary of the book"
                type: string
      responses:
        201:
          description: "Successfully added book"
          schema:
            $ref: "#/definitions/Book"
        400:
          description: "Bad request. Invalid Book supplied"
        500:
          $ref: "#/definitions/500_error"
  /books/{id}/reviews/{review_id}:
    get:
      summary: "Returns a specific review"
      description: "Returns a specific review (review_id) of a book (id)"
      produces:
        - application/json
      parameters:
        - $ref: "#/parameters/Book_id"
        - $ref: "#/parameters/Review_id"
      responses:
        200:
          description: "Successfully returns a review for a given book"
          schema:
            $ref: "#/definitions/Review"
        400:
          description: "Bad request. Invalid book or review id supplied"
        500:
          $ref: "#/definitions/500_error"
    put:
      summary: "Updates a specific review"
      description: "Updates the message and/or user of a specific review. At least one (user/message) must be specified in the body"
      produces:
        - application/json
      parameters:
        - $ref: "#/parameters/Book_id"
        - $ref: "#/parameters/Review_id"
        - $ref: "#/parameters/Review"
      responses:
        200:
          description: "Successfully updated review for the book"
        400:
          description: "Bad request. Invalid book or review id supplied"
        500:
          $ref: "#/definitions/500_error"
  /books/{id}/reviews:
    get:
      summary: "Returns all the reviews for a book"
      description: "Returns a list of all the reviews for a given book"
      produces:
        - application/json
      parameters:
        - $ref: "#/parameters/Book_id"
        - $ref: "#/parameters/limit"
        - $ref: "#/parameters/offset"
      responses:
        200:
          description: "Successfully returns a list of reviews for the book with the given id"
          schema:
            type: object
            properties:
              count:
                description: "Number of reviews in the response"
                type: integer
              limit:
                description: "Number of reviews requested"
                type: integer
              offset:
                description: "Number of reviews into the list that the response starts at"
                type: integer
              total_count:
                description: "Total number of reviews"
                type: integer
              items:
                description: "list of reviews"
                type: array
                items:
                  $ref: "#/definitions/Review"
        400:
          description: "Bad request. Invalid Book supplied"
        500:
          $ref: "#/definitions/500_error"
    post:
      summary: "Adds a review for a book"
      description: "Add a review for the book with given id"
      produces:
        - application/json
      parameters:
        - $ref: "#/parameters/Book_id"
        - $ref: "#/parameters/Review"
      responses:
        201:
          description: "Successfully added review"
          schema:
            $ref: "#/definitions/Review"
        500:
          $ref: "#/definitions/500_error"
parameters:
  limit:
    name: limit
    description: "Maximum number of items that will be returned. A value of zero will return zero items. The default value is 20, and the maximum limit allowed is 1000"
    in: query
    required: false
    default: 20
    type: integer
  offset:
    name: offset
    description: "Starting index of the items array that will be returned. By default it is zero, meaning that the returned items will start from the beginning."
    in: query
    required: false
    default: 0
    type: integer
  Book_id:
    in: path
    name: id
    description: "Unique book id"
    type: integer
    required: true
  Review_id:
    in: path
    name: review_id
    description: "Unique review id"
    type: integer
    required: true
  Review:
    name: review
    in: body
    schema:
      type: object
      required:
        - message
        - user
      properties:
        message:
          description: "Review message from user"
          type: string
        user:
          $ref: "#/definitions/User"
definitions:
  book_id:
    description: "Unique book id"
    type: string
  Book:
    type: object
    required:
      - id
      - title
      - author
      - links
    properties:
      id:
        $ref: "#/definitions/book_id"
      title:
        description: "Name of the book"
        type: string
      author:
        description: "Author of the book"
        type: string
      synopsis:
        description: "Brief summary of the book"
        type: string
      links:
        type: object
        required:
          - self
          - reservations
          - reviews
        properties:
          self:
            type: string
          reservations:
            type: string
          reviews:
            type: string
  Review:
    type: object
    required:
      - id
      - last_updated
      - message
      - user
      - book_id
      - links
    properties:
      id:
        description: "Unique review id"
        type: string
      last_updated:
        description: "UTC timestamp of when the review was last updated"
        type: string
        format: date-time
        example: "2020-04-26T08:05:52Z"
      message:
        description: "Review message from user"
        type: string
      user:
        $ref: "#/definitions/User"
      book_id:
        $ref: "#/definitions/book_id"
      links:
        type: object
        required:
          - self
          - book
        properties:
          self:
            type: string
          book:
            type: string
  User:
    description: "Reviewer details"
    type: object
    required:
      - forenames
      - surname
    properties:
      forenames:
        description: "Reviewer's forenames"
        type: string
      surname:
        description: "Reviewer's surnames"
        type: string
  Health:
    type: object
    properties:
      status:
        type: string
        description: "The status of the API"
        enum: ["OK", "WARNING", "CRITICAL"]
      version:
        type: object
        properties:
          build_time:
            type: string
            description: "The build date and time of the API"
            example: "2020-06-11T12:49:20+01:00"
          git_commit:
            type: string
            description: "The git commit hash of the API"
            example: "7c2febbf2b818175112478d4ffbadbee1b654f63"
          language:
            type: string
            description: "The programming language used to implement API"
            example: "go"
          language_version:
            type: string
            description: "The version of the programming language used to implement API"
            example: "go1.14.3"
          version:
            type: string
            description: "The version of API"
            example: "1.0.0"
      uptime:
        type: string
        description: "The uptime of API"
        example: "34516"
      start_time:
        type: string
        description: "The start date and time of API running"
        example: "2020-06-11T11:49:21.520922Z"
      checks:
        type: array
        items:
          $ref: '#/definitions/HealthChecker'
  HealthChecker:
    type: object
    properties:
      name:
        type: string
        description: "The name of external service used by API"
        enum: ["mongodb"]
      status:
        type: string
        description: "The status of the external service"
        enum: ["OK", "WARNING", "CRITICAL"]
      message:
        type: string
        description: "The message status of the external service"
        example: "mongodb is OK"
      last_checked:
        type: string
        description: "The last health check date and time of the external service"
        example: "2020-06-11T11:49:50.330089Z"
      last_success:
        type: string
        description: "The last successful health check date and time of the external service"
        example: "2020-06-11T11:49:50.330089Z"
      last_failure:
        type: string
        description: "The last failed health check date and time of the external service"
        example: null
  500_error:
    description: "Internal server error"