Quickstart

Get up and running with the Cat Data API in minutes

Get your Cat Data API server running locally and make your first API request in under 5 minutes.

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (v14 or higher)
• PostgreSQL (v12 or higher)
• npm or yarn package manager

Installation

1. Clone the repository

   Clone the Cat Data API repository to your local machine:

   git clone https://github.com/toryshchyn/cat-data.git
   cd cat-data
   
2. Install dependencies

   Install the required npm packages:

   npm

   npm install
   

   This will install all dependencies from package.json:

   • express - Web framework
   • pg and knex - PostgreSQL client and query builder
   • multer - File upload handling
   • express-jwt and jwks-rsa - Auth0 authentication
   • cors - CORS middleware
   • uuid - UUID generation
3. Set up environment variables

   Create a .env file in the project root with your configuration:

   .env

   # Database Configuration
   PGHOST=localhost
   PGPORT=5432
   PGUSER=your_db_user
   PGPASSWORD=your_db_password
   PGDATABASE=cat_data
   
   # Auth0 Configuration
   AUTH0_DOMAIN=https://your-tenant.auth0.com/
   AUTH0_AUDIENCE=https://your-api-identifier
   
   # Server Configuration
   PORT=3000
   NODE_ENV=development
   

   See the Environment Variables guide for detailed configuration instructions.

4. Run database migrations

   Set up the database schema using Knex migrations:

   npx knex migrate:latest
   

   This creates the following tables:

   • images - Stores image metadata
   • tags - Stores tags for categorization
   • items - Stores catalog items
   • items_to_tags - Junction table for many-to-many relationships
5. Start the development server

   Start the API server in development mode:

   npm run dev
   

   You should see:

   Server running on http://localhost:3000
   

Make Your First API Request

Now that your server is running, let’s make your first authenticated API request.

All API endpoints require Auth0 JWT authentication. See the Authentication guide to obtain a valid token.

Upload an Image

Upload a cat image to the API:

Upload Image

curl -X POST http://localhost:3000/api/upload \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "file=@/path/to/cat-photo.jpg"

Response:

{
  "id": 1,
  "filename": "550e8400-e29b-41d4-a716-446655440000-cat-photo.jpg"
}

List All Images

Retrieve all uploaded images:

List Images

curl -X GET http://localhost:3000/api/images \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

[
  {
    "id": 1,
    "name": "550e8400-e29b-41d4-a716-446655440000-cat-photo.jpg"
  }
]

Get a Specific Image

Retrieve an image by ID:

Get Image

curl -X GET http://localhost:3000/api/image/1 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  --output downloaded-image.jpg

Delete an Image

Delete an image:

Delete Image

curl -X DELETE http://localhost:3000/api/image/1 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response: 204 No Content

Next Steps

Authentication

Learn how to authenticate with Auth0 JWT tokens

API Reference

Explore all available endpoints in detail

Database Schema

Understand the PostgreSQL database structure

Development Setup

Configure your development environment

Common Issues

Database connection errors

If you see connection errors, verify:

• PostgreSQL is running: pg_isready
• Database credentials in .env are correct
• Database exists: createdb cat_data

Authentication errors (401 Unauthorized)

This means your JWT token is invalid or expired. Ensure:

• Your Auth0 configuration is correct in .env
• You’re using a valid, non-expired JWT token
• The token’s audience matches your AUTH0_AUDIENCE

File upload errors

If file uploads fail, check:

• File type is JPEG or PNG (other types are rejected)
• File is being sent as multipart/form-data with field name file
• The images/ directory exists and is writable

Development Scripts

The API includes these npm scripts from package.json:

Script	Command	Description
dev	npm run dev	Start development server with hot reload
build	npm run build	Compile TypeScript to JavaScript
start	npm start	Run production server from compiled code

For production deployment, build the project first:

npm run build
npm start