API — Book Operations

Each book must consists of multiple parts of information. Here’s the rules:

A book must have a book genre at all times
A book can only have one book genre at any given time
A book must have at least one author
A book can have multiple authors

Based on this let’s dive into all book related endpoints and how to use them.

Create an Author

This endpoint provides functionality to create a new author in the system.

Perform a POST request:

curl --location 'http://localhost:8080/authors' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....' \
--data '{
  "firstName": "Walther",
  "lastName": "Smulders"
}'

This should provide a response like:

{
  "authorID": "b87661db-ccdf-4f19-8347-7162a111eff8",
  "firstName": "Walther",
  "lastName": "Smulders"
}

Take note of the authorID field and copy that value, the subsequent sections will make use of this value as a path parameter.

Get all Authors

This endpoint provides functionality to retrieve all authors found in the system. If there are no authors found an empty array will be returned: [ ]

Perform a GET request:

curl --location 'http://localhost:8080/authors' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....'

This should provide a response like:

[
  {
    "authorID": "b87661db-ccdf-4f19-8347-7162a111eff8",
    "firstName": "Walther",
    "lastName": "Smulders"
  }
]

This response includes the author we just created.

Get Author by AuthorID

This endpoint provides functionality to retrieve a single author by making use of the authorID value. This value is passed along to the back-end application by the means of a path parameter value and serves as the lookup key.

Perform a GET request:

curl --location 'http://localhost:8080/authors/b87661db-ccdf-4f19-8347-7162a111eff8' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....'

This should provide a response like:

{
  "authorID": "b87661db-ccdf-4f19-8347-7162a111eff8",
  "firstName": "Walther",
  "lastName": "Smulders"
}

This response correlates with the authorID supplied in the path parameter.

Update Author by AuthorID

This endpoint provides functionality to update an existing author by making use of the authorID value. This value is passed along to the back-end application by the means of a path parameter value and serves as the lookup key.

Perform a PUT request:

curl --location --request PUT 'http://localhost:8080/authors/b87661db-ccdf-4f19-8347-7162a111eff8' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....' \
--data '{
  "firstName": "Walther",
  "lastName": "Smulders",
  "additionalName": "John"
}'

There is no response body, and the HTTP status code is HTTP 204 No Content
You can run the Get Author by AuthorID request again to see the difference. The response will show the updated additionalName value which has been added, the new value being John.

Create Book with Authors

In order to create a new book, at least one authorID must be included in the request since a book must always have at least one author associated with it. You will also need to include a valid bookGenreID since a book must always have a book genre associated with it.

This endpoint provides functionality to create a new book. As can be seen in the request body below, functionality allows to include multiple authorIDs so you don’t have to add authors one-by-one.

Perform a POST request:

curl --location 'http://localhost:8080/books' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....' \
--data '{
  "authorIDs": [
    "b87661db-ccdf-4f19-8347-7162a111eff8"
  ],
  "bookGenreID": "e450228e-1a30-4b79-9b37-4a1ba7eb6948",
  "book": {
    "isbn": "978-1-1242-4798-4",
    "title": "My Awesome Book",
    "pages": 500,
    "plot": "This is a plot",
    "cover": "cover.jpg",
    "datePublished": "2022-08-29"
  }
}'

This should provide a response like:

{
  "bookID": "79b7d1a7-9ef5-461b-aac2-4b9db94a8d2c",
  "title": "My Awesome Book",
  "isbn": "978-1-1242-4798-4",
  "pages": 500,
  "plot": "This is a plot",
  "cover": "cover.jpg",
  "datePublished": "2022-08-29",
  "dateAdded": "2024-05-15T23:39:33.463158",
  "dateUpdated": "2024-05-15T23:39:33.463169",
  "authors": [
    {
      "authorID": "b87661db-ccdf-4f19-8347-7162a111eff8",
      "firstName": "Walther",
      "lastName": "Smulders",
      "additionalName": "John"
    }
  ],
  "genreBook": {
    "bookGenreID": "e450228e-1a30-4b79-9b37-4a1ba7eb6948",
    "genre": "Professional & Technical",
    "subGenre": "Programming"
  }
}

Get Books with Links

A book has certain “links” or associations. These links are: a book genre item and author items.

This endpoint provides functionality to retrieve all the books in the system with their associated links. If there are no books found then an empty array will be returned: [ ]

Perform a GET request:

curl --location 'http://localhost:8080/books/links' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....'

This should provide a response like:

[
  {
    "bookID": "79b7d1a7-9ef5-461b-aac2-4b9db94a8d2c",
    "title": "My Awesome Book",
    "isbn": "978-1-1242-4798-4",
    "pages": 500,
    "plot": "This is a plot",
    "cover": "cover.jpg",
    "datePublished": "2022-08-29",
    "dateAdded": "2024-05-15T23:39:33.463158",
    "dateUpdated": "2024-05-15T23:39:33.463169",
    "authors": [
      {
        "authorID": "b87661db-ccdf-4f19-8347-7162a111eff8",
        "firstName": "Walther",
        "lastName": "Smulders",
        "additionalName": "John"
      }
    ],
    "genreBook": {
      "bookGenreID": "e450228e-1a30-4b79-9b37-4a1ba7eb6948",
      "genre": "Professional & Technical",
      "subGenre": "Programming"
    }
  }
]

This response will provide all books in the system with all related information. This includes all author information as well as book genre information.

Get all Books

This endpoint will retrieve all the book items found in the system. Note that this endpoint does not include the associated links for each book, but rather only contains the “core” details of each book item.

If there are no books found in the system, an empty array will be returned: [ ]

Perform a GET request:

curl --location 'http://localhost:8080/books' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....'

This should provide a response like:

[
  {
    "bookID": "79b7d1a7-9ef5-461b-aac2-4b9db94a8d2c",
    "title": "My Awesome Book",
    "isbn": "978-1-1242-4798-4",
    "pages": 500,
    "plot": "This is a plot",
    "cover": "cover.jpg",
    "datePublished": "2022-08-29",
    "dateAdded": "2024-05-15T23:39:33.463158",
    "dateUpdated": "2024-05-15T23:39:33.463169"
  }
]

This response will return all books but only include the book’s core information. The book genre and author information is excluded.

Get Book by BookID

This endpoint provides functionality to retrieve a specific book by making use of the bookID value as the lookup key. The bookID value is passed along to the back-end application by the means of a path parameter variable.

Perform a GET request:

curl --location 'http://localhost:8080/books/79b7d1a7-9ef5-461b-aac2-4b9db94a8d2c' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....'

This should provide a response like:

{
  "bookID": "79b7d1a7-9ef5-461b-aac2-4b9db94a8d2c",
  "title": "My Awesome Book",
  "isbn": "978-1-1242-4798-4",
  "pages": 500,
  "plot": "This is a plot",
  "cover": "cover.jpg",
  "datePublished": "2022-08-29",
  "dateAdded": "2024-05-15T23:39:33.463158",
  "dateUpdated": "2024-05-15T23:39:33.463169"
}

This response will return all books but only include the book’s core information. The book genre and author information is excluded.

Get Book with Links by BookID

This endpoint provides functionality to retrieve a specific book’s details along with its associated links by making use of the bookID value as the lookup key. The bookID value is passed along to the back-end application by the means of a path parameter variable.

Perform a GET request:

curl --location 'http://localhost:8080/books/79b7d1a7-9ef5-461b-aac2-4b9db94a8d2c/links' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....'

This should provide a response like:

{
  "bookID": "79b7d1a7-9ef5-461b-aac2-4b9db94a8d2c",
  "title": "My Awesome Book",
  "isbn": "978-1-1242-4798-4",
  "pages": 500,
  "plot": "This is a plot",
  "cover": "cover.jpg",
  "datePublished": "2022-08-29",
  "dateAdded": "2024-05-15T23:39:33.463158",
  "dateUpdated": "2024-05-15T23:39:33.463169",
  "authors": [
    {
      "authorID": "b87661db-ccdf-4f19-8347-7162a111eff8",
      "firstName": "Walther",
      "lastName": "Smulders",
      "additionalName": "John"
    }
  ],
  "genreBook": {
    "bookGenreID": "e450228e-1a30-4b79-9b37-4a1ba7eb6948",
    "genre": "Professional & Technical",
    "subGenre": "Programming"
  }
}

This response returns a single book item based on the bookID supplied with all links which includes the author information as well as the book genre information.

Get Authors with Books

This endpoint provides functionality to retrieve all authors in the system along with all of their associated books. The book item details will only include the book’s core details.

Perform a GET request:

curl --location 'http://localhost:8080/authors/books' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....'

This should provide a response like:

[
  {
    "authorID": "b87661db-ccdf-4f19-8347-7162a111eff8",
    "firstName": "Walther",
    "lastName": "Smulders",
    "additionalName": "John",
    "books": [
      {
        "bookID": "79b7d1a7-9ef5-461b-aac2-4b9db94a8d2c",
        "title": "My Awesome Book",
        "isbn": "978-1-1242-4798-4",
        "pages": 500,
        "plot": "This is a plot",
        "cover": "cover.jpg",
        "datePublished": "2022-08-29",
        "dateAdded": "2024-05-15T23:39:33.463158",
        "dateUpdated": "2024-05-15T23:39:33.463169"
      }
    ]
  }
]

This response returns all the books linked to all authors in the system.

Get Author with Books by AuthorID

This endpoint provides functionality to retrieve all the books associated with a specific author. The authorID value is used as the lookup key. The authorID value is passed along to the back-end application by the means of a path parameter variable.

Perform a GET request:

curl --location 'http://localhost:8080/authors/b87661db-ccdf-4f19-8347-7162a111eff8/books' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....'

This should provide a response like:

{
  "authorID": "b87661db-ccdf-4f19-8347-7162a111eff8",
  "firstName": "Walther",
  "lastName": "Smulders",
  "additionalName": "John",
  "books": [
    {
      "bookID": "79b7d1a7-9ef5-461b-aac2-4b9db94a8d2c",
      "title": "My Awesome Book",
      "isbn": "978-1-1242-4798-4",
      "pages": 500,
      "plot": "This is a plot",
      "cover": "cover.jpg",
      "datePublished": "2022-08-29",
      "dateAdded": "2024-05-15T23:39:33.463158",
      "dateUpdated": "2024-05-15T23:39:33.463169"
    }
  ]
}

This response returns all the books for a single author based on the authorID value in the path parameter.

Update Book by BookID

This endpoint provides functionality to update an existing book by making use of the bookID value. The bookID value is used as the lookup key and passed along to the back-end application by the means of a path parameter variable.

Note the reduced allowable property values in the request body. Not all properties or a book’s core details are updatable.

Perform a PUT request:

curl --location --request PUT 'http://localhost:8080/books/79b7d1a7-9ef5-461b-aac2-4b9db94a8d2c' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....' \
--data '{
  "title": "My Book",
  "plot": "This is an updated plot",
  "isbn": "978-1-1242-4798-4",
  "pages": 400,
  "cover": "cover.jpg",
  "datePublished": "2023-03-23"
}'

There is no response body, and the HTTP status code is HTTP 204 No Content
You can run the Get Book by BookID request again to see the difference. The response will show the updated book information as reflected in the request body above.

Update Book Genre

This endpoint provides functionality to update a specific book’s genre association. There is no request body needed as the values will be picked up from the request URI.

The bookID and bookGenreID values are used as lookup and replacement values. They are passed along to the back-end application by the means of path parameter variables.

Perform a PUT request:

curl --location --request PUT 'http://localhost:8080/books/79b7d1a7-9ef5-461b-aac2-4b9db94a8d2c/genres/c58e0c88-aa81-4442-a165-a8860de86069' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....'

There is no response body, and the HTTP status code is HTTP 204 No Content
You can run the Get Book with Links by BookID request again to see the difference. The response will show the updated book information.

Add Author to Book

Currently, only one author exists (the one created earlier). Let’s create another one and add the newly created one to the book as well. This means this book will have two authors after the request is completed.

This endpoint provides functionality to add a single author to an existing book item. This is done by making use of the bookID and authorID values as both lookup and addition values respectively. They are passed along to the back-end application by the means of path parameter variables.

Perform a POST request to create another author:

curl --location 'http://localhost:8080/authors' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....' \
--data '{
  "firstName": "James",
  "lastName": "Small"
}'

This should provide a response like:

{
  "authorID": "fdabc0c4-9ecf-4bee-a818-f8f0b655c389",
  "firstName": "James",
  "lastName": "Small"
}

Take note of the authorID field and copy that value, the subsequent steps will make use of this value as a path parameter.

Perform a PUT request to add an additional author to the book:

curl --location --request PUT 'http://localhost:8080/books/79b7d1a7-9ef5-461b-aac2-4b9db94a8d2c/authors/fdabc0c4-9ecf-4bee-a818-f8f0b655c389' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....'

There is no response body, and the HTTP status code is HTTP 204 No Content

Run the Get Book with Links by BookID request again to see the difference

{
  "bookID": "79b7d1a7-9ef5-461b-aac2-4b9db94a8d2c",
  "title": "My Book",
  "isbn": "978-1-1242-4798-4",
  "pages": 400,
  "plot": "This is an updated plot",
  "cover": "cover.jpg",
  "datePublished": "2023-03-23",
  "dateAdded": "2024-05-15T23:39:33.463158",
  "dateUpdated": "2024-05-16T00:01:29.964363",
  "authors": [
    {
      "authorID": "b87661db-ccdf-4f19-8347-7162a111eff8",
      "firstName": "Walther",
      "lastName": "Smulders",
      "additionalName": "John"
    },
    {
      "authorID": "fdabc0c4-9ecf-4bee-a818-f8f0b655c389",
      "firstName": "James",
      "lastName": "Small"
    }
  ],
  "genreBook": {
    "bookGenreID": "c58e0c88-aa81-4442-a165-a8860de86069",
    "genre": "Arts & Entertainment",
    "subGenre": "Art & Architecture"
  }
}

You can see from the response above that the book contains all the updated information, including the genre change, and additional author which we added.

Remove Author from Book

This endpoint provides functionality to remove an author from an existing book. Keep in mind that you will note be able to remove an author from any book if that author is the only author associated with that specific book. A book must have at least one author associated with it.

The bookID value is used as the lookup value. The authorID value is used as the value to be removed from the association. They are passed along to the back-end application by the means of path parameter variables.

Perform a DELETE request:

curl --location --request DELETE 'http://localhost:8080/books/79b7d1a7-9ef5-461b-aac2-4b9db94a8d2c/authors/fdabc0c4-9ecf-4bee-a818-f8f0b655c389' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....'

There is no response body, and the HTTP status code is HTTP 204 No Content

Run the Get Book with Links by BookID request again to see the difference

{
  "bookID": "79b7d1a7-9ef5-461b-aac2-4b9db94a8d2c",
  "title": "My Book",
  "isbn": "978-1-1242-4798-4",
  "pages": 400,
  "plot": "This is an updated plot",
  "cover": "cover.jpg",
  "datePublished": "2023-03-23",
  "dateAdded": "2024-05-15T23:39:33.463158",
  "dateUpdated": "2024-05-16T00:01:29.964363",
  "authors": [
    {
      "authorID": "b87661db-ccdf-4f19-8347-7162a111eff8",
      "firstName": "Walther",
      "lastName": "Smulders",
      "additionalName": "John"
    }
  ],
  "genreBook": {
    "bookGenreID": "c58e0c88-aa81-4442-a165-a8860de86069",
    "genre": "Arts & Entertainment",
    "subGenre": "Art & Architecture"
  }
}

As can be seen in the response above, the author has been removed.

Summary

Endpoints covered in this guide are as follows:

POST /authors
- Create a new author
GET /authors
- Retrieve all authors in the system
GET /authors/<authorID>
- Get a specific author by making use of the authorID value
PUT /authors/<authorID>
- Update a specific author by making use of the authorID value
POST /books
- Create a book with Authors
GET /books/links
- Retrieve all books in the system along with their associated links
GET /books
- Retrieve all books in the system with only the book’s core values
GET /books/<bookID>
- Get a specific book by making use of the bookID value
GET /books/<bookID>/links
- Get a specific book along with its associated links by making use of the bookID value
GET /authors/books
- Retrieve all authors in the system along with their associated books
GET /authors/<authorID>/books
- Get a single author and its associated books by making use of the authorID value
PUT /books/<bookID>
- Update a specific book by making use of the bookID value
PUT /books/<bookID>/genres/<bookGenreID>
- Update a specific book’s genre by making use of both the bookID and bookGenreID values
PUT /books/<bookID>/authors/<authorID>
- Add an author to an existing book by making use of both the bookID and the authorID values
DELETE /books/<bookID>/authors/<authorID>
- Remove an author from an existing book by making use of both the bookID and the authorID values