​
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/