Base URL

All endpoints are relative to the following base URL. Prepend this to every path shown in this documentation:

https://localhost:7001

All responses are in application/json format unless stated otherwise. The Content-Type response header will always be application/json; charset=utf-8.

https://localhost:7001/api/users
https://localhost:7001/api/products?page=1&pageSize=20
https://localhost:7001/api/organisations/5
https://localhost:7001/api/auth/login

HTTPS only. All traffic is served over TLS. If you are running locally in development mode, your browser may warn about a self-signed certificate — accept the exception or configure a trusted dev cert with dotnet dev-certs https --trust.

Quick Start

Make your first API call in under 10 seconds — paste the URL below into your browser, cURL, or any HTTP client:

GET /api/users?page=1&pageSize=10

GET /api/users/1

GET /api/products?page=1&pageSize=5
GET /api/organisations
GET /api/todos?page=1&pageSize=10

You'll get back a paginated JSON response with realistic data immediately. No headers, no tokens, no body required for GET requests.

Step 1 — Browse Collections

Visit the API Collection page to see all available endpoint groups. Collections are organised by domain so you can quickly identify which group fits your use case.

Each collection card shows the domain name, a short description, and links directly to the endpoint explorer for that group. Hover over a card to see related endpoints, or click through to start interacting with the live data.

Auth
Users · Roles
Organisations · Departments · Employees · Teams
Blogs · Categories · Comments
Products · Cart
Todos
Transactions · Payments · Refunds

Not sure which collection to start with? If you're building a user-facing app, start with Users and Auth. For e-commerce UIs, try Products and Cart. For dashboard or admin tooling, Organisations and Transactions give rich relational data.

Step 2 — Pick an Endpoint

Click any collection card to open its endpoint explorer. Each endpoint documents the HTTP verb, full path, required and optional query parameters, request headers, and an example JSON response payload.

The endpoint explorer provides two quick-action buttons next to every URL:

Each endpoint section also shows example request headers. For public GET endpoints, no special headers are required. For endpoints that simulate protected resources, a sample Authorization: Bearer header is shown with the expected format.

Step 3 — Make a Request

All public GET endpoints accept requests with no authentication headers. Simply construct the URL and send the request from any client, framework, or language. Responses are returned synchronously — there is no polling or callback required.

curl https://localhost:7001/api/users

curl -v \
     -H "Accept: application/json" \
     https://localhost:7001/api/users?page=1&pageSize=5

const res = await fetch('/api/users?page=1&pageSize=10');
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const { data, totalRecords, totalPages } = await res.json();
console.log(`Loaded ${data.length} of ${totalRecords} users`);

import requests

r = requests.get('https://localhost:7001/api/users', params={'page': 1, 'pageSize': 10}, verify=False)
r.raise_for_status()
users = r.json()['data']
print(f"Fetched {len(users)} users")

Request headers: You do not need to set any headers for public endpoints. If you do send an Accept header, use application/json. Sending any other Accept value will still return JSON — BogusApi always responds in JSON.

Step 4 — Paginate Results

Every list endpoint supports cursor-free offset pagination via two query parameters. Omitting them defaults to page=1 and pageSize=10.

GET /api/users?page=2&pageSize=5

{
  "data": [
    { "id": 6, "name": "Carol White", "email": "carol@example.com" },
    { "id": 7, "name": "Dan Brown",  "email": "dan@example.com"   }
  ],
  "page": 2,
  "pageSize": 5,
  "totalRecords": 100,
  "totalPages": 20
}

Use totalPages and page together to build next/previous controls. When page exceeds totalPages, data will be an empty array.

let page = 1, all = [];
do {
  const res = await fetch(`/api/users?page=${page}&pageSize=20`);
  const json = await res.json();
  all = all.concat(json.data);
  if (page >= json.totalPages) break;
  page++;
} while (true);
console.log(`Total users fetched: ${all.length}`);

Step 5 — Auth Endpoints

Endpoints under /api/auth simulate a complete token-based authentication flow — login, token refresh, and logout. The mock JWT returned is structurally valid (three Base64 segments) and can be decoded by any standard JWT library, though it is not cryptographically signed with a real secret in development mode.

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "tokenType": "Bearer",
  "user": {
    "id": 42,
    "name": "Alice Johnson",
    "email": "user@example.com",
    "role": "Admin"
  }
}

GET /api/users/me
Authorization: Bearer <your-token>

POST /api/auth/refresh
Content-Type: application/json

{
  "refreshToken": "<refresh-token-from-login>"
}

POST /api/auth/logout
Authorization: Bearer <your-token>

Testing protected flows: Use the login endpoint to obtain a token, store it in your test environment (e.g., a Postman variable or a React context), then attach it to all subsequent requests via the Authorization header. The token expiry is simulated — you can call /api/auth/refresh to receive a new token.

Swagger UI

The built-in Swagger UI is auto-generated from the ASP.NET Core OpenAPI spec and lists every registered endpoint with full schema documentation and a live try-it-out interface. It requires no installation or configuration — just open the page in your browser.

1. Open https://localhost:7001/swagger in your browser
2. Find the endpoint group you want (e.g. Users)
3. Click to expand an operation (e.g. GET /api/users)
4. Click "Try it out" in the top-right of the panel
5. Fill in any parameters (page, pageSize, id…)
6. Click "Execute"
7. Inspect the response body, status code, and headers inline

Swagger UI also shows you the full request schema model — useful for understanding exactly which fields are required or optional before you write client code. For authenticated endpoints, click the Authorize button at the top of the page, paste your Bearer token, and all subsequent Try-it-out calls will include it automatically.

Postman

Postman is the most popular GUI HTTP client for API development. It supports saved collections, environment variables, pre-request scripts, automated test assertions, and team sharing. Import the BogusApi base URL into a new collection and you can build a full request library in minutes.

Environments → New Environment → "BogusApi Local"
Variable: baseUrl  →  https://localhost:7001
Variable: token    →  (leave empty, populated after login)

New Request → GET
URL: {{baseUrl}}/api/users?page=1&pageSize=10
Headers: Accept: application/json
Send

// Add this to the "Tests" tab of your login request
const json = pm.response.json();
pm.environment.set('token', json.token);

Authorization tab → Bearer Token → {{token}}

cURL

cURL ships pre-installed on macOS, most Linux distributions, and Windows 10+ (PowerShell). It requires no configuration and is the fastest way to probe an endpoint directly from a terminal or script. Use -s for silent output, -v for verbose headers, and pipe through jq for formatted JSON.

# Basic list
curl https://localhost:7001/api/users

# With pagination
curl "https://localhost:7001/api/users?page=1&pageSize=5"

# Pretty-print with jq
curl -s https://localhost:7001/api/users | jq .

# Get a single record by ID
curl https://localhost:7001/api/users/3

# Login and capture token
TOKEN=$(curl -s -X POST https://localhost:7001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"password123"}' \
  | jq -r '.token')

# Use token in next request
curl -H "Authorization: Bearer $TOKEN" \
     https://localhost:7001/api/users/me

curl -k https://localhost:7001/api/users

Fetch API

The browser-native fetch() function is available in all modern browsers and Node.js 18+. It supports async/await, streaming responses, AbortController for timeouts, and full control over headers and body. No third-party library is needed — it works out of the box in any JavaScript or TypeScript project.

const res = await fetch('/api/users?page=1&pageSize=10');
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const { data, totalRecords, totalPages } = await res.json();
console.log(`Page 1 of ${totalPages} — ${totalRecords} total users`);

const loginRes = await fetch('/api/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'user@example.com', password: 'password123' })
});
const { token } = await loginRes.json();
sessionStorage.setItem('token', token);

const token = sessionStorage.getItem('token');
const meRes = await fetch('/api/users/me', {
  headers: { 'Authorization': `Bearer ${token}` }
});
const user = await meRes.json();
console.log('Logged in as:', user.name);

const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 5000); // 5s timeout
try {
  const res = await fetch('/api/users', { signal: controller.signal });
  const json = await res.json();
} finally {
  clearTimeout(timer);
}

Axios

Axios is the most widely used HTTP client library in the JavaScript ecosystem. It supports automatic JSON serialisation and parsing, request/response interceptors, request cancellation, timeout configuration, and clean error objects. It works identically in the browser and in Node.js.

npm install axios
# or
yarn add axios

// api.js
import axios from 'axios';

const api = axios.create({
  baseURL: 'https://localhost:7001',
  timeout: 8000,
  headers: { 'Accept': 'application/json' }
});

export default api;

import api from './api';

// GET with query params
const { data } = await api.get('/api/users', { params: { page: 1, pageSize: 10 } });
console.log(data.data); // array of users

// POST login
const { data: auth } = await api.post('/api/auth/login', {
  email: 'user@example.com',
  password: 'password123'
});

api.interceptors.request.use(config => {
  const token = localStorage.getItem('token');
  if (token) config.headers['Authorization'] = `Bearer ${token}`;
  return config;
});

// Auto-redirect on 401
api.interceptors.response.use(
  res => res,
  err => {
    if (err.response?.status === 401) window.location.href = '/login';
    return Promise.reject(err);
  }
);

HTTPie

HTTPie is a modern CLI HTTP client designed for human readability. It colour-codes response bodies, auto-formats JSON, and uses an intuitive key=value syntax for request bodies and query parameters. It also supports sessions, file uploads, and plugin extensions.

# pip
pip install httpie

# macOS
brew install httpie

# Windows (Chocolatey)
choco install httpie

# Basic list (== is a query param in HTTPie)
http GET https://localhost:7001/api/users page==1 pageSize==10

# Get single record
http GET https://localhost:7001/api/users/5

# Ignore TLS in local dev
http --verify=no GET https://localhost:7001/api/products

# POST — key=value sends as JSON automatically
http POST https://localhost:7001/api/auth/login \
     email=user@example.com password=password123

# Authenticated GET
http GET https://localhost:7001/api/users/me \
     Authorization:"Bearer <token>"

# Session mode — stores cookies and headers across calls
http --session=./bogus.json GET https://localhost:7001/api/users

Response Format

All responses follow a consistent JSON envelope so your client code doesn't need to handle different shapes across collections. List endpoints always return a paginated wrapper. Single-resource endpoints (GET /api/users/{id}) return the resource object directly. Error responses always include a machine-readable error field.

{
  "data": [
    {
      "id": 1,
      "name": "Alice Johnson",
      "email": "alice@example.com",
      "username": "alice.johnson",
      "phone": "+1-555-0100",
      "role": "Admin",
      "createdAt": "2024-03-15T08:30:00Z"
    },
    {
      "id": 2,
      "name": "Bob Smith",
      "email": "bob@example.com",
      "username": "bob.smith",
      "phone": "+1-555-0101",
      "role": "User",
      "createdAt": "2024-04-02T12:00:00Z"
    }
  ],
  "page": 1,
  "pageSize": 10,
  "totalRecords": 250,
  "totalPages": 25
}

{
  "id": 1,
  "name": "Alice Johnson",
  "email": "alice@example.com",
  "username": "alice.johnson",
  "phone": "+1-555-0100",
  "role": "Admin",
  "createdAt": "2024-03-15T08:30:00Z"
}

{
  "error": "NotFound",
  "message": "User with id 9999 was not found.",
  "statusCode": 404
}

All date/time fields are in ISO 8601 UTC format (2024-03-15T08:30:00Z). Numeric IDs are integers. String IDs (where used) are UUID v4s. Boolean fields use lowercase true / false. Nullable fields may be null rather than omitted.

Status Codes

BogusApi follows standard HTTP semantics. Every response includes an appropriate status code that your client code can branch on. The response body for error codes always includes error, message, and statusCode fields.

Client code should always inspect the status code before reading the response body. A non-2xx code means data will not be present — use the error and message fields instead.

Query Parameters

The following query parameters are supported across all list endpoints. Parameters marked optional have sensible defaults and do not need to be sent on every request.

GET /api/users?search=alice&sortBy=createdAt&sortDir=desc&page=1&pageSize=5

Unknown or unsupported parameters are silently ignored and will not cause a 400 error.

API Collections

Every collection is documented with live endpoints. Click any name below to open its explorer: