The City Suggestion API application is a simple Spring Boot application, implementing a RESTful web service, providing city name suggestions based on a query string.
For further details about the API, please see the API portal
The application can be started with maven, just use the mvn spring-boot:run command:
The service provides an HTTP endpoint under "/suggestions". City suggestion queries may be sent to this endpoint via HTTP GET. The query string with the partial name of the city must be passed in the "q" query parameter:
The application utilizes the production ready features of the Spring Boot Actuator module.
Ths includes providing a Health Endpoint. The actual state of the application may be queried from the HTTP endpoint under: /actuator/health.
This could be done for example with the following curl command:
curl localhost:8080/actuator/health
The API documentation is also available in the deployed application and can be queried runtime as well:
http://localhost:8080/swagger-ui.html
The web based Swagger UI user interface also provides "try-it-yourself" functionality:
The API portal hosted at apimatic.io can be used to generate clients for different programming langauges as well (including Java, C#, Python and many others).
The expected behaviour of the API is also captured by postman based integration tests.
These may be used for integration and system testing purposes.
For details about the postman based integration tests, please see the official postman documentation.
On the reference system (Intel Core [email protected]) the startup took 7 seconds. This may be further optimized, if needed.
The service needs 1 Gb memory. Based on the results of the stress tests, this is enough to get a smooth throughput for a load peeking at 7500 requests/s.
Based on the load and stress tests; the service is capable to handle traffic up to 7500 requests/s on the reference system.
Higher traffic leads to graceful degradation of the response times and the total throughput:
If you need to serve higher load, then please consider using several instances of the service using load balancing or even configure auto scaling, especially if dynamic scaling capatibilities are needed as the load increases.
For further details about the load and stress testing please see the attached report.
The data is "GeoNames Gazetteer" dataset. (Licensed under CC Attribution License)
For details see the related readme file and the GeoNames website.