Book Swap API

API documentation

Return all books - optionally filtered

• URL

  /api/books

• Method:

  GET

• URL Params

  Required:

  There are no required URL params

  Optional:

  • claimed=0|1 - Either 1 or 0 to get only claimed/unclaimed books
  • search=string - A search term
  • genre=int - Filter results by genre id

  Example:

  /api/books?search=Peach&claimed=1&genre=1

• Success Response:

  • Code: 200
    Content:
    

{
    "data": [
        {
            "id": 2,
            "title": "foo",
            "author": "Test",
            "image": "https://via.placeholder.com/640x480.png/00cc88?text=iure",
            "genre": {
                "id": 1,
                "name": "Action"
            }
        }
    ],
    "message": "Books successfully retrieved"
}

• Error Response:

  • Code: 422 UNPROCESSABLE CONTENT
    Content:

    {
        "message": "The claimed field must be a number. (and 2 more errors)",
        "errors": {
            "claimed": [
                "The claimed field must be a number."
            ],
            "genre": [
                "The selected genre is invalid."
            ],
            "search": [
                "The search field must be a string."
            ]
        }
    }

Return a specific book

• URL

  /api/books/{id}

• Method:

  GET

• URL Params

  Required:

  There are no required URL params

  Optional:

  There are no optional URL params

  Example:

  /api/books/1

• Success Response:

  • Code: 200
    Content:
    

{
    "data": {
        "id": 1,
        "title": "Test",
        "author": "Test person",
        "blurb": "blurb",
        "claimed_by_name": "Ash",
        "image": "https://example.com/image.jpg",
        "page_count": 1000,
        "year": 1980,
        "genre": {
            "id": 1,
            "name": "Action"
        },
        "reviews": [
            {
                "id": 3,
                "name": "Ash",
                "rating": 1,
                "review": "bad"
            }
        ]
    },
    "message": "Book successfully found"
}

• Error Response:

  • Code: 404 NOT FOUND
    Content: {"message": "Book with id 999 not found"}

Claim book

• URL

  /books/claim/{id}

• Method:

  PUT

• Body Data

  Must be sent as JSON with the correct headers

  Required:

  {
    "email": "String",
    "name": "string"
  }

  Optional:

  There are no optional body parameters

  Example:

  /api/books/claim/1

• Success Response:

  • Code: 200 OK
    Content:
    

  {"message": "Book 1 was claimed"}

• Error Response:

  • Code: 404 NOT FOUND
    Content: {"message": "Book 10 was not found"}

  • Code: 400 BAD REQUEST
    Content: {"message": "Book 10 is already claimed"}

  • Code: 422 UNPROCESSABLE CONTENT
    Content:

  {
      "message": "The email field is required. (and 1 more error)",
      "errors": {
          "email": [
              "The email field is required."
          ],
          "name": [
              "The name field is required."
          ]
      }
  }

Return book

• URL

  /books/return/{id}

• Method:

  PUT

• URL Params

  Required:

  There are no required URL params

  Optional:

  There are no optional URL params

• Body Data

  Must be sent as JSON with the correct headers

  Required:

  {
    "email": "String",
  }

  Optional:

  There are no optional body parameters

  Example:

  /api/books/return/1

• Success Response:

  • Code: 200 OK
    Content:
    

  {"message": "Book 1 was returned"}

• Error Response:

  • Code: 404 NOT FOUND
    Content: {"message": "Book 10 was not found"}

  • Code: 400 BAD REQUEST
    Content: {"message": "Book 10 is not currently claimed"}

  • Code: 400 BAD REQUEST
    Content: {"message": "Book 1 was not returned. [email protected] did not claim this book."}

  • Code: 422 UNPROCESSABLE CONTENT
    Content:

  {
      "message": "The email field is required.",
      "errors": {
          "email": [
              "The email field is required."
          ]
      }
  }

  • Code: 500 INTERNAL SERVER ERROR
    Content: {"message": "Book 10 was not able to be returned"}

Add a new book

• URL

  /api/books

• Method:

  POST

• URL Params

  Required:

  There are no required URL params

  Optional:

  There are no optional URL params

• Body Data

  Must be sent as JSON with the correct headers

  Required:

  {
    "title": "String",
    "author": "string",
    "genre_id": integer
  }

  Optional:

  {
    "blurb": "string",
    "image": "url",
    "year": 1234
  }

  Example:

  /api/books

• Success Response:

  • Code: 201 CREATED
    Content:
    

  {"message": "Book created"}

  • Error Response:

    • Code: 500 INTERNAL SERVER ERROR
      Content: {"message": "Unexpected error occurred"}

    • Code: 422 UNPROCESSABLE CONTENT
      Content:

    {
        "message": "The title field is required. (and 2 more errors)",
        "errors": {
            "title": [
              "The title field is required."
            ],
            "author": [
              "The author field is required."
            ],
            "genre_id": [
              "The genre id field is required."
            ]
        }
    }

Delete a book

• URL

  /api/books/{id}

• Method:

  DELETE

• URL Params

  Required:

  There are no required URL params

  Optional:

  There are no optional URL params

• Body Data

  Must be sent as JSON with the correct headers

  Required:

  There are no required body parameters

  Optional:

  There are no required body parameters

  Example:

  /api/books/1

• Success Response:

  • Code: 200 OK
    Content:
    

  {"message": "Book 1 was deleted"}

  • Error Response:

    • Code: 404 NOT FOUND
      Content: {"message": "The title field is required. (and 2 more errors)"}

Add a new book review

• URL

  /api/reviews

• Method:

  POST

• URL Params

  Required:

  There are no required URL params

  Optional:

  There are no optional URL params

• Body Data

  Must be sent as JSON with the correct headers

  Required:

  {
    "name": "String",
    "rating": integer,
    "review": "string",
    "book_id": "int"
  }

  Note: rating must be an integer between 0 and 5

Optional:

There are no optional body parameters

Example:

/api/reviews

• Success Response:

  • Code: 201 CREATED
    Content:
    

  {"message": "Review created"}

• Error Response:

  • Code: 500 INTERNAL SERVER ERROR
    Content: {"message": "Unexpected error occurred"}

  • Code: 422 UNPROCESSABLE CONTENT
    Content:

    {      
        "message": "The name field is required. (and 3 more errors)",
        "errors": {
            "name": [
              "The name field is required."
            ],
            "rating": [
              "The rating field is required."
            ],
            "review": [
              "The review field is required."
            ],
            "book_id": [
              "The book id field is required."
            ]
        }
    }

Return all genres

• URL

  /api/genres

• Method:

  GET

• URL Params

  Required:

  There are no required URL params

  Optional:

  There are no optional URL params

  Example:

  /api/genres

• Success Response:

  • Code: 200
    Content:
    

{
    "data": [
        {
            "id": 1,
            "name": "Action"
        }
    ],
    "message": "Genres retrieved"
}

• Error Response:

  • Code: 500 INTERNAL SERVER ERROR
    Content: {"message": "Unexpected error occurred"}

Example fetch request

fetch('https://book-swap-api.dev.io-academy.uk/api/books', {
    mode: 'cors',
    headers: {
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
}).then(res => res.json())
    .then(data => {
        console.log(data)
    })