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

or

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

• Construindo uma API RESTful com Java e Spring Framework— Parte 1 (PT-BR)
• Construindo uma API RESTful com Java e Spring Framework— Parte 2 (PT-BR)
• Construindo uma API RESTful com Java e Spring Framework— Parte 3 (PT-BR)
• Construindo uma API RESTful com Java e Spring Framework— Parte 4 (PT-BR)
• Building a RESTful API with Java and Spring Framework — Part 1 (EN)

License

This API is licensed under the MIT License.