Khanos Backend API

A small REST service: GitHub commit search, a Mongoose-backed URL shortener, and Gemini text/image generation.

Group Main

GET /

API documentation page

Renders the human-readable API documentation for this service, including endpoint groups, parameters and response examples.

Responses
  • 200 HTML documentation page
GET /api/

API documentation (JSON)

Returns the same endpoint metadata as structured JSON. Useful for clients that want to fetch the docs programmatically.

Responses
  • 200 Array of documented routes

Group GitHub

GET /api/github/getCommits/:word

Search commits by keyword

Searches recent GitHub commits (main public repositories) that contain the given word.

Parameters
Name Type Required Description
word string yes Keyword to search for in commit messages.
Responses
  • 200 Array of commit objects. On upstream failure the service swallows the error and returns a JSON body of `null` (still HTTP 200).
GET /api/github/getCommitsByRepoAndOwner/:owner/:repo

Search commits by owner and repo

Searches recent GitHub commits for a specific repository, identified by its owner and name.

Parameters
Name Type Required Description
owner string yes GitHub account or organization that owns the repository.
repo string yes Repository name (without the .git suffix).
Responses
  • 200 Array of commit objects. On upstream failure the service swallows the error and returns a JSON body of `null` (still HTTP 200).

Group URL Shortener

GET /api/url

List all stored URLs

Fetches every URL currently stored in the database.

Responses
  • 200 Array of stored URL documents.
  • 500 Internal server error while reading from the database.
POST /api/url/create

Create a short URL

Creates a new short URL for the provided original URL. If an existing short URL is found, it is returned; otherwise a new one is created.

Parameters
Name Type Required Description
original_url string yes The full URL to shorten.
Responses
  • 200 The shortened URL document `{ original_url, short_url, creation_date }` (created or reused). 
    {
  "original_url": "https://example.com/very-long-path",
  "short_url": 12345,
  "creation_date": "2026-01-01T00:00:00.000Z"
}
  • 400 The original_url is not a valid URL.
  • 500 Internal server error while creating the short URL.
GET /api/url/:short_url

Get a stored URL

Fetches a single stored URL by its short code.

Parameters
Name Type Required Description
short_url string yes Short code identifying the stored URL.
Responses
  • 200 The requested URL document `{ original_url, short_url, creation_date }`. 
    {
  "original_url": "https://example.com",
  "short_url": 12345,
  "creation_date": "2026-01-01T00:00:00.000Z"
}
  • 500 No URL found for the given short code; returns `{ error: 'URL not found' }`. 
    {
  "error": "URL not found"
}
  • 500 Internal server error while reading from the database.
DELETE /api/url/delete/:short_url

Delete a short URL

Deletes a stored URL by its short code.

Parameters
Name Type Required Description
short_url string yes Short code of the URL to delete.
Responses
  • 200 The deleted URL document `{ original_url, short_url, creation_date }`. 
    {
  "original_url": "https://example.com",
  "short_url": 12345,
  "creation_date": "2026-01-01T00:00:00.000Z"
}
  • 500 No URL found for the given short code; returns `{ error: 'URL not found' }`. 
    {
  "error": "URL not found"
}
  • 500 Internal server error while deleting from the database.

Group Gemini

GET /api/gemini/getFromText

Generate text from a prompt

Generates text using Gemini from a text-only prompt supplied as a query parameter.

Parameters
Name Type Required Description
prompt string yes The prompt to send to the model.
Responses
  • 200 Generated text response.
  • 400 The prompt query parameter is missing. 
    {
  "error": "Prompt is required"
}
  • 503 Service temporarily unavailable; returns `{ status: 503, warning: 'This service is temporarily unavailable' }`. 
    {
  "status": 503,
  "warning": "This service is temporarily unavailable"
}
GET /api/gemini/getChatFromText/:prompt

Generate text with chat context

Generates a reply using Gemini, maintaining conversation history in the session to build context.

Parameters
Name Type Required Description
prompt string yes The user message for this turn of the conversation.
Responses
  • 200 Generated reply text.
  • 404 The `:prompt` path segment is omitted; Express cannot match the route.
  • 503 Gemini service temporarily unavailable. 
    {
  "status": 503,
  "warning": "This service is temporarily unavailable"
}
POST /api/gemini/getFromImage

Generate text from image and prompt

Generates text using Gemini from a multimodal input of an uploaded image plus an optional prompt. The uploaded file is deleted after processing.

Parameters
Name Type Required Description
image file yes Uploaded image (multipart/form-data), max 2 MB.
prompt string no Optional text prompt to accompany the image.
Responses
  • 200 Generated text response based on the image and prompt.
  • 400 The prompt or image field is missing. 
    {
  "error": "Prompt is required"
}
  • 503 Service temporarily unavailable; returns `{ status: 503, warning: 'This service is temporarily unavailable' }`. 
    {
  "status": 503,
  "warning": "This service is temporarily unavailable"
}

Overview

khanos.backend 😍

The Express API behind my site. Three small services that each solve a real problem I had, kept behind a shared middleware stack and covered by tests.

Live: khanos-backend.herokuapp.com

What it does

All endpoints below are mounted under /api/ (see server.js). The JSON route catalog is served at GET /api/.

Endpoint Purpose
GET /api/github/getCommits/:word Search my commit history by keyword
GET /api/github/getCommitsByRepoAndOwner/:owner/:repo Commits for a specific repository
GET /api/url · POST /api/url/create · GET /api/url/:short_url · DELETE /api/url/delete/:short_url Mongoose-backed URL shortener
GET /api/gemini/getFromText · GET /api/gemini/getChatFromText/:prompt Gemini text and chat prompts
POST /api/gemini/getFromImage Gemini image prompts, 2 MB upload cap

The OpenAI endpoints (/api/openai/getResponse/:text, /api/openai/getImage/:text) are commented out in api/routes/index.js and not currently exposed.

Every request passes through helmet, CORS, compression, express-rate-limit, express-session and a single error-handling middleware, so no route does its own error plumbing. Controllers, services and models stay in separate layers: controllers handle HTTP, services own the outbound calls, models own the data.

Getting Started

To get started with the project, clone the repository and install the dependencies:

git clone https://github.com/Khanos/khanos.backend.git
cd khanos.backend
npm install

Running the Application

To start the application, use the following command:

npm start

The application will start and listen on port 3000.

Develop

To start the application in development mode, use the following command:

npm run dev

The application starts with hot reload and request logging enabled.

Testing

To run the tests and code coverage run the following command:

npm run test

To run the tests and watch for changes on the files, run the following command:

npm run test:watch

Project Structure

The project has the following structure:

  • api/: Contains the controllers, middlewares, models, routes, and services for the application.
  • public/: Contains the static files served by the application.
  • tests/: Contains the test files for the application.
  • views/: Contains the view templates for the application.

Controllers

  • MainController.js: Handles the main routes of the application.
  • GithubController.js: Handles the GitHub-related routes of the application.
  • GeminiController.js: Handles the Gemini-related routes of the application.
  • UrlShortenerController.js: Handles the URL shortening related routes of the application.

Services

  • GithubService.js: Service to interact with the GitHub API.
  • GeminiService.js: Service to interact with the Gemini API.
  • UrlShortenerService.js: Short-code generation and lookup for the URL shortener.

Middlewares

  • errorHandler.js: Central error handler; every route delegates its failures here.

Models

  • UrlModel.js: Model for URL data.

License

Licensed under the GNU Lesser General Public License v3.0.

This is a small fun project, you can view it on GitHub