This project provides a RESTful API for managing a database of banks and their SWIFT codes. It allows users to retrieve, add, and delete bank information. The application is built using Go and utilizes PostgreSQL as its database. The entire application is containerized using Docker for easy setup and deployment.
The application is composed of several cooperating systems, each responsible for a different layer of functionality:
This component stores and manages all project data. It supports adding, removing, and retrieving entries. The database is preloaded with mock data provided in the /data directory as CSV files.
This is the main server application responsible for handling all incoming requests. It processes the backend logic, validates the data, and interacts with the database to ensure accurate responses or appropriate error handling.
The app uses verified ISO 3166-1 alpha-2 country codes and official country names obtained from Restcountries v2.0. This helps validate incoming data, whether from CSV files or API CREATE requests.
A separate database used solely for testing purposes. It is isolated from production data and used exclusively to validate edge cases. This database is the target environment for automated tests.
This module is responsible for running automated tests against backend endpoints and logic. It identifies functional issues and provides detailed error reports, aiding in the validation of existing features.
- Written in Go with Fiber web framework
- PostgreSQL for persistent storage
- Automated testing with separate database
- Dockerized (dev/test/prod)
- Input validation based on official ISO and SWIFT formats
To get started with this project, first clone the repository to your local machine:
git clone https://github.com/Xenoneqq/swift-code-databaseOnce cloning is complete, navigate into the project directory:
cd swift-code-databaseBefore setting up the project, ensure you have Docker installed on your system. You can follow the installation instructions for your platform here:
Once Docker is installed, you're ready to proceed with the setup steps.
The project can be launched in different modes depending on the environment and purpose.
All commands should be executed from the root directory of the project:
cd swift-code-databaseOnce launched, the application exposes its API at:
http://localhost:8080/api/v1/swift-codes
Below are the available Docker run modes:
Runs the application with a default database populated from the bank_data.csv file included in the project.Recommended for general use and production-like behavior.
To start the application in this mode:
docker compose up -dThis mode is intended for local debugging and feature testing. It runs the application with a separate test database, without any preloaded data. The environment accepts HTTP requests and is suitable for testing edge cases or development-specific scenarios.
To start in debug mode:
docker compose --env-file .env.debug up -dThis mode prepares the environment for automated testing. It starts the application and test database, then automatically runs the test suite. After the tests complete, the environment remains active, allowing further manual inspection or requests.
To run in test mode:
docker compose --env-file .env.test upUsing -d launches app in the background. Don't use it if you want to see the test results in terminal
To stop the running application and shut down all active containers, use:
docker compose downIf you also want to remove all associated data volumes ( full reset ), use the following command:
docker compose down -v
⚠️ The -v flag will permanently remove all data stored in the database. Use with caution.
🛠️ Note on Docker versions:
Docker v20+ supports the newerdocker composesyntax (without a dash).
If you're using an older version, replacedocker composewithdocker-composein all commands.
All endpoints are served under the https://localhost:8080/api/v1/swift-codes base path unless stated otherwise.
You can interact with the API using tools like Postman (recommended for easier testing), or by using command-line tools such as curl.
Example request snippets below use curl for demonstration purposes and can be copied and executed directly in your terminal.
There is a Postman collection available! Click the button below to quickly import the collection into Postman and start interacting with the API.
Returns a list of all banks, sorted by bank name, headquarter status, country name, and SWIFT code.
curl http://localhost:8080/api/v1/swift-codes200 OK: List of bank entries400 Bad Request: Failed to fetch data
If there are no banks in the database, an empty array and a custom message will be included in the response.
Fetches a single bank using its SWIFT code.
- When the bank is a Headquarter:
curl http://localhost:8080/api/v1/swift-codes/KCCPPLPWXXX- Explanation: The
XXXat the end of the SWIFT code indicates a headquarter.
- When the bank is a Branch:
curl http://localhost:8080/api/v1/swift-codes/KCCPPLPWASI- Explanation: The
ASIsuffix in the SWIFT code indicates a branch of the bank.
- When the bank might not exist:
curl http://localhost:8080/api/v1/swift-codes/GTBKPLWAAAA- Explanation: If the SWIFT code doesn't exist, the response will return a
404 Not Foundstatus, indicating that no bank was found.
200 OK: Bank found; returns detailed info404 Not Found: Bank does not exist400 Bad Request: Multiple banks found with the same code or invalid query
If the bank is a headquarter, branch information will be included in the response.
Retrieves all banks for a given country, based on its ISO2 code (e.g., "PL", "DE", "FR").
curl http://localhost:8080/api/v1/swift-codes/country/PL200 OK: List of banks for the specified country404 Not Found: No banks found400 Bad Request: Failed to fetch data
Creates a new bank entry using a JSON payload. The submitted data must meet the following validation rules:
swiftCode,countryName, andcountryISO2must be written entirely in uppercase letters.swiftCodemust be exactly 11 characters long.- The first six characters of the
swiftCodemust contain only letters (no digits). - If the bank is a headquarter (
isHeadquarter: true), theswiftCodemust end with"XXX". - The
countryISO2must match the 5th and 6th characters of theswiftCode. - The
countryNameandcountryISO2must correspond to real, valid country data.
{
"swiftCode": "ABCDCNSPXXX",
"bankName": "Bank Name",
"countryName": "COUNTRY NAME",
"countryISO2": "XX",
"isHeadquarter": true,
"address": "Street 123"
}curl -X POST http://localhost:8080/api/v1/swift-codes -H "Content-Type: application/json" -d "{\"swiftCode\":\"GTBKPLWAXXX\",\"bankName\":\"Generic Test Bank\",\"countryName\":\"POLAND\",\"countryISO2\":\"PL\",\"isHeadquarter\":true,\"address\":\"123 Bank St\"}"201 Created: Entry created successfully400 Bad Request: Invalid input or bank already exists422 Unprocessable Entity: Malformed payload
Deletes a bank based on its SWIFT code.
curl -X DELETE http://localhost:8080/api/v1/swift-codes/GTBKPLWAXXXThis example deletes the bank created in the previous section using the POST endpoint.
200 OK: Entry deleted successfully404 Not Found: Bank not found400 Bad Request: Error during deletion
Returns the status of the API server.
curl http://localhost:8080/api200 OK: Server is active
This project includes an automated test suite that verifies the behavior of the API and core application logic. All tests are isolated from production data and run against a dedicated test database.
- API endpoint behavior (GET, POST, DELETE)
- SWIFT code validation rules
- Country name/code verification
- Handling of duplicate or malformed data
You can run the full test suite using Docker in testing mode:
docker-compose --env-file .env.test upThis will:
- Spin up the application and a dedicated test database
- Run all Go test files automatically
- Output detailed test results to the console
All test files are located in the /tests directory and use Go's built-in testing package. The tests are designed to run automatically during container startup when in test mode.
⚠️ After the tests finish, the application and test database will remain active — similar to launching in DEBUG mode.