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.

PUT

Used to update an existing resource.

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.

401 Unauthorized

The request requires authentication. Only basic authentication is currently supported.

403 Forbidden

The request is authenticated but the authenticated user is not authorized to use the targeted resource.

404 Not Found

The requested resource did not exist.

HATEOAS

The REST API uses HATEOAS to include links to further resources or actions using hypermedia links.

Authentication

All REST API endpoints are secured and required authentication. Only basic authentication is supported.

Authorization: Basic dXNlcjpzZWNyZXQ=

Authorization

Book API

REST API Required Role

GET /books

 — 

GET /books/{identifier}

 — 

POST /books/{identifier}/borrow

LIBRARY_USER

POST /books/{identifier}/return

LIBRARY_USER

POST /books

LIBRARY_CURATOR

PUT /books/{identifier}

LIBRARY_CURATOR

DELETE /books/{identifier}

LIBRARY_CURATOR

User API

REST API Required Role

GET /users

LIBRARY_ADMIN

GET /users/{identifier}

LIBRARY_ADMIN

POST /users

LIBRARY_ADMIN

PUT /users/{identifier}

LIBRARY_ADMIN

DELETE /users/{identifier}

LIBRARY_ADMIN

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/library-server/books' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "identifier" : "93936326-62ba-471a-b685-08f7f39f95df",
  "isbn" : "1234566",
  "title" : "title",
  "description" : "description",
  "authors" : [ "Author" ],
  "borrowed" : false,
  "borrowedBy" : null,
  "links" : [ ]
}'
HTTP request
POST /library-server/books HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpzZWNyZXQ=
Host: localhost:9091
Content-Length: 225

{
  "identifier" : "93936326-62ba-471a-b685-08f7f39f95df",
  "isbn" : "1234566",
  "title" : "title",
  "description" : "description",
  "authors" : [ "Author" ],
  "borrowed" : false,
  "borrowedBy" : null,
  "links" : [ ]
}
HTTPie request
$ echo '{
  "identifier" : "93936326-62ba-471a-b685-08f7f39f95df",
  "isbn" : "1234566",
  "title" : "title",
  "description" : "description",
  "authors" : [ "Author" ],
  "borrowed" : false,
  "borrowedBy" : null,
  "links" : [ ]
}' | http --auth 'user:secret' POST 'http://localhost:9091/library-server/books' \
    'Content-Type:application/json'
HTTP response
HTTP/1.1 201 Created
Location: http://localhost:9091/library-server/books/93936326-62ba-471a-b685-08f7f39f95df
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 700

{
  "identifier" : "93936326-62ba-471a-b685-08f7f39f95df",
  "isbn" : "1234566",
  "title" : "title",
  "description" : "description",
  "authors" : [ "Author" ],
  "borrowed" : false,
  "_links" : {
    "self" : {
      "href" : "http://localhost:9091/library-server/books/93936326-62ba-471a-b685-08f7f39f95df"
    },
    "update" : {
      "href" : "http://localhost:9091/library-server/books/93936326-62ba-471a-b685-08f7f39f95df"
    },
    "borrow" : {
      "href" : "http://localhost:9091/library-server/books/93936326-62ba-471a-b685-08f7f39f95df/borrow"
    },
    "return" : {
      "href" : "http://localhost:9091/library-server/books/93936326-62ba-471a-b685-08f7f39f95df/return"
    }
  }
}

Update an existing Book

In order to update a book, the consumer needs to provide an isbn number, a a title and a description for the new book and PUT them to /books/{identifier}. This will update an existing book in the library’s collection.

Curl request
$ curl 'http://localhost:9091/library-server/books/081314cb-4abf-43e5-9b38-7d7261edb10d' -i -u 'user:secret' -X PUT \
    -H 'Content-Type: application/json' \
    -d '{
  "identifier" : "081314cb-4abf-43e5-9b38-7d7261edb10d",
  "isbn" : "9781617291203",
  "title" : "Spring in Action: Covers Spring 5",
  "description" : "Spring in Action, Fifth Edition is a hands-on guide to the Spring Framework, updated for version 4. It covers the latest features, tools, and practices including Spring MVC, REST, Security, Web Flow, and more. You'll move between short snippets and an ongoing example as you learn to build simple and efficient J2EE applications. Author Craig Walls has a special knack for crisp and entertaining examples that zoom in on the features and techniques you really need.",
  "authors" : [ "Craig Walls" ],
  "borrowed" : false,
  "borrowedBy" : null,
  "links" : [ ]
}'
HTTP request
PUT /library-server/books/081314cb-4abf-43e5-9b38-7d7261edb10d HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpzZWNyZXQ=
Host: localhost:9091
Content-Length: 718

{
  "identifier" : "081314cb-4abf-43e5-9b38-7d7261edb10d",
  "isbn" : "9781617291203",
  "title" : "Spring in Action: Covers Spring 5",
  "description" : "Spring in Action, Fifth Edition is a hands-on guide to the Spring Framework, updated for version 4. It covers the latest features, tools, and practices including Spring MVC, REST, Security, Web Flow, and more. You'll move between short snippets and an ongoing example as you learn to build simple and efficient J2EE applications. Author Craig Walls has a special knack for crisp and entertaining examples that zoom in on the features and techniques you really need.",
  "authors" : [ "Craig Walls" ],
  "borrowed" : false,
  "borrowedBy" : null,
  "links" : [ ]
}
HTTPie request
$ echo '{
  "identifier" : "081314cb-4abf-43e5-9b38-7d7261edb10d",
  "isbn" : "9781617291203",
  "title" : "Spring in Action: Covers Spring 5",
  "description" : "Spring in Action, Fifth Edition is a hands-on guide to the Spring Framework, updated for version 4. It covers the latest features, tools, and practices including Spring MVC, REST, Security, Web Flow, and more. You'll move between short snippets and an ongoing example as you learn to build simple and efficient J2EE applications. Author Craig Walls has a special knack for crisp and entertaining examples that zoom in on the features and techniques you really need.",
  "authors" : [ "Craig Walls" ],
  "borrowed" : false,
  "borrowedBy" : null,
  "links" : [ ]
}' | http --auth 'user:secret' PUT 'http://localhost:9091/library-server/books/081314cb-4abf-43e5-9b38-7d7261edb10d' \
    'Content-Type:application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 1193

{
  "identifier" : "081314cb-4abf-43e5-9b38-7d7261edb10d",
  "isbn" : "9781617291203",
  "title" : "Spring in Action: Covers Spring 5",
  "description" : "Spring in Action, Fifth Edition is a hands-on guide to the Spring Framework, updated for version 4. It covers the latest features, tools, and practices including Spring MVC, REST, Security, Web Flow, and more. You'll move between short snippets and an ongoing example as you learn to build simple and efficient J2EE applications. Author Craig Walls has a special knack for crisp and entertaining examples that zoom in on the features and techniques you really need.",
  "authors" : [ "Craig Walls" ],
  "borrowed" : false,
  "_links" : {
    "self" : {
      "href" : "http://localhost:9091/library-server/books/081314cb-4abf-43e5-9b38-7d7261edb10d"
    },
    "update" : {
      "href" : "http://localhost:9091/library-server/books/081314cb-4abf-43e5-9b38-7d7261edb10d"
    },
    "borrow" : {
      "href" : "http://localhost:9091/library-server/books/081314cb-4abf-43e5-9b38-7d7261edb10d/borrow"
    },
    "return" : {
      "href" : "http://localhost:9091/library-server/books/081314cb-4abf-43e5-9b38-7d7261edb10d/return"
    }
  }
}

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/library-server/books' -i -u 'user:secret' -X GET
HTTPie request
$ http --auth 'user:secret' GET 'http://localhost:9091/library-server/books'
HTTP request
GET /library-server/books HTTP/1.1
Authorization: Basic dXNlcjpzZWNyZXQ=
Host: localhost:9091
HTTP response
HTTP/1.1 200 OK
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 5655

{
  "_embedded" : {
    "bookResourceList" : [ {
      "identifier" : "f9bf70d6-e56d-4cab-be6b-294cd05f599f",
      "isbn" : "9780132350884",
      "title" : "Clean Code",
      "description" : "Even bad code can function. But if code isn’t clean, it can bring a development organization to its knees. Every year, countless hours and significant resources are lost because of poorly written code. But it doesn’t have to be that way. Noted software expert Robert C. Martin presents a revolutionary paradigm with Clean Code: A Handbook of Agile Software Craftsmanship . Martin has teamed up with his colleagues from Object Mentor to distill their best agile practice of cleaning code “on the fly” into a book that will instill within you the values of a software craftsman and make you a better programmer—but only if you work at it.",
      "authors" : [ "Bob C. Martin" ],
      "borrowed" : true,
      "borrowedBy" : {
        "identifier" : "c47641ee-e63c-4c13-8cd2-1c2490aee0b3",
        "email" : "bruce.wayne@example.com",
        "firstName" : "Bruce",
        "lastName" : "Wayne",
        "_links" : {
          "self" : {
            "href" : "http://localhost:9091/library-server/users/c47641ee-e63c-4c13-8cd2-1c2490aee0b3"
          }
        }
      },
      "_links" : {
        "self" : {
          "href" : "http://localhost:9091/library-server/books/f9bf70d6-e56d-4cab-be6b-294cd05f599f"
        },
        "update" : {
          "href" : "http://localhost:9091/library-server/books/f9bf70d6-e56d-4cab-be6b-294cd05f599f"
        },
        "borrow" : {
          "href" : "http://localhost:9091/library-server/books/f9bf70d6-e56d-4cab-be6b-294cd05f599f/borrow"
        },
        "return" : {
          "href" : "http://localhost:9091/library-server/books/f9bf70d6-e56d-4cab-be6b-294cd05f599f/return"
        }
      }
    }, {
      "identifier" : "3038627d-627e-448d-8422-0a5705c9e8f1",
      "isbn" : "9781449374648",
      "title" : "Cloud Native Java",
      "description" : "What separates the traditional enterprise from the likes of Amazon, Netflix, and Etsy? Those companies have refined the art of cloud native development to maintain their competitive edge and stay well ahead of the competition. This practical guide shows Java/JVM developers how to build better software, faster, using Spring Boot, Spring Cloud, and Cloud Foundry.",
      "authors" : [ "Josh Long", "Kenny Bastiani" ],
      "borrowed" : true,
      "borrowedBy" : {
        "identifier" : "69c10574-9064-40e4-85bd-5c68547f3f48",
        "email" : "bruce.banner@example.com",
        "firstName" : "Bruce",
        "lastName" : "Banner",
        "_links" : {
          "self" : {
            "href" : "http://localhost:9091/library-server/users/69c10574-9064-40e4-85bd-5c68547f3f48"
          }
        }
      },
      "_links" : {
        "self" : {
          "href" : "http://localhost:9091/library-server/books/3038627d-627e-448d-8422-0a5705c9e8f1"
        },
        "update" : {
          "href" : "http://localhost:9091/library-server/books/3038627d-627e-448d-8422-0a5705c9e8f1"
        },
        "borrow" : {
          "href" : "http://localhost:9091/library-server/books/3038627d-627e-448d-8422-0a5705c9e8f1/borrow"
        },
        "return" : {
          "href" : "http://localhost:9091/library-server/books/3038627d-627e-448d-8422-0a5705c9e8f1/return"
        }
      }
    }, {
      "identifier" : "081314cb-4abf-43e5-9b38-7d7261edb10d",
      "isbn" : "9781617291203",
      "title" : "Spring in Action: Covers Spring 5",
      "description" : "Spring in Action, Fifth Edition is a hands-on guide to the Spring Framework, updated for version 4. It covers the latest features, tools, and practices including Spring MVC, REST, Security, Web Flow, and more. You'll move between short snippets and an ongoing example as you learn to build simple and efficient J2EE applications. Author Craig Walls has a special knack for crisp and entertaining examples that zoom in on the features and techniques you really need.",
      "authors" : [ "Craig Walls" ],
      "borrowed" : false,
      "_links" : {
        "self" : {
          "href" : "http://localhost:9091/library-server/books/081314cb-4abf-43e5-9b38-7d7261edb10d"
        },
        "update" : {
          "href" : "http://localhost:9091/library-server/books/081314cb-4abf-43e5-9b38-7d7261edb10d"
        },
        "borrow" : {
          "href" : "http://localhost:9091/library-server/books/081314cb-4abf-43e5-9b38-7d7261edb10d/borrow"
        },
        "return" : {
          "href" : "http://localhost:9091/library-server/books/081314cb-4abf-43e5-9b38-7d7261edb10d/return"
        }
      }
    }, {
      "identifier" : "93936326-62ba-471a-b685-08f7f39f95df",
      "isbn" : "1234566",
      "title" : "title",
      "description" : "description",
      "authors" : [ "Author" ],
      "borrowed" : false,
      "_links" : {
        "self" : {
          "href" : "http://localhost:9091/library-server/books/93936326-62ba-471a-b685-08f7f39f95df"
        },
        "update" : {
          "href" : "http://localhost:9091/library-server/books/93936326-62ba-471a-b685-08f7f39f95df"
        },
        "borrow" : {
          "href" : "http://localhost:9091/library-server/books/93936326-62ba-471a-b685-08f7f39f95df/borrow"
        },
        "return" : {
          "href" : "http://localhost:9091/library-server/books/93936326-62ba-471a-b685-08f7f39f95df/return"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:9091/library-server/books"
    },
    "create" : {
      "href" : "http://localhost:9091/library-server/books"
    }
  }
}

Getting a Book

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

Curl request
$ curl 'http://localhost:9091/library-server/books/f9bf70d6-e56d-4cab-be6b-294cd05f599f' -i -u 'user:secret' -X GET
HTTPie request
$ http --auth 'user:secret' GET 'http://localhost:9091/library-server/books/f9bf70d6-e56d-4cab-be6b-294cd05f599f'
HTTP request
GET /library-server/books/f9bf70d6-e56d-4cab-be6b-294cd05f599f HTTP/1.1
Authorization: Basic dXNlcjpzZWNyZXQ=
Host: localhost:9091
HTTP response
HTTP/1.1 200 OK
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 1676

{
  "identifier" : "f9bf70d6-e56d-4cab-be6b-294cd05f599f",
  "isbn" : "9780132350884",
  "title" : "Clean Code",
  "description" : "Even bad code can function. But if code isn’t clean, it can bring a development organization to its knees. Every year, countless hours and significant resources are lost because of poorly written code. But it doesn’t have to be that way. Noted software expert Robert C. Martin presents a revolutionary paradigm with Clean Code: A Handbook of Agile Software Craftsmanship . Martin has teamed up with his colleagues from Object Mentor to distill their best agile practice of cleaning code “on the fly” into a book that will instill within you the values of a software craftsman and make you a better programmer—but only if you work at it.",
  "authors" : [ "Bob C. Martin" ],
  "borrowed" : true,
  "borrowedBy" : {
    "identifier" : "c47641ee-e63c-4c13-8cd2-1c2490aee0b3",
    "email" : "bruce.wayne@example.com",
    "firstName" : "Bruce",
    "lastName" : "Wayne",
    "_links" : {
      "self" : {
        "href" : "http://localhost:9091/library-server/users/c47641ee-e63c-4c13-8cd2-1c2490aee0b3"
      }
    }
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:9091/library-server/books/f9bf70d6-e56d-4cab-be6b-294cd05f599f"
    },
    "update" : {
      "href" : "http://localhost:9091/library-server/books/f9bf70d6-e56d-4cab-be6b-294cd05f599f"
    },
    "borrow" : {
      "href" : "http://localhost:9091/library-server/books/f9bf70d6-e56d-4cab-be6b-294cd05f599f/borrow"
    },
    "return" : {
      "href" : "http://localhost:9091/library-server/books/f9bf70d6-e56d-4cab-be6b-294cd05f599f/return"
    }
  }
}

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/{identifier}/borrow action resource:

Curl request
$ curl 'http://localhost:9091/library-server/books/f9bf70d6-e56d-4cab-be6b-294cd05f599f/borrow' -i -u 'user:secret' -X POST
HTTPie request
$ http --auth 'user:secret' POST 'http://localhost:9091/library-server/books/f9bf70d6-e56d-4cab-be6b-294cd05f599f/borrow'
HTTP request
POST /library-server/books/f9bf70d6-e56d-4cab-be6b-294cd05f599f/borrow HTTP/1.1
Authorization: Basic dXNlcjpzZWNyZXQ=
Host: localhost:9091
HTTP response

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

HTTP/1.1 200 OK
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 1676

{
  "identifier" : "f9bf70d6-e56d-4cab-be6b-294cd05f599f",
  "isbn" : "9780132350884",
  "title" : "Clean Code",
  "description" : "Even bad code can function. But if code isn’t clean, it can bring a development organization to its knees. Every year, countless hours and significant resources are lost because of poorly written code. But it doesn’t have to be that way. Noted software expert Robert C. Martin presents a revolutionary paradigm with Clean Code: A Handbook of Agile Software Craftsmanship . Martin has teamed up with his colleagues from Object Mentor to distill their best agile practice of cleaning code “on the fly” into a book that will instill within you the values of a software craftsman and make you a better programmer—but only if you work at it.",
  "authors" : [ "Bob C. Martin" ],
  "borrowed" : true,
  "borrowedBy" : {
    "identifier" : "c47641ee-e63c-4c13-8cd2-1c2490aee0b3",
    "email" : "bruce.wayne@example.com",
    "firstName" : "Bruce",
    "lastName" : "Wayne",
    "_links" : {
      "self" : {
        "href" : "http://localhost:9091/library-server/users/c47641ee-e63c-4c13-8cd2-1c2490aee0b3"
      }
    }
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:9091/library-server/books/f9bf70d6-e56d-4cab-be6b-294cd05f599f"
    },
    "update" : {
      "href" : "http://localhost:9091/library-server/books/f9bf70d6-e56d-4cab-be6b-294cd05f599f"
    },
    "borrow" : {
      "href" : "http://localhost:9091/library-server/books/f9bf70d6-e56d-4cab-be6b-294cd05f599f/borrow"
    },
    "return" : {
      "href" : "http://localhost:9091/library-server/books/f9bf70d6-e56d-4cab-be6b-294cd05f599f/return"
    }
  }
}

Returning a Book

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

Curl request
$ curl 'http://localhost:9091/library-server/books/f9bf70d6-e56d-4cab-be6b-294cd05f599f/return' -i -u 'user:secret' -X POST
HTTPie request
$ http --auth 'user:secret' POST 'http://localhost:9091/library-server/books/f9bf70d6-e56d-4cab-be6b-294cd05f599f/return'
HTTP request
POST /library-server/books/f9bf70d6-e56d-4cab-be6b-294cd05f599f/return HTTP/1.1
Authorization: Basic dXNlcjpzZWNyZXQ=
Host: localhost:9091
HTTP response

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

HTTP/1.1 200 OK
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 1676

{
  "identifier" : "f9bf70d6-e56d-4cab-be6b-294cd05f599f",
  "isbn" : "9780132350884",
  "title" : "Clean Code",
  "description" : "Even bad code can function. But if code isn’t clean, it can bring a development organization to its knees. Every year, countless hours and significant resources are lost because of poorly written code. But it doesn’t have to be that way. Noted software expert Robert C. Martin presents a revolutionary paradigm with Clean Code: A Handbook of Agile Software Craftsmanship . Martin has teamed up with his colleagues from Object Mentor to distill their best agile practice of cleaning code “on the fly” into a book that will instill within you the values of a software craftsman and make you a better programmer—but only if you work at it.",
  "authors" : [ "Bob C. Martin" ],
  "borrowed" : true,
  "borrowedBy" : {
    "identifier" : "c47641ee-e63c-4c13-8cd2-1c2490aee0b3",
    "email" : "bruce.wayne@example.com",
    "firstName" : "Bruce",
    "lastName" : "Wayne",
    "_links" : {
      "self" : {
        "href" : "http://localhost:9091/library-server/users/c47641ee-e63c-4c13-8cd2-1c2490aee0b3"
      }
    }
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:9091/library-server/books/f9bf70d6-e56d-4cab-be6b-294cd05f599f"
    },
    "update" : {
      "href" : "http://localhost:9091/library-server/books/f9bf70d6-e56d-4cab-be6b-294cd05f599f"
    },
    "borrow" : {
      "href" : "http://localhost:9091/library-server/books/f9bf70d6-e56d-4cab-be6b-294cd05f599f/borrow"
    },
    "return" : {
      "href" : "http://localhost:9091/library-server/books/f9bf70d6-e56d-4cab-be6b-294cd05f599f/return"
    }
  }
}

Deleting a Book

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

Curl request
$ curl 'http://localhost:9091/library-server/books/02c3d1fb-ca32-46bd-818f-704012b3fe9c' -i -u 'user:secret' -X DELETE
HTTPie request
$ http --auth 'user:secret' DELETE 'http://localhost:9091/library-server/books/02c3d1fb-ca32-46bd-818f-704012b3fe9c'
HTTP request
DELETE /library-server/books/02c3d1fb-ca32-46bd-818f-704012b3fe9c HTTP/1.1
Authorization: Basic dXNlcjpzZWNyZXQ=
Host: localhost:9091
HTTP response

Successful deletion is indicated with a response like this:

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

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/library-server/users' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "identifier" : "3d788f67-3ce7-45f2-a9a2-a9dddbb28f30",
  "email" : "test@example.com",
  "firstName" : "test",
  "lastName" : "first",
  "password" : "mycoolpassword4tests",
  "roles" : [ "LIBRARY_USER" ],
  "links" : [ ]
}'
HTTPie request
$ echo '{
  "identifier" : "3d788f67-3ce7-45f2-a9a2-a9dddbb28f30",
  "email" : "test@example.com",
  "firstName" : "test",
  "lastName" : "first",
  "password" : "mycoolpassword4tests",
  "roles" : [ "LIBRARY_USER" ],
  "links" : [ ]
}' | http POST 'http://localhost:9091/library-server/users' \
    'Content-Type:application/json'
HTTP request
POST /library-server/users HTTP/1.1
Content-Type: application/json
Host: localhost:9091
Content-Length: 227

{
  "identifier" : "3d788f67-3ce7-45f2-a9a2-a9dddbb28f30",
  "email" : "test@example.com",
  "firstName" : "test",
  "lastName" : "first",
  "password" : "mycoolpassword4tests",
  "roles" : [ "LIBRARY_USER" ],
  "links" : [ ]
}
HTTP response

Successful creation is indicated with a response like this:

HTTP/1.1 201 Created
Location: http://localhost:9091/library-server/users/3d788f67-3ce7-45f2-a9a2-a9dddbb28f30
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 277

{
  "identifier" : "3d788f67-3ce7-45f2-a9a2-a9dddbb28f30",
  "email" : "test@example.com",
  "firstName" : "test",
  "lastName" : "first",
  "_links" : {
    "self" : {
      "href" : "http://localhost:9091/library-server/users/3d788f67-3ce7-45f2-a9a2-a9dddbb28f30"
    }
  }
}

Update an existing User

In order to update an existing user, the consumer needs to provide an email address, first name and last name for the existing user and PUT them to /users/{identifier}. This will update the existing user in the user’s collection.

Curl request
$ curl 'http://localhost:9091/library-server/users/40c5ad0d-41f7-494b-8157-33fad16012aa' -i -X PUT \
    -H 'Content-Type: application/json' \
    -d '{
  "identifier" : "40c5ad0d-41f7-494b-8157-33fad16012aa",
  "email" : "curator@example.com",
  "firstName" : "Library",
  "lastName" : "Curator",
  "password" : "curator_newpassword!",
  "roles" : [ "LIBRARY_USER", "LIBRARY_CURATOR" ],
  "links" : [ ]
}'
HTTPie request
$ echo '{
  "identifier" : "40c5ad0d-41f7-494b-8157-33fad16012aa",
  "email" : "curator@example.com",
  "firstName" : "Library",
  "lastName" : "Curator",
  "password" : "curator_newpassword!",
  "roles" : [ "LIBRARY_USER", "LIBRARY_CURATOR" ],
  "links" : [ ]
}' | http PUT 'http://localhost:9091/library-server/users/40c5ad0d-41f7-494b-8157-33fad16012aa' \
    'Content-Type:application/json'
HTTP request
PUT /library-server/users/40c5ad0d-41f7-494b-8157-33fad16012aa HTTP/1.1
Content-Type: application/json
Host: localhost:9091
Content-Length: 254

{
  "identifier" : "40c5ad0d-41f7-494b-8157-33fad16012aa",
  "email" : "curator@example.com",
  "firstName" : "Library",
  "lastName" : "Curator",
  "password" : "curator_newpassword!",
  "roles" : [ "LIBRARY_USER", "LIBRARY_CURATOR" ],
  "links" : [ ]
}
HTTP response

Successful update is indicated with a response like this:

HTTP/1.1 200 OK
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 285

{
  "identifier" : "40c5ad0d-41f7-494b-8157-33fad16012aa",
  "email" : "curator@example.com",
  "firstName" : "Library",
  "lastName" : "Curator",
  "_links" : {
    "self" : {
      "href" : "http://localhost:9091/library-server/users/40c5ad0d-41f7-494b-8157-33fad16012aa"
    }
  }
}

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/library-server/users' -i -X GET
HTTPie request
$ http GET 'http://localhost:9091/library-server/users'
HTTP request
GET /library-server/users HTTP/1.1
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
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 1448

[ {
  "identifier" : "2cdd02c8-4fc0-4dc0-8e6a-00eeb2fa7c94",
  "email" : "service-account-library-client@placeholder.org",
  "firstName" : "n/a",
  "lastName" : "n/a",
  "links" : [ {
    "rel" : "self",
    "href" : "http://localhost:9091/library-server/users/2cdd02c8-4fc0-4dc0-8e6a-00eeb2fa7c94"
  } ]
}, {
  "identifier" : "c47641ee-e63c-4c13-8cd2-1c2490aee0b3",
  "email" : "bruce.wayne@example.com",
  "firstName" : "Bruce",
  "lastName" : "Wayne",
  "links" : [ {
    "rel" : "self",
    "href" : "http://localhost:9091/library-server/users/c47641ee-e63c-4c13-8cd2-1c2490aee0b3"
  } ]
}, {
  "identifier" : "69c10574-9064-40e4-85bd-5c68547f3f48",
  "email" : "bruce.banner@example.com",
  "firstName" : "Bruce",
  "lastName" : "Banner",
  "links" : [ {
    "rel" : "self",
    "href" : "http://localhost:9091/library-server/users/69c10574-9064-40e4-85bd-5c68547f3f48"
  } ]
}, {
  "identifier" : "0d2c04f1-e25f-41b5-b4cd-3566a081200f",
  "email" : "clark.kent@example.com",
  "firstName" : "Clark",
  "lastName" : "Kent",
  "links" : [ {
    "rel" : "self",
    "href" : "http://localhost:9091/library-server/users/0d2c04f1-e25f-41b5-b4cd-3566a081200f"
  } ]
}, {
  "identifier" : "3d788f67-3ce7-45f2-a9a2-a9dddbb28f30",
  "email" : "test@example.com",
  "firstName" : "test",
  "lastName" : "first",
  "links" : [ {
    "rel" : "self",
    "href" : "http://localhost:9091/library-server/users/3d788f67-3ce7-45f2-a9a2-a9dddbb28f30"
  } ]
} ]

Getting a User

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

Curl request
$ curl 'http://localhost:9091/library-server/users/c47641ee-e63c-4c13-8cd2-1c2490aee0b3' -i -X GET
HTTPie request
$ http GET 'http://localhost:9091/library-server/users/c47641ee-e63c-4c13-8cd2-1c2490aee0b3'
HTTP request
GET /library-server/users/c47641ee-e63c-4c13-8cd2-1c2490aee0b3 HTTP/1.1
Host: localhost:9091
HTTP response

The response contains an available user like this:

HTTP/1.1 200 OK
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 285

{
  "identifier" : "c47641ee-e63c-4c13-8cd2-1c2490aee0b3",
  "email" : "bruce.wayne@example.com",
  "firstName" : "Bruce",
  "lastName" : "Wayne",
  "_links" : {
    "self" : {
      "href" : "http://localhost:9091/library-server/users/c47641ee-e63c-4c13-8cd2-1c2490aee0b3"
    }
  }
}

Deleting a User

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

Curl request
$ curl 'http://localhost:9091/library-server/users/40c5ad0d-41f7-494b-8157-33fad16012aa' -i -X DELETE
HTTPie request
$ http DELETE 'http://localhost:9091/library-server/users/40c5ad0d-41f7-494b-8157-33fad16012aa'
HTTP request
DELETE /library-server/users/40c5ad0d-41f7-494b-8157-33fad16012aa HTTP/1.1
Host: localhost:9091
HTTP response

Successful deletion is indicated with a response like this:

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY