Emergency Report REST API Powered by What3Words
This is a Java based REST application which intends performing emergency alerting using what3words API. It is a minimal Proof of concept that adheres to the requirements mentioned in Here
Key aspects related to implementation:
- Employing test driven development practice while building application - Each module goes through the
red
->fix
->green
->refactor
cycle - Intensive unit tests - Mocktio based unit tests to observe interactions of various actors
- Separation of concerns - Modular approach on top of MVC paradigm in giving specific responsibility to each modules in the application
- Service layer to handle data persistence and business logics required to invoke the what3words api with the location data supplied
- Controller to handle all the endpoint calls to process the data from users.
- Models to keep track of data that is processed by the system.
- ControllerAdvice to handle all the user defined exceptions handled at the runtime to send proper response code to users to better understand the flow.
- Dependency resolution with Spring-Boot's Auto-configuration and dependency resolution.
- MVC test to support integration testing of the entire Spring Application.
- Lombok - used annotation based pre-processing to reduce a lot of boilerplate code that can be deferred to compile time.
TDD - Red->Green->Refactor cycle
REST APIs
Convert from English to Welsh
Request
POST /emergency-api/welsh-convert HTTP/1.1
Host: localhost:8080
Content-Type: application/json
{
"3wa": "daring.lion.race"
}
Request format:
3wa – the input 3wa string to be converted to the other language.
Response
Returns: Empty converted 3wa in to the other language:
200 – in case of success
400 – if the 3wa is invalid
503 – if the API invocation to What3Words external service fails.
HTTP/1.1 200 OK
Content-Type: application/json
{
"3wa": "sychach.parciau.lwmpyn"
}
OR
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Type: application/json;charset=UTF-8
{
"message": "3wa not recognised: filled.count.asd12"
}
Get Report filled with missing info
Request
POST /emergency-api/reports HTTP/1.1
Host: localhost:8080
{
"message":"A hiker has got lost",
/* "lat": null,
"lng":null, */
"3wa": "daring.lion.race",
"reportingOfficerName": "Joe Bloggs"
}
OR
POST /emergency-api/reports HTTP/1.1
Host: localhost:8080
{
"message":"A hiker has got lost",
"lat": 51.508341,
"lng":-0.125499,
"3wa": null,
"reportingOfficerName": "Joe Bloggs"
}
Request format:
message – the input message related to the emergency reported. lat – the input location latitude value. lng – the input location longitude value. 3wa – the input 3wa string to be converted to the other language. reportingOfficerName – the name of the reporting person from the location.
Response
Returns: The filled location report for request posted to the endpoint. Or if the 3wa is not grammatically correct, then the suggestions closer to the given 3wa.
/* HTTP/1.1 200 */
Content-Type: application/json;charset=UTF-8
{
"message":"A hiker has got lost",
"lat": 51.508341,
"lng":-0.125499,
"3wa": "daring.lion.race",
"reportingOfficerName": "Joe Bloggs"
}
OR
/* HTTP/1.1 200 */
Content-Type: application/json;charset=UTF-8
{
"message":"3wa not recognised: filled.count.snap",
"suggestions": [
{
"country": "GB",
"nearestPlace": "Bayswater, London",
"words": "filled.count.soap"
},
{
"country": "GB",
"nearestPlace": "Wednesfield, W. Midlands",
"words": "filled.count.slap"
},
{
"country": "GB",
"nearestPlace": "Orsett, Thurrock",
"words": "fills.count.slap"
}
]
}
OR
/* HTTP/1.1 422 UNPROCESSABLE ENTITY */
Content-Type: application/json;charset=UTF-8
{
"message": "Invalid Request!"
}
/* HTTP/1.1 402 INVALID REQUEST */
Content-Type: application/json;charset=UTF-8
{
"message": "3wa not recognised: filled.count.asd12"
}
/* HTTP/1.1 500 SERVICE ERROR */
Content-Type: application/json;charset=UTF-8
{
"message": "3wa not recognised: filled.count.asd12"
}
Response
Returns the appropriate response for the location information passed.
200 – in case of success
400 – if the 3wa is invalid
503 – if the API invocation to What3Words external service fails.
Test Coverage
Dependencies
Testing
This application is build following TDD principles and are rich with various integration/unit tests based on test pyramids To run all the tests:
mvn clean test
Build
In order to build this application, run the following maven command.
mvn clean package
installing the packages
With Tests:
$ mvn clean install -U
running tests
Unit tests:
$ mvn test
Developed in Jetbrain's IntelliJ IDE
References
- what3words java wrapper : https://developer.what3words.com/tutorial/java
- API details: https://developer.what3words.com/public-api/docs#overview
- mocktio failing for API class: https://stackoverflow.com/a/58200905
- json name setting: https://stackoverflow.com/q/40969156
handlerExceptionResolver
not found bean issue : https://stackoverflow.com/a/56121977- json ignore fields: https://www.baeldung.com/jackson-ignore-null-fields
- integration testing: https://stackoverflow.com/a/35402975
- Mock external API call :
- assert json content in mvc testing : https://stackoverflow.com/a/41670634
License
MIT