{"id":20482189,"url":"https://github.com/rajagopal28/what3words-api-spike","last_synced_at":"2026-05-10T10:04:10.984Z","repository":{"id":88702009,"uuid":"427021776","full_name":"rajagopal28/what3words-api-spike","owner":"rajagopal28","description":"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.","archived":false,"fork":false,"pushed_at":"2021-11-11T14:11:23.000Z","size":1689,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"solution","last_synced_at":"2025-01-16T04:14:21.563Z","etag":null,"topics":["dependency-injection","integration","inversion-of-control","java-8","layered-architecture","rest-api","single-responsibility-principle","spring-boot","tdd","tdd-java","test-pyramid","what3words-api"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rajagopal28.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-11-11T14:01:41.000Z","updated_at":"2022-10-10T10:19:48.000Z","dependencies_parsed_at":null,"dependency_job_id":"f539558b-396f-4c70-aafc-c3933f9e93a6","html_url":"https://github.com/rajagopal28/what3words-api-spike","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rajagopal28%2Fwhat3words-api-spike","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rajagopal28%2Fwhat3words-api-spike/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rajagopal28%2Fwhat3words-api-spike/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rajagopal28%2Fwhat3words-api-spike/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rajagopal28","download_url":"https://codeload.github.com/rajagopal28/what3words-api-spike/tar.gz/refs/heads/solution","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242058084,"owners_count":20065062,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dependency-injection","integration","inversion-of-control","java-8","layered-architecture","rest-api","single-responsibility-principle","spring-boot","tdd","tdd-java","test-pyramid","what3words-api"],"created_at":"2024-11-15T16:11:57.513Z","updated_at":"2025-12-03T12:01:17.014Z","avatar_url":"https://github.com/rajagopal28.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Emergency Report REST API Powered by What3Words\n\nThis is a Java based REST application which intends performing emergency alerting using what3words API.\nIt is a minimal Proof of concept that adheres to the requirements mentioned in [Here](./Requirements.md)\n\n### Key aspects related to implementation:\n- Employing test driven development practice while building application - Each module goes through the `red` -\u003e `fix` -\u003e `green` -\u003e `refactor` cycle\n- Intensive unit tests - Mocktio based unit tests to observe interactions of various actors\n- Separation of concerns - Modular approach on top of MVC paradigm in giving specific responsibility to each modules in the application\n    - *Service layer* to handle data persistence and business logics required to invoke the what3words api with the location data supplied\n    - *Controller* to handle all the endpoint calls to process the data from users.\n    - *Models* to keep track of data that is processed by the system.\n    - *ControllerAdvice* to handle all the user defined exceptions handled at the runtime to send proper response code to users to better understand the flow.\n- Dependency resolution with Spring-Boot's Auto-configuration and dependency resolution.\n- MVC test to support integration testing of the entire Spring Application.\n- Lombok - used annotation based pre-processing to reduce a lot of boilerplate code that can be deferred to compile time.\n\n\n## TDD - Red-\u003eGreen-\u003eRefactor cycle\n![TDD Diagram](./images/red-green-refactor.png)\n\n## REST APIs\n\n#### Convert from English to Welsh\n##### Request\n```http\nPOST /emergency-api/welsh-convert HTTP/1.1\nHost: localhost:8080\nContent-Type: application/json\n\n{\n    \"3wa\": \"daring.lion.race\"\n}\n```\n### Request format:\n*3wa* – the input 3wa string to be converted to the other language.\n\n##### Response\nReturns: Empty converted 3wa in to the other language:\n\n200 – in case of success\n\n400 – if the 3wa is invalid\n\n503 – if the API invocation to What3Words external service fails.\n\n\n```http\nHTTP/1.1 200 OK\nContent-Type: application/json\n\n{\n    \"3wa\": \"sychach.parciau.lwmpyn\"\n}\n\n```\n\nOR\n\n```http\nHTTP/1.1 400 Bad Request\nContent-Type: application/json\n\nContent-Type: application/json;charset=UTF-8\n{\n    \"message\": \"3wa not recognised: filled.count.asd12\"\n}\n```\n\n\n#### Get Report filled with missing info\n##### Request\n```http\nPOST /emergency-api/reports HTTP/1.1\nHost: localhost:8080\n\n{\n    \"message\":\"A hiker has got lost\",\n    /* \"lat\": null,\n    \"lng\":null, */\n    \"3wa\": \"daring.lion.race\",\n    \"reportingOfficerName\": \"Joe Bloggs\"\n}\n\n```\n\nOR\n\n```http\nPOST /emergency-api/reports HTTP/1.1\nHost: localhost:8080\n\n{\n    \"message\":\"A hiker has got lost\",\n    \"lat\": 51.508341,\n    \"lng\":-0.125499,\n    \"3wa\": null,\n    \"reportingOfficerName\": \"Joe Bloggs\"\n}\n\n```\n\n\n### Request format:\n*message* – the input message related to the emergency reported.\n*lat* – the input location latitude value.\n*lng* – the input location longitude value.\n*3wa* – the input 3wa string to be converted to the other language.\n*reportingOfficerName* – the name of the reporting person from the location.\n\n\n\n##### Response\nReturns: The filled location report for request posted to the endpoint.\nOr if the 3wa is not grammatically correct, then the suggestions closer to the given 3wa.\n\n```http\n/* HTTP/1.1 200 */\nContent-Type: application/json;charset=UTF-8\n\n{\n    \"message\":\"A hiker has got lost\",\n    \"lat\": 51.508341,\n    \"lng\":-0.125499,\n    \"3wa\": \"daring.lion.race\",\n    \"reportingOfficerName\": \"Joe Bloggs\"\n}\n```\nOR\n\n\n```http\n/* HTTP/1.1 200 */\nContent-Type: application/json;charset=UTF-8\n{\n    \"message\":\"3wa not recognised: filled.count.snap\",\n    \"suggestions\": [\n        {\n            \"country\": \"GB\",\n            \"nearestPlace\": \"Bayswater, London\",\n            \"words\": \"filled.count.soap\"\n        },\n        {\n            \"country\": \"GB\",\n            \"nearestPlace\": \"Wednesfield, W. Midlands\",\n            \"words\": \"filled.count.slap\"\n        },\n        {\n            \"country\": \"GB\",\n            \"nearestPlace\": \"Orsett, Thurrock\",\n            \"words\": \"fills.count.slap\"\n        }\n    ]\n}\n```\nOR\n```http\n/* HTTP/1.1 422 UNPROCESSABLE ENTITY */\nContent-Type: application/json;charset=UTF-8\n{\n    \"message\": \"Invalid Request!\"\n}\n```\n\n\n```http\n/* HTTP/1.1 402 INVALID REQUEST */\nContent-Type: application/json;charset=UTF-8\n{\n    \"message\": \"3wa not recognised: filled.count.asd12\"\n}\n```\n\n\n```http\n/* HTTP/1.1 500 SERVICE ERROR */\nContent-Type: application/json;charset=UTF-8\n{\n    \"message\": \"3wa not recognised: filled.count.asd12\"\n}\n```\n\n##### Response\nReturns the appropriate response for the location information passed.\n\n200 – in case of success\n\n400 – if the 3wa is invalid\n\n503 – if the API invocation to What3Words external service fails.\n\n### Test Coverage\n![TestCoverage](./images/test-coverage-1.png)\n![TestCoverage](./images/test-coverage-2.png)\n\n\n### Dependencies\n![Dependencies](./images/dependencies-1.png)\n![Dependencies](./images/dependencies-2.png)\n\n## Testing\nThis application is build following TDD principles and are rich with various integration/unit tests based on test pyramids\nTo run all the tests:\n\n```bash\nmvn clean test\n```\n\n## Build\nIn order to build this application, run the following maven command.\n```bash\nmvn clean package\n```\n### installing the packages\nWith Tests:\n```bash\n$ mvn clean install -U\n```\n### running tests\nUnit tests:\n```bash\n$ mvn  test\n```\n\n\u003e         Developed in Jetbrain's IntelliJ IDE\n\n## References\n - what3words java wrapper : https://developer.what3words.com/tutorial/java\n  - API details: https://developer.what3words.com/public-api/docs#overview\n - mocktio failing for API class: https://stackoverflow.com/a/58200905\n - json name setting: https://stackoverflow.com/q/40969156\n - `handlerExceptionResolver` not found bean issue : https://stackoverflow.com/a/56121977\n - json ignore fields: https://www.baeldung.com/jackson-ignore-null-fields\n - integration testing: https://stackoverflow.com/a/35402975\n - Mock external API call :\n    - https://stackoverflow.com/questions/20504399/testing-springs-requestbody-using-spring-mockmvc\n    - using wiremock : https://stackoverflow.com/a/40908543\n    - using easymock: https://stackoverflow.com/a/61685017\n- assert json content in mvc testing : https://stackoverflow.com/a/41670634\n\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frajagopal28%2Fwhat3words-api-spike","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frajagopal28%2Fwhat3words-api-spike","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frajagopal28%2Fwhat3words-api-spike/lists"}