1. Overview

Book API is a simple API for managing books and authors, it allows you to create, read, update and delete both books and authors. You can also link and unlink them, as well as retrieve authors of a book and vice versa.

1.1. Usage of HTTP Verbs

The following table describes how the Book API interprets the HTTP verbs.

Table 1. HTTP Verbs
HTTP Verb Usage

GET

GET is used to retrieve information.

POST

POST is used to create resources.

PUT

PUT is used to update or link resources.

DELETE

DELETE is used to delete or unlink resources.

1.2. Error Handling

1.2.1. Successful Requests

Successful requests return a response with HTTP status 200 (OK) or 201 (CREATED) or 204 (NO CONTENT). The response body contains a JSON structure, except for 204 status responses.

1.2.2. Validation Errors

POST requests against the Book API expect a JSON structure in the request body. PUT requests also expect a JSON structure, except for linking requests. GET, PUT, and DELETE requests expect to have a valid path variable. If the JSON structure contains invalid values, the API returns a response with HTTP status 422 (UNPROCESSABLE ENTITY) that includes an error JSON structure object with a message field and a possible array of errors.

1.2.3. General Errors

If an unexpected error occurs during the processing of a request, the Book API returns a response with HTTP status 500 (INTERNAL SERVER ERROR).

2. Resources

The Book API is guided by resources. The following sections describe the resources of the API.

2.1. Book

This section describes the book resource and its endpoints.

2.1.1. Structure

Path Type Description Constraints

title

String

Book’s title

Must not be blank

description

String

Book’s description

Must not be blank

isbn

String

Book’s ISBN

Must be a valid ISBN. Must not be blank

published

Boolean

Book’s publication state

Must not be null

2.1.2. Creating a book

Example request

POST /api/books HTTP/1.1
Content-Type: application/json
Content-Length: 118
Host: localhost:8080

{
  "title" : "The Lord of the Rings",
  "description" : "Fantasy",
  "isbn" : "9780544003415",
  "published" : true
}

Example response

HTTP/1.1 201 Created
Location: http://localhost:8080/api/books/31
Content-Type: application/json
Content-Length: 131

{
  "id" : 31,
  "title" : "The Lord of the Rings",
  "description" : "Fantasy",
  "isbn" : "9780544003415",
  "published" : true
}

2.1.3. Finding a book

Example request

GET /api/books/28 HTTP/1.1
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 131

{
  "id" : 28,
  "title" : "The Lord of the Rings",
  "description" : "Fantasy",
  "isbn" : "9780544003415",
  "published" : true
}

2.1.4. Finding all books

Query parameters

Parameter Description

page

The page to retrieve

size

Entries per page

sort

Field to be sorted

Example request

GET /api/books?page=0&size=2&sort=title HTTP/1.1
Host: localhost:8080

Example response

HTTP/1.1 200 OK
X-Total-Count: 4
Content-Type: application/json
Content-Length: 290

[ {
  "id" : 27,
  "title" : "The Chronicles of Narnia",
  "description" : "description again",
  "isbn" : "9780060847133",
  "published" : false
}, {
  "id" : 25,
  "title" : "The Hobbit",
  "description" : "Some detailed description",
  "isbn" : "9780008376055",
  "published" : false
} ]

2.1.5. Editing a book

Example request

PUT /api/books/21 HTTP/1.1
Content-Type: application/json
Content-Length: 126
Host: localhost:8080

{
  "title" : "The Hobbit",
  "description" : "Some detailed description",
  "isbn" : "9780008376055",
  "published" : false
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 139

{
  "id" : 21,
  "title" : "The Hobbit",
  "description" : "Some detailed description",
  "isbn" : "9780008376055",
  "published" : false
}

2.1.6. Deleting a book

Example request

DELETE /api/books/17 HTTP/1.1
Host: localhost:8080

Example response

HTTP/1.1 204 No Content

2.1.7. Finding book authors

Example request

GET /api/books/16/authors HTTP/1.1
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 313

[ {
  "id" : 23,
  "name" : "Erich Gamma",
  "email" : "erich@example.com"
}, {
  "id" : 24,
  "name" : "Richard Helm",
  "email" : "richard@example.com"
}, {
  "id" : 25,
  "name" : "Ralph Johnson",
  "email" : "ralph@example.com"
}, {
  "id" : 26,
  "name" : "John Vlissides",
  "email" : "john@example.com"
} ]

2.1.8. Adding an author to a book

Example request

PUT /api/books/14/authors/21 HTTP/1.1
Host: localhost:8080
Content-Type: application/x-www-form-urlencoded

Example response

HTTP/1.1 204 No Content

2.1.9. Removing an author from a book

Example request

DELETE /api/books/12/authors/19 HTTP/1.1
Host: localhost:8080

Example response

HTTP/1.1 204 No Content

2.2. Author

This section describes the author resource and its endpoints.

2.2.1. Structure

Path Type Description Constraints

name

String

Author’s name

Must not be blank

email

String

Author’s email

Must be a well-formed email address. Must not be blank

2.2.2. Creating an author

Example request

POST /api/authors HTTP/1.1
Content-Type: application/json
Content-Length: 66
Host: localhost:8080

{
  "name" : "J.R.R. Tolkien",
  "email" : "tolkien@example.com"
}

Example response

HTTP/1.1 201 Created
Location: http://localhost:8080/api/authors/17
Content-Type: application/json
Content-Length: 79

{
  "id" : 17,
  "name" : "J.R.R. Tolkien",
  "email" : "tolkien@example.com"
}

2.2.3. Finding an author

Example request

GET /api/authors/16 HTTP/1.1
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 79

{
  "id" : 16,
  "name" : "J.R.R. Tolkien",
  "email" : "tolkien@example.com"
}

2.2.4. Editing an author

Example request

PUT /api/authors/14 HTTP/1.1
Content-Type: application/json
Content-Length: 62
Host: localhost:8080

{
  "name" : "C.S. Lewis",
  "email" : "cslewis@example.com"
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 75

{
  "id" : 14,
  "name" : "C.S. Lewis",
  "email" : "cslewis@example.com"
}

2.2.5. Deleting an author

Example request

DELETE /api/authors/11 HTTP/1.1
Host: localhost:8080

Example response

HTTP/1.1 204 No Content

2.2.6. Finding author books

Example request

GET /api/authors/10/books HTTP/1.1
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 407

[ {
  "id" : 9,
  "title" : "The Lord of the Rings",
  "description" : "Fantasy",
  "isbn" : "9780544003415",
  "published" : true
}, {
  "id" : 10,
  "title" : "The Hobbit",
  "description" : "Some detailed description",
  "isbn" : "9780008376055",
  "published" : false
}, {
  "id" : 11,
  "title" : "The Silmarillion",
  "description" : "description",
  "isbn" : "9780618391110",
  "published" : true
} ]

2.2.7. Adding a book to an author

Example request

PUT /api/authors/9/books/8 HTTP/1.1
Host: localhost:8080
Content-Type: application/x-www-form-urlencoded

Example response

HTTP/1.1 204 No Content

2.2.8. Removing a book from an author

Example request

DELETE /api/authors/6/books/5 HTTP/1.1
Host: localhost:8080

Example response

HTTP/1.1 204 No Content