rajagopal28 / what3words-api-spike

A small proof of concept java application using spring-boot to work with and get to know about the innovative geo navigation project what3words' API and their wrapper sdks to work with their product.

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 :
  • https://stackoverflow.com/questions/20504399/testing-springs-requestbody-using-spring-mockmvc
  • using wiremock : https://stackoverflow.com/a/40908543
  • using easymock: https://stackoverflow.com/a/61685017
• assert json content in mvc testing : https://stackoverflow.com/a/41670634

License

MIT