​

Local Development Setup

This guide will help you set up a local development environment for Rates API, allowing you to make changes, test new features, and contribute to the project.

​

Prerequisites

Before you begin, make sure you have the following installed:

• Bun: The JavaScript runtime and package manager used by the project
• Git: For version control
• A text editor or IDE: Such as VS Code, WebStorm, etc.

​

Getting Started

​

1. Clone the Repository

git clone https://github.com/simonbetton/ratesapi.nz.git
cd ratesapi.nz

​

2. Install Dependencies

Using Bun to install dependencies:

bun i

​

3. Run the Development Server

Start the local development server:

bun run dev

This will start the server at http://localhost:8787. You can access the API and Swagger UI documentation at this URL.

​

Scraping Data

The project includes scripts to scrape rate data from financial institution websites. These scripts are located in the bin/ directory.

To run a scraper script:

bun run bin/scrape-mortgage-rates.ts

Available scraper scripts:

• scrape-mortgage-rates.ts: Fetches current mortgage rates
• scrape-personal-loan-rates.ts: Fetches personal loan rates
• scrape-car-loan-rates.ts: Fetches car loan rates
• scrape-credit-card-rates.ts: Fetches credit card rates

The scraped data is stored in the CloudFlare D1 database, allowing for comprehensive historical data management.

​

CloudFlare D1 Database

The project uses CloudFlare D1, a serverless SQL database built on SQLite, for data storage. This allows for efficient storage and querying of both current and historical rate data.

​

Local Development with D1

For local development, you’ll need to set up a local D1 database:

# Install Wrangler CLI if not already installed
npm install -g wrangler

# Create a local D1 database
wrangler d1 create ratesapi-data-local

# Apply database schema to local database
wrangler d1 execute ratesapi-data-local --file=./schema.sql --local

​

Database Schema

The database schema includes tables for:

• Current rates (mortgage, personal loan, car loan, credit card)
• Historical time series data
• Institution information
• Metadata and audit logs

​

Development Tips

​

Project Structure

• src/: Contains the main application code

  • index.ts: The entry point for the application
  • models/: Data schemas and types
  • routes/: API endpoint handlers
  • lib/: Utility functions and helpers

• bin/: Scripts for scraping data

• schema.sql: Database schema definition file

​

Testing Your Changes

Before submitting changes, make sure to:

1. Test all affected endpoints locally
2. Run any necessary data scraper scripts
3. Ensure the project builds without errors

​

Common Tasks

• Add a new endpoint: Create a new route handler in src/routes/
• Update data models: Modify schemas in src/models/
• Enhance scrapers: Modify the scraper scripts in bin/