travels-java-api

About the API

An API for travel management. It is built with Java, Spring Boot, and Spring Framework. A toy-project to serve as a theoretical basis for the Medium series of articles I wrote about Java+Spring. The API main URL /api-travels/v1.

Features

This API provides HTTP endpoint's and tools for the following:

Create a trip: POST/api-travels/v1/travels
Update a trip: PUT/api-travels/v1/travels
Delete a trip (by id): DELETE/api-travels/v1/travels/1
Get report of travels in a period of time (sorted and paginated): GET/api-travels/v1/travels?startDate=2020-01-01&endDate=2020-09-20&page=2&size=5&sort=DESC
Find a unique trip by id: GET/api-travels/v1/travels/1
Find a unique trip by id, but filtering JSON fields: GET/api-travels/v1/travels/1?fields=id,orderNumber,startDate,amount
Find a trip by the order number (unique id on the system): GET/api-travels/v1/travels/byOrderNumber/{orderNumber}
Get Statistics about the travels of the API: GET/api-travels/v1/statistics

Details

POST/api-travels/v1/travels

This end-point is called to create a new trip.

Body:

{
  "orderNumber": "123456",
  "amount": "22.88",
  "startDate": "2020-04-05T09:59:51.312Z",
  "endDate": "2020-04-15T16:25:00.500Z",
  "type": "RETURN"
}

Where:

id - travel id. It is automatically generated.

orderNumber - identification number of a trip on the system.

amount – travel amount; a string of arbitrary length that is parsable as a BigDecimal;

startDate – travel start date time in the ISO 8601 format YYYY-MM-DDThh:mm:ss.sssZ in the Local time zone.

endDate – end date of the trip in the ISO 8601 format YYYY-MM-DDThh:mm:ss.sssZ in the Local time zone.

type - travel type: ONE-WAY, RETURN or MULTI-CITY.

links - self-linking URL for the travel. It is automatically generated.

Returns an empty body with one of the following:

201 - Created: Everything worked as expected.
400 - Bad Request: the request was unacceptable, often due to missing a required parameter or invalid JSON.
404 - Not Found: The requested resource doesn't exist.
409 - Conflict: The request conflicts with another request (perhaps due to using the same idempotent key).
422 – Unprocessable Entity: if any of the fields are not parsable or the start date is greater than the end date.
429 - Too Many Requests: Too many requests hit the API too quickly. We recommend an exponential back-off of your requests.
500, 502, 503, 504 - Server Errors: something went wrong on API end (These are rare).

PUT/api-travels/v1/travels/{id}

This end-point is called to update a trip.

Body:

{
   "id": 1,
   "orderNumber": "123456",
   "amount": "30.06",
   "startDate": "2020-04-05T09:59:51.312Z",
   "endDate": "2020-04-15T16:25:00.500Z",
   "type": "RETURN"
}

Must be submitted the object that will be modified. Must return a trip specified by ID and all fields recorded above, including links and the one that was updated.

{
   "data": {   
   		"id": 1,
   		"orderCode": "123456",
   		"amount": "30.06",
   		"startDate": "2020-04-05T09:59:51.312Z",
  		"endDate": "2020-04-15T16:25:00.500Z",
  		"type": "RETURN",
   		"links": [
			{
			"rel": "self",
				"href": "http://localhost:8080/api-travels/v1/travels/1"
			}
   		]
	}
}

GET/api-travels/v1/travels?startDate=2020-01-01&endDate=2020-01-18&page=2&size=5&sort=DESC

The end-point returns travels were created within the period specified in the request. E.g., in the above query, we are looking for all travels carried out between 01-18 January 2020. Also, the result should return in descending order and only page 2 with five trips.

DELETE/api-travels/v1/travels/{id}

This end-point causes a specific id to be deleted, accepting an empty request body and returning a 204 status code.

Where:

id - travel id to be deleted.

GET/api-travels/v1/statistics

This end-point returns the statistics based on the travels created.

Returns:

{
	"data": { 
  		"sum": "150.06",
  		"avg": "75.3",
  		"max": "120.0",
  		"min": "30.06",
  		"count": 2,
  		"links": [
			{
			"rel": "self",
				"href": "http://localhost:8080/api-travels/v1/statistics/1"
			}
   		]
   	}
}

Where:

sum – a BigDecimal specifying the total sum of the amount of all travels.

avg – a BigDecimal specifying the average of the amount of all travels.

max – a BigDecimal specifying single highest travel value.

min – a BigDecimal specifying single lowest travel value.

count – a long specifying the total number of travels.

links - self-linking URL for the statistic. It is automatically generated.

All BigDecimal values always contain exactly two decimal places, e.g: 15.385 is returned as 15.39.

Technologies used

This project was developed with:

Java 11 (Java Development Kit - JDK: 11.0.9)
Spring Boot 2.3.7
Spring Admin Client 2.3.1
Maven
JUnit 5
Surfire
PostgreSQL 13
Flyway 6.4.4
Swagger 3.0.0
Model Mapper 2.3.9
Heroku
EhCache
Bucket4j 4.10.0
Partialize 20.05

Compile and Package

The API also was developed to run with an jar. In order to generate this jar, you should run:

mvn package

It will clean, compile and generate a jar at target directory, e.g. travels-java-api-5.0.1-SNAPSHOT.jar

Execution

You need to have PostgreSQL 9.6.17 or above installed on your machine to run the API on dev profile. After installed, on the pgAdmin create a database named travels. If you don't have pgAdmin installed you can run on the psql console the follow command:

CREATE database travels;

After creating the API database, you need to add your Postgres root username and password in the application.properties file on src/main/resource. The lines that must be modified are as follows:

spring.datasource.username=
spring.datasource.password=

When the application is running Flyway will create the necessary tables for the creation of the words and the execution of the compare between the end-points. In the test profile, the application uses H2 database (data in memory).

Test

For unit test phase, you can run:

mvn test

To run all tests (including Integration Tests):

mvn integration-test

Run

In order to run the API, run the jar simply as following:

java -jar travels-java-api-5.0.1-SNAPSHOT.jar --spring.profiles.active=dev

mvn spring-boot:run -Dspring.profiles.active=dev

By default, the API will be available at http://localhost:8080/api-travels/v1

Documentation

Swagger (development environment): http://localhost:8080/swagger-ui/index.html

Medium Articles

License

This API is licensed under the MIT License.

brunominozzi/travels-java-api

travels-java-api

About the API

Features

Details

Technologies used

Compile and Package

Execution

Test

Run

Documentation

Medium Articles

License