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

A financial API for managing transactions. The API main URL /financial/v1.


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

  • Create a Transaction: POST/financial/v1/transactions
  • Update a Transaction: PUT/financial/v1/transactions
  • Delete a Transaction (by id): DELETE/financial/v1/transactions/1
  • Get report of transactions in a period of time (sorted and paginated): GET/financial/v1/transactions?startDate=2020-01-01&endDate=2020-09-20&page=2&size=5&sort=DESC
  • Find a unique transaction by id: GET/financial/v1/transactions/1
  • Find a unique transaction by id, but filtering JSON fields: GET/financial/v1/transactions/1?fields=id,nsu,transactionDate,amount
  • Find transactions by NSU (Unique sequential number): GET/financial/v1/transactions/byNsu/{nsuNumber}
  • Get Statistics about the transactions of the API: GET/financial/v1/statistics



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


  "nsu": "123456",
  "authorizationNumber": "010203",
  "amount": "22.88",
  "transactionDate": "2020-04-05T09:59:51.312Z",
  "type": "CARD",


id - transaction id. It is automatically generated.

nsu - identification number of a sales transaction using cards. May be null if transaction was paid in cash;

authorizationNumber - is a one-time code used in the processing of online transactions;

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

transactionDate – transaction time in the ISO 8601 format YYYY-MM-DDThh:mm:ss.sssZ in the Local timezone.

type - transaction type: CARD (credit-card) or MONEY (paid in cash).

links - self-linking URL for the transaction. 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 transaction date is in the future.
  • 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).


This end-point is called to update a transaction.


   "id": 1,
   "nsu": "123456",
   "authorizationNumber": "010203",
   "amount": "30.06",
   "transactionDate": "2020-04-05T09:59:51.312Z",
   "type": "CARD"

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

   "data": {   
           "id": 1,
           "nsu": "123456",
           "authorizationNumber": "010203",
           "amount": "30.06",
           "transactionDate": "2020-04-05T09:59:51.312Z",
           "type": "CARD",
           "links": [
               "rel": "self",
                "href": "http://localhost:8080/financial/v1/transactions/1"


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


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


id - transaction id to be deleted.


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


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


sum – a BigDecimal specifying the total sum of transaction value.

avg – a BigDecimal specifying the average amount of transaction value.

max – a BigDecimal specifying single highest transaction value.

min – a BigDecimal specifying single lowest transaction value.

count – a long specifying the total number of transactions.

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.7)
  • Spring Boot 2.3.4
  • Spring Admin Client 2.3.0
  • Maven
  • JUnit 5
  • Surfire
  • PostgreSQL 12
  • Flyway 6.4.4
  • Swagger 3.0.0
  • Model Mapper 2.3.8
  • 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. financial-java-api-3.1.3-SNAPSHOT.jar


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 financial. If you don't have pgAdmin installed you can run on the psql console the follow command:

CREATE database financial;

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


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).


  • For unit test phase, you can run:
mvn test
  • To run all tests (including Integration Tests):
mvn integration-test


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

java -jar financial-java-api-3.1.3-SNAPSHOT.jar


mvn spring-boot:run

By default, the API will be available at http://localhost:8080/financial/v1


Medium Articles


This API is licensed under the MIT License.


Financial Java API

A financial API for managing transactions. It is built with Java, Spring Boot, and Spring Framework.

Financial Java API Info

⭐ Stars 54
🔗 Homepage
🔗 Source Code
🕒 Last Update 8 months ago
🕒 Created 2 years ago
🐞 Open Issues 0
➗ Star-Issue Ratio Infinity
😎 Author mariazevedo88