Conversion to roman numerals is a spring-boot application which exposes an endpoint to calculate the roman numeral equivalent of a given integer.
- Purpose
- References
- Local environment setup
- Engineering and testing methodology
- API response
- Dependencies
- Packaging layout
- Future
Build an HTTP endpoint that provides the roman numeral equivalent of
an integer value in the range 1-255. The HTTP endpoint accepts a URI in the
format http://localhost:8080/romannumeral?query={number}
where number
is
an integer in the range 1-255.
For example, http://localhost:8080/romannumeral?query=10
would return the
roman numeral equivalent of 10, which is X
.
The references below provide a brief background on roman numerals and explain how integers are converted to roman numerals.
- Install Apache maven (version 3.6.3 or above)
- Install JDK 11 (version 11.0.8 or above)
- Optional : Install a JSON viewer plugin on your browser. For Chrome, you could install JSONView
- Clone the repo :
git clone https://github.com/swetabar/roman-numeral.git
- From the root folder, execute :
mvn spring-boot:run
- Open any browser window and try out the following URL:
http://localhost:8080/romannumeral?query=9
to get started
You could probably import it into IntelliJ IDEA Community edition as well, but that might need a few additional plugins.
- Clone the repo :
git clone https://github.com/swetabar/roman-numeral.git
- Click on
File -> Open
- Navigate to the cloned
roman-numeral
folder and import it in - Within the project in intellij, navigate to :
src/main/java/com/roman/conversion/RomanNumeralApplication.java
- Run
RomanNumeralApplication.java
- Open any browser window and try out the following URL:
http://localhost:8080/romannumeral?query=10
to get started
- From the root folder, execute
mvn clean test
- Right click on the
com.roman.conversion
package - Click on
Run Tests in com.roman.conversion
- You can see the unit tests running on the IntelliJ terminal
Spring-boot is used as the backend framework to build out the rest endpoint for converting integers to roman numerals. A few error handling scenarios had to be considered - such as 0 has no roman numeral equivalent. I used TDD - Test Driven Development to build out this application. The development process started with the spring boot application's backbone, then writing out tests for RomanNumeralController and RomanNumeralService, followed by writing out code to make sure the tests pass. I added the edge cases soon after and the error handling following the same process as mentioned above. I also added Javadoc comments to provide a better understanding of each class, method, or interface.
The detailed API response can be found in the swagger document. I've mentioned the successful scenario as well as a
few error scenarios.
The swagger documentation can be accessed at :
http://localhost:8080/swagger-ui.html#/roman-numeral-controller
.
The JSON version of the document can be accessed at : http://localhost:8080/v2/api-docs
The request could be a curl request : curl http://localhost:8080/romannumeral?query=8
or you could open your favorite
browser and hit : http://localhost:8080/romannumeral?query=8
. The server
responds with an HTTP status code of 200 and a json object with the
input
and the output as seen below:
{
"input": "8",
"output": "VIII"
}
Request :
curl http://localhost:8080/romannumeral?query=
The server responds with an HTTP status code of 400 and a json
object as seen below:
{
"errorCode": "REQUEST_IS_EMPTY",
"message": "The query parameter is blank."
}
Request :
curl http://localhost:8080/romannumeral?query=0
The server responds with an HTTP status code of 422 and a json
object as seen below:
{
"errorCode": "REQUEST_LIMIT_ERROR",
"message": "The number entered was 0. There is no roman numeral for 0."
}
Request : curl http://localhost:8080/romannumeral?query=9.8
The server responds with an HTTP status code of 400 and a json
object as seen below:
{
"errorCode": "INVALID_INPUT",
"message": "You entered 9.8, which is a double value. Please enter an integer value in the range of 1 - 255."
}
Request : curl http://localhost:8080/romannumeral?query=257
The server responds with an HTTP status code of 422 and a json
object as seen below:
{
"errorCode": "REQUEST_LIMIT_ERROR",
"message": "The number should lie within the limit of 1 - 255."
}
Request : curl http://localhost:8080/roman
The server responds with an HTTP status code of 404 and a json
object as seen below:
{
"errorCode": "404 NOT_FOUND",
"message": "Not Found"
}
The dependencies that have been used for this application include :
- Lombok
- Spring-boot maven plugin
- Spring-boot starter
- Spring-boot starter test
- Spring-boot starter web
- junit4
- maven-surefire-plugin
- springfox-swagger2
The dependency graph can be found on github here.
The root of the project contains the src
folder which has the source code
for the application as well as the unit tests.
Within src/main/java/com/roman/conversion
, the following folders were
included:
- controller - Consists of
RomanNumeralController.java
with the/romannumeral
endpoint andHandleErrorController.java
with the/error
endpoint - errorhandling - Consists of
ExceptionHandler.java
to handle exceptions andIncorrectLimitException.java
- model - Consists of
Error.java
andRomanNumeral.java
model classes - service - Consists of
IRomanNumeralService.java
interface andRomanNumeralService.java
- utils - Consists of
RomanNumeralUtils.java
which includes constants and utility methods
Within src/test/java/com/roman/conversion/
, unit test files for each of the
above classes have been included.
Next steps include :
- Expand the limit for converting an integer to a roman numeral beyond 255
- Adding integration tests
- Create a docker image
- Deploying the application to the cloud
- Building out a frontend for it
- Adding scaling, if required