HTTP Verbs

This application tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage

GET

Used to retrieve resource(s).

POST

Used to create a new resource or execute and action.

DELETE

Used to delete a resource.

HTTP Status Codes

This application tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code Usage

200 OK

The request completed successfully.

201 Created

A new resource has been created successfully..

204 No Content

The request completed successfully, but there is no content included in the response.

400 Bad Request

The request was malformed. The response body will include an error providing further information.

404 Not Found

The requested resource did not exist.

Resources

Books

Creating a new Book

In order to create a book, the consumer needs to provide an isbn number, a a title and a description for the new book and POST them to /books. This will create a new book in the library’s collection.

Curl request
$ curl 'http://localhost:9091/books' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "id" : "61cfa02b-7199-47f4-b684-a1d8cade097e",
  "isbn" : "123-456789123",
  "title" : "Book title",
  "description" : "Book description",
  "authors" : [ "Author" ],
  "borrowed" : false,
  "borrowedBy" : null
}'
HTTP request
POST /books HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 216
Host: localhost:9091

{
  "id" : "61cfa02b-7199-47f4-b684-a1d8cade097e",
  "isbn" : "123-456789123",
  "title" : "Book title",
  "description" : "Book description",
  "authors" : [ "Author" ],
  "borrowed" : false,
  "borrowedBy" : null
}
HTTPie request
$ echo '{
  "id" : "61cfa02b-7199-47f4-b684-a1d8cade097e",
  "isbn" : "123-456789123",
  "title" : "Book title",
  "description" : "Book description",
  "authors" : [ "Author" ],
  "borrowed" : false,
  "borrowedBy" : null
}' | http POST 'http://localhost:9091/books' \
    'Accept:application/json' \
    'Content-Type:application/json'
HTTP response
HTTP/1.1 201 Created

Listing all existing Books

All existing books of the library’s collection can be retrieved with a GET request on the /books resource.

Curl request
$ curl 'http://localhost:9091/books' -i -X GET \
    -H 'Accept: application/json'
HTTPie request
$ http GET 'http://localhost:9091/books' \
    'Accept:application/json'
HTTP request
GET /books HTTP/1.1
Accept: application/json
Host: localhost:9091
HTTP response
HTTP/1.1 200 OK
Content-Length: 392
Content-Type: application/json;charset=UTF-8

[ {
  "id" : "b15edead-62e6-4a27-acf6-77e2f8899791",
  "isbn" : "123-456789123",
  "title" : "Book title",
  "description" : "Book description",
  "authors" : [ "Author" ],
  "borrowed" : true,
  "borrowedBy" : {
    "id" : "ef6f0d9a-a87e-459a-a88a-f6d93a80d5f3",
    "email" : "john.doe@example.com",
    "firstName" : "John",
    "lastName" : "Doe",
    "roles" : [ "LIBRARY_USER" ]
  }
} ]

Getting a Book

An existing book of the library’s collection can be retrieved with a GET request on the book’s /books/{id} resource.

Curl request
$ curl 'http://localhost:9091/books/b6fff565-f953-49a4-9847-2a6a0599d376' -i -X GET \
    -H 'Accept: application/json'
HTTPie request
$ http GET 'http://localhost:9091/books/b6fff565-f953-49a4-9847-2a6a0599d376' \
    'Accept:application/json'
HTTP request
GET /books/b6fff565-f953-49a4-9847-2a6a0599d376 HTTP/1.1
Accept: application/json
Host: localhost:9091
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 388

{
  "id" : "b6fff565-f953-49a4-9847-2a6a0599d376",
  "isbn" : "123-456789123",
  "title" : "Book title",
  "description" : "Book description",
  "authors" : [ "Author" ],
  "borrowed" : true,
  "borrowedBy" : {
    "id" : "3e63c37c-f6eb-4a02-93b6-e43041a4b0b5",
    "email" : "john.doe@example.com",
    "firstName" : "John",
    "lastName" : "Doe",
    "roles" : [ "LIBRARY_USER" ]
  }
}

Borrowing a Book

In order to borrow a book it has to (1) exist and (2) not already be borrowed by someone else. A book can be borrowed by providing a borrower as part of a POST request on the /books/{id}/borrow action resource:

Curl request
$ curl 'http://localhost:9091/books/98a5c985-3636-4d4c-b200-a9ab2bb2c5e8/borrow' -i -X POST \
    -H 'Accept: application/json'
HTTPie request
$ http POST 'http://localhost:9091/books/98a5c985-3636-4d4c-b200-a9ab2bb2c5e8/borrow' \
    'Accept:application/json'
HTTP request
POST /books/98a5c985-3636-4d4c-b200-a9ab2bb2c5e8/borrow HTTP/1.1
Accept: application/json
Host: localhost:9091
HTTP response

If the book was successfully borrowed, the response would be something like this:

HTTP/1.1 200 OK

Returning a Book

In order to return a book it has to (1) exist and (2) be borrowed by someone. A book can be returned sending an empty POST request to the /books/{id}/return action resource.

Curl request
$ curl 'http://localhost:9091/books/e785ecc1-04cd-4201-9864-3533882e372b/return' -i -X POST \
    -H 'Accept: application/json'
HTTPie request
$ http POST 'http://localhost:9091/books/e785ecc1-04cd-4201-9864-3533882e372b/return' \
    'Accept:application/json'
HTTP request
POST /books/e785ecc1-04cd-4201-9864-3533882e372b/return HTTP/1.1
Accept: application/json
Host: localhost:9091
HTTP response

If the book was successfully returned, the response would be something like this:

HTTP/1.1 200 OK

Deleting a Book

An existing book can be deleted with a DELETE request on the book’s /books/{id} resource.

Curl request
$ curl 'http://localhost:9091/books/d61ce729-253f-4d3a-a7e4-34c0ec06f19d' -i -X DELETE \
    -H 'Accept: application/json'
HTTPie request
$ http DELETE 'http://localhost:9091/books/d61ce729-253f-4d3a-a7e4-34c0ec06f19d' \
    'Accept:application/json'
HTTP request
DELETE /books/d61ce729-253f-4d3a-a7e4-34c0ec06f19d HTTP/1.1
Accept: application/json
Host: localhost:9091
HTTP response

Successful deletion is indicated with a response like this:

HTTP/1.1 200 OK

Users

Creating a new User

In order to create a user, the consumer needs to provide an email address, first name and last name for the new user and POST them to /users. This will create a new user in the user’s collection.

Curl request
$ curl 'http://localhost:9091/users' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "id" : "2810ba64-77d9-4c23-bdf7-b1ed6cdde4be",
  "email" : "john.doe@example.com",
  "firstName" : "John",
  "lastName" : "Doe",
  "roles" : [ "LIBRARY_USER" ],
  "password" : "secret"
}'
HTTPie request
$ echo '{
  "id" : "2810ba64-77d9-4c23-bdf7-b1ed6cdde4be",
  "email" : "john.doe@example.com",
  "firstName" : "John",
  "lastName" : "Doe",
  "roles" : [ "LIBRARY_USER" ],
  "password" : "secret"
}' | http POST 'http://localhost:9091/users' \
    'Accept:application/json' \
    'Content-Type:application/json'
HTTP request
POST /users HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 190
Host: localhost:9091

{
  "id" : "2810ba64-77d9-4c23-bdf7-b1ed6cdde4be",
  "email" : "john.doe@example.com",
  "firstName" : "John",
  "lastName" : "Doe",
  "roles" : [ "LIBRARY_USER" ],
  "password" : "secret"
}
HTTP response

Successful deletion is indicated with a response like this:

HTTP/1.1 200 OK

Listing all existing Users

All existing users of the user’s collection can be retrieved with a GET request on the /users resource:

Curl request
$ curl 'http://localhost:9091/users' -i -X GET \
    -H 'Accept: application/json'
HTTPie request
$ http GET 'http://localhost:9091/users' \
    'Accept:application/json'
HTTP request
GET /users HTTP/1.1
Accept: application/json
Host: localhost:9091
HTTP response

If there are any users the response would look something like this:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 169

[ {
  "id" : "89134056-cac4-4c5f-af05-9071855f36fb",
  "email" : "john.doe@example.com",
  "firstName" : "John",
  "lastName" : "Doe",
  "roles" : [ "LIBRARY_USER" ]
} ]

Getting a User

An existing user of the user’s collection can be retrieved with a GET request on the user’s /users/{id} resource:

Curl request
$ curl 'http://localhost:9091/users/1458538a-2c06-4b06-aaba-c11d1fc66f0e' -i -X GET \
    -H 'Accept: application/json'
HTTPie request
$ http GET 'http://localhost:9091/users/1458538a-2c06-4b06-aaba-c11d1fc66f0e' \
    'Accept:application/json'
HTTP request
GET /users/1458538a-2c06-4b06-aaba-c11d1fc66f0e HTTP/1.1
Accept: application/json
Host: localhost:9091
HTTP response

The response contains an available user like this:

HTTP/1.1 200 OK
Content-Length: 165
Content-Type: application/json;charset=UTF-8

{
  "id" : "1458538a-2c06-4b06-aaba-c11d1fc66f0e",
  "email" : "john.doe@example.com",
  "firstName" : "John",
  "lastName" : "Doe",
  "roles" : [ "LIBRARY_USER" ]
}

Deleting a User

An existing user can be deleted with a DELETE request on the user’s /users/{id} resource.

Curl request
$ curl 'http://localhost:9091/users/96f474e6-bb2f-4bd0-96b8-bda994abe8fe' -i -X DELETE \
    -H 'Accept: application/json'
HTTPie request
$ http DELETE 'http://localhost:9091/users/96f474e6-bb2f-4bd0-96b8-bda994abe8fe' \
    'Accept:application/json'
HTTP request
DELETE /users/96f474e6-bb2f-4bd0-96b8-bda994abe8fe HTTP/1.1
Accept: application/json
Host: localhost:9091
HTTP response

Successful deletion is indicated with a response like this:

HTTP/1.1 200 OK