Data Hub API

Generic Open Data Backend

A Generic Open Data Backend

Store, serve, and manage any type of data with flexible JSON structures, JWT authentication, and a RESTful API design.

Get Started
View API Docs

Flexible Data Storage

Store any type of data using JSON-based structures with categories and types

JWT Authentication

Secure API with access and refresh tokens, role-based access control

RESTful API

Clean, intuitive endpoints following REST principles with consistent responses

Public Read Access

Data is publicly accessible, perfect for open data projects and APIs

Developer Friendly

Clear documentation, example requests, and consistent response formats

Production Ready

Open-source, MIT licensed, deployment-ready configuration

Overview

Data Hub API is a generic open data backend designed to store and serve ANY type of data using categories and flexible JSON structures. The API is designed to be consumed by web apps, mobile apps, dashboards, and external services.

Core Concepts

  • Categories: Organize data into logical groups (e.g., General, Documentation, API)
  • Data Types: Classify data by format (e.g., JSON, Text, Structured)
  • Data Entries: Store flexible JSON content with metadata
  • Role-Based Access: Admins can manage data, public users can only read

Authentication

The Data Hub API uses JWT (JSON Web Tokens) for authentication. Public endpoints (GET requests) do not require authentication. Write operations (POST, PUT, DELETE) require an access token with admin role.

Token Types

Access Token
  • • Expires in 15 minutes
  • • Used for API requests
  • • Include in Authorization header
Refresh Token
  • • Expires in 7 days
  • • Used to get new access tokens
  • • More secure, long-lived

Authentication Flow

  1. Send POST request to /api/auth/login with username and password
  2. Receive access token and refresh token in response
  3. Include access token in Authorization header: Bearer {token}
  4. When access token expires, use refresh token to get a new one
  5. Include new access token in subsequent requests

API Endpoints

Authentication

POST
/api/auth/login

Authenticate with username and password

🔒 Admin Only

POST
/api/auth/refresh

Refresh access token using refresh token

🔒 Admin Only

POST
/api/auth/logout

Logout current session

🔒 Admin Only

Data Management

GET
/api/data

Get all data entries (public read access)

Query Params: Optional: categoryId, typeId (query params)

✓ Public Access

GET
/api/data/:id

Get data entry by ID (public read access)

✓ Public Access

POST
/api/data

Create new data entry (admin only)

Request Body: Required: categoryId, typeId, title, content

🔒 Admin Only

PUT
/api/data/:id

Update data entry (admin only)

Request Body: Optional: categoryId, typeId, title, content, source

🔒 Admin Only

DELETE
/api/data/:id

Delete data entry (admin only)

🔒 Admin Only

Categories & Types

GET
/api/categories

Get all categories (public read access)

✓ Public Access

GET
/api/types

Get all data types (public read access)

✓ Public Access

Example Requests

Login (curl)

curl -X POST https://your-domain.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "JabesNelma",
    "password": "your-password"
  }'

Get All Data (curl)

curl https://your-domain.com/api/data

Create Data Entry (curl)

curl -X POST https://your-domain.com/api/data \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "categoryId": "category-id",
    "typeId": "type-id",
    "title": "My Data Entry",
    "content": {
      "key": "value",
      "nested": {
        "data": "here"
      }
    },
    "source": "example"
  }'

Fetch Data (JavaScript)

// Get all data (public)
const response = await fetch('https://your-domain.com/api/data');
const { success, data, message } = await response.json();

if (success) {
  console.log('Data entries:', data);
}

// Create data entry (requires admin token)
const createResponse = await fetch('https://your-domain.com/api/data', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  },
  body: JSON.stringify({
    categoryId: 'category-id',
    typeId: 'type-id',
    title: 'New Entry',
    content: { key: 'value' },
    source: 'my-app'
  })
});
const result = await createResponse.json();

Getting Started

1. Set Up the Project

  1. Clone the repository and install dependencies
  2. Configure environment variables in .env file
  3. Run database migrations
  4. Start the development server

2. Create Admin User

Use the seed endpoint to create your first admin user:

curl -X POST http://localhost:3000/api/admin/seed \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "secure-password",
    "seedKey": "admin-setup-key"
  }'

3. Start Using the API

Login with your admin credentials, get your access token, and start managing data entries.

Response Format

All API responses follow a consistent format:

{
  "success": true,
  "data": { ... },
  "message": "Operation completed successfully"
}

success: Boolean indicating if the request was successful
data: Response data (varies by endpoint)
message: Descriptive message about the operation