People Simple Preferences

RESTful API to manage personal info - name & age, and personal preferences - favorite food & color.

The project uses the following technologies:

web/REST: Grizzly, Jersey
marshalling: GSON and JAXB
persistence: Hibernate, SQLite
building: Maven
testing: JUnit, JBehave
documenting: Swagger.io

Install

mvn install

Details

Implemented date of birth instead of age, because age is dynamic value. But "age" also present in model as transient field - it's read-only & auto-calculated from a date of birth.

Implemented multiple preferences for color & food. Color preferences are sub-set of pre-defined colors represented by enum. Food preferences are user-generated.

Added constraint for uniqueness of first name + last name + date of birth.

Try it!

Run the web app (for dev/test only):

mvn clean test  # run just once
mvn exec:java

JSON or XML

By default, all results will be returned in JSON format. You can manage response media type by implicitly adding -H 'Accept: application/json' (that's for curl). To get data in XML media format, use -H 'Accept: application/xml'.

To submit data, you should always provide Content-Type header (there are no defaults for it). To send data in JSON, use -H 'Content-Type: application/json'. To send data in XML, use -H 'Content-Type: application/xml'.

People list

Get people list:

curl -i http://localhost:8080/preferences/people

To see all possible RESTful options for /preferences/people, use -X OPTIONS (it'll show options in WADL format).

Search the people list:

curl -i http://localhost:8080/preferences/people/search?lastName=Ivanov

You can search by firstName and/or lastName.

Create new person:

curl -i -X POST -H 'Content-Type: application/json' -d '{"firstName": "John", "lastName": "Smith", "dateOfBirth": "1985-12-18", "favoriteColor": ["YELLOW"], "favoriteFood": [{"name": "chocolate"}]}' http://localhost:8080/preferences/people

You can send data in XML format too:

curl -i -X POST -H 'Content-Type: application/xml' -d '<person><id>1</id><firstName>Petr</firstName><lastName>Petrov</lastName><dateOfBirth>1985-12-18</dateOfBirth><favoriteFood><food><name>chocolate</name></food><food><name>banana</name></food></favoriteFood></person>' http://localhost:8080/preferences/people

If the person John Smith (1985-12-18) already exists, there will be HTTP 409 Conflict with error message in the HTTP response body. If the color is unexpected - there will be HTTP 400 Bad Request with error message in the body. Otherwise, there will be HTTP 201 Created with empty HTTP response body & Location: link-to-created-person header.

Person

Get person details:

curl -i http://localhost:8080/preferences/people/1

To see all possible RESTful options for /preferences/people/1, use -X OPTIONS.

Update person details:

curl -i -X PUT -H 'Content-Type: application/json' -d '{"id":1,"firstName":"John","lastName":"Smith","dateOfBirth":"1988-12-23","favoriteColor":["YELLOW"],"favoriteFood":[{"name":"chocolate"}]}' http://localhost:8080/preferences/people/1

There is the same validation for the person update as for its creation. If you'll try to update not existing person - it will return HTTP 404 Not Found.

Delete person:

curl -X DELETE http://localhost:8080/preferences/people/4

There will be HTTP 204 No Content with empty body in case of success.

Food

As I've mentioned, there is a separate entity for food preferences.

Get food list:

curl -i http://localhost:8080/preferences/foodlist

To see all possible RESTful options for /preferences/foodlist, use -X OPTIONS.

Search the food list:

curl -i http://localhost:8080/preferences/foodlist/search?name=ca

You can search by name.

Get food details:

curl -i http://localhost:8080/preferences/foodlist/1

To see all possible RESTful options for /preferences/foodlist/1, use -X OPTIONS.

Update food details:

curl -i -X PUT -H 'Content-Type: application/json' -d '{"name": "apple"}' http://localhost:8080/preferences/foodlist/1

I've not implemented creation and deletion of food record because it's a part of person workflow.

Dev extras

Special test page created, served by dev server, to test the API in the browser:

http://localhost:8080/test/web/index.html

First you need to choose HTTP method, then - fill the form & send.

Tests

JUnit for unit tests and JBehave for application-level tests used. Run tests command:

mvn clean test integration-test

To view the results of JBehave tests go to "target/jbehave/view/reports.html".

Docs

Swagger.io used to build RESTful API documentation. Build the docs:

mvn compile

Look for the generated docs in "target/generated-resources/swagger.json".

sheva / peoplesimplepreferences Goto Github PK