Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js 18 or higher
  • PostgreSQL 14 or higher
  • Redis 6 or higher
  • A GitHub account and GitHub App credentials

​
Installation

1

Clone and Install Dependencies

Clone the Diffy API repository and install the required packages:
git clone https://github.com/your-org/diffy-api.git
cd diffy-api
yarn install
2

Configure Environment Variables

Create a .env file in the root directory with your configuration:
# Server Configuration
PORT=3001
FRONTEND_URL=http://localhost:3000

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/diffy"

# Redis
REDIS_URL="redis://localhost:6379"

# GitHub OAuth App
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
GITHUB_CALLBACK_URL=http://localhost:3001/auth/callback
GITHUB_REDIRECT_URL=http://localhost:3000/auth/callback

# GitHub App (for webhooks and API access)
GITHUB_APP_ID=your_github_app_id
GITHUB_APP_PRIVATE_KEY_PATH=./certs/diffy.private-key.pem
GITHUB_WEBHOOK_SECRET=your_webhook_secret

# JWT
JWT_SECRET=your_jwt_secret_key
You’ll need to create a GitHub OAuth App and GitHub App in your GitHub account settings. See GitHub’s documentation for details.
3

Set Up the Database

Generate the Prisma client and run database migrations:
npx prisma generate
npx prisma migrate deploy
This will create all necessary tables including User, PullRequest, and Comment models.
4

Start the Development Server

Launch the API server in development mode:
yarn start:dev
The server will start on http://localhost:3001 with hot-reloading enabled.

​
Making Your First API Call

​
1. Authenticate with GitHub

Start the OAuth flow by redirecting users to the authentication endpoint: 
GET http://localhost:3001/auth/github
This will redirect to GitHub for authorization. After approval, users are redirected back to your callback URL with a JWT token.

​
2. Get Current User Profile

Use the JWT token to fetch the authenticated user’s profile: 
curl -X GET http://localhost:3001/users/me \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
3. Fetch a Pull Request

Retrieve pull request details from GitHub: 
curl -X GET http://localhost:3001/github/pull-request/owner/repo/123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
4. Create an Inline Comment

Add a line-level comment to a pull request: 
curl -X POST http://localhost:3001/comments \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Consider using async/await here for better readability",
    "filePath": "src/main.ts",
    "lineNumber": 42,
    "pullRequestId": "123"
  }'

​
5. Connect to WebSocket for Real-Time Updates

Establish a WebSocket connection for live collaboration:
TypeScript
import { io } from 'socket.io-client';

const socket = io('http://localhost:3001');

// Join a pull request room
socket.emit('join-pr-room', {
  pullRequestId: 123,
  username: 'john_doe'
});

// Listen for other users joining
socket.on('joined', (message: string) => {
  console.log(message);
});

// Listen for active users updates
socket.on('active-users', (users: string[]) => {
  console.log('Active users:', users);
});

// Listen for typing indicators
socket.on('typing', (data: { username: string }) => {
  console.log(`${data.username} is typing...`);
});

​
Next Steps

API Reference

Explore all available endpoints and request/response schemas

WebSocket Events

Learn about real-time events and collaboration features

Authentication Guide

Deep dive into OAuth flow and JWT token management

GitHub Webhooks

Configure and handle GitHub webhook events

​
Need Help?

If you encounter any issues or have questions:
  • Check the API Reference for detailed endpoint documentation
  • Review the Prisma schema for database models
  • Examine the source code on GitHub
Make sure your PostgreSQL and Redis services are running before starting the development server. The API requires both services to be available.

Build docs developers (and LLMs) love

Get started for freeTalk to us