• Stars
    star
    248
  • Rank 163,560 (Top 4 %)
  • Language
    Java
  • License
    MIT License
  • Created about 5 years ago
  • Updated 7 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

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.

travels-java-api

Build Status GitHub forks GitHub release (latest by date) GitHub language count GitHub code size in bytes GitHub repo size GitHub last commit GitHub

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

Medium Articles

License

This API is licensed under the MIT License.

More Repositories

1

artigo-solid-medium

Implementações dos exemplos demonstrados no artigo: https://bit.ly/2o97vY1
Java
32
star
2

java-tutorials

A public list of open-source tutorials written by me about Java and its frameworks
30
star
3

travels-api

API for Travels Management - UFLA Comp Jr/20 anniversary event
Java
28
star
4

java-certification-oca

A project of exercises from books specialized on the OCA Exam 1Z0-808 program (Java 8) and OCA Exam 1Z0-815 (Java 11) program
Java
20
star
5

hackerrank-challenges

A project of solved Java/SQL challenges from HackerRank website
Java
17
star
6

o3smeasures-tool

Eclipse plug-in to evaluate software internal quality of Java projects.
Java
11
star
7

json-formatter-validator

Java tool for JSON validation via string or file and correction of invalid JSON-like string
Java
10
star
8

airbnb-scraper

Web scraper/crawler of Airbnb Brazilians page
JavaScript
7
star
9

starwars-intro

Star Wars film intro animation developed in HTML, CSS, JavaScript and Node.js (Tutorial by glaucia86 - https://bit.ly/32UG73k)
HTML
6
star
10

imdb-scraper

IMDB webscraper with Request-Promise, Cheerio and Nightmare.js
JavaScript
6
star
11

reddit-scraper

Web scraper/crawler of Reddit page
JavaScript
5
star
12

artigo-boas-praticas-medium

Implementações dos exemplos demonstrados no artigo: https://bit.ly/2Cs4PxN
Java
5
star
13

mariazevedo88.github.io

My personal website designed with AngularJS and Bootstrap
HTML
4
star
14

spring-rabbitmq-example

Example of a Spring Boot application using RabbitMQ
Java
4
star
15

spring-framework-examples

Spring Framework's examples: Spring Boot, Spring Data and Spring MVC
Java
3
star
16

personal-java-vault

3
star
17

spring-boot-swagger-jwt

Demo project for Spring Boot + Swagger + JWT
Java
3
star
18

spring-discord-example

Demo Discord bot using Discord4J + Spring Boot
Java
3
star
19

apis-admin-server

Spring Boot Admin Server for my personal API's
Java
3
star
20

json-formatter-validator-java7

A java 7 version of the original project json-formatter-validator (https://github.com/mariazevedo88/json-formatter-validator)
Java
3
star
21

hash-generator-js

A Vue.js application with a javascript implementation of String's class hashCode method in Java
JavaScript
3
star
22

o3smeasures-plugin

Eclipse UpdateSite for the o3smeasures tool
XSLT
2
star
23

goldgem

Simple framework that implements some basic design patterns for Java projects using MVC.
Java
2
star
24

travels-api-graphql

2
star
25

rails-instagram

Ruby
2
star
26

spring-boot-blog-example

Demo project for Spring Boot + Thymeleaf
Java
2
star
27

jPetshop

A toy-project used as example of use of o3smeasure plug-in
Java
2
star
28

spring-boot-ws-example

An example application of SOAP Web Service with Spring Boot
Java
2
star
29

CakeUI

Framework to build Android applications easily.
Java
2
star
30

java-benchmarks

A project to get benchmarks of Java types and data structures
Java
2
star
31

automation-cucumber

Some automation tests with Ruby and Cucumber
Ruby
2
star
32

hash-generator

JavaEE app to generate hash code from a string
CSS
2
star
33

java-zookeeper-example

Demo project for Java + Zookeeper
Java
2
star
34

json-formatter

Linux Shell Script to format a JSON file
Shell
2
star
35

spring-boot-messaging-custom-starter

Spring Boot Demo Custom Starter Application - for testing purposes
Java
2
star
36

datasciencecoursera

Data Science repo from the Data Science Specialization on Coursera
R
2
star
37

o3smeasures

o3smeasures plugin webpage. Check out the plugin repo: https://github.com/mariazevedo88/o3smeasures-tool/
JavaScript
2
star