Tiny Rebrand DocsHome

API Structure

Understanding TinyRebrand's API request and response format conventions

TinyRebrand's API follows consistent patterns for requests and responses. Understanding these conventions will help you integrate more effectively and handle edge cases properly.

Base URL

https://api.tinyrebrand.com/api

Request Format

Authentication

All API requests must include an Authorization header with a valid access token. This can be either an OAuth access token or a Personal Access Token:

# OAuth access token
Authorization: Bearer at_1234567890abcdef

# Personal Access Token
Authorization: Bearer tkn_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789

Content Type

All requests with a body must specify the content type as JSON:

Content-Type: application/json

Request Body

Request bodies must be valid JSON. Here's an example of creating a new link:

POST /user/link
Content-Type: application/json
Authorization: Bearer at_1234567890abcdef

{
  "title": "My Website",
  "url": "https://example.com",
  "slug": "my-website",
  "status": true,
  "hasPassword": false,
  "domainId": "507f1f77bcf86cd799439011"
}

Response Format

All API responses follow a consistent structure with standardized fields:

Success Response

{
  "status": 200,
  "code": "OK",
  "message": "Link created successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "title": "My Website",
    "url": "https://example.com",
    "slug": "my-website",
    "shortUrl": "https://tiny.ly/my-website",
    "status": true,
    "hasPassword": false,
    "createdAt": "2024-01-15T10:00:00.000Z",
    "updatedAt": "2024-01-15T10:00:00.000Z"
  }
}

Error Response

{
  "status": 400,
  "code": "VALIDATION_ERROR",
  "message": "Validation failed",
  "meta": {
    "errors": [
      {"name": "url", "error": "The url field is required"},
      {"name": "slug", "error": "The slug must be unique"}
    ]
  }
}

Response Fields

FieldTypeDescription
statusnumberHTTP status code
codestringResponse code ('OK' for success, error codes for failures)
messagestringHuman-readable success or error message
dataobjectResponse data (for successful requests)
metaobjectAdditional metadata (pagination, error details, etc.)

HTTP Status Codes

Pagination

List endpoints support pagination using limit and start parameters:
GET /user/link?limit=10&start=20

{
  "status": 200,
  "code": "OK",
  "message": "Links fetched successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "title": "Example Link",
      "url": "https://example.com",
      "shortUrl": "https://tiny.ly/example"
    }
  ],
  "meta": {
    "total": 156,
    "start": 20,
    "limit": 10
  }
}

Query Parameters

ParameterTypeDescription
limitnumberNumber of items to return (max 100)
startnumberNumber of items to skip (offset)
qstringSearch query string

Date Formats

All dates are returned in ISO 8601 format with UTC timezone:
"createdAt": "2024-01-15T10:00:00.000Z"
"updatedAt": "2024-01-15T10:00:00.000Z"
"expiresAt": "2024-02-15T10:00:00.000Z"

Field Naming Conventions

  • camelCase: All field names use camelCase formatting
  • Consistent naming: Similar fields use consistent names across endpoints
  • Descriptive names: Field names clearly indicate their purpose
  • Boolean fields: Use "is", "has", or "can" prefixes (e.g., "isActive", "hasPassword")

API Versioning

Currently, TinyRebrand API uses a single version. Future versions will be indicated in the URL:
# Current
https://api.tinyrebrand.com/api/user/me

# Future versioning (example)
https://api.tinyrebrand.com/api/v2/user/me

Best Practices

Example Implementation

// API client with consistent response handling
class TinyRebrandAPI {
  constructor(accessToken) {
    this.accessToken = accessToken;
    this.baseURL = 'https://api.tinyrebrand.com/api';
  }

  async makeRequest(endpoint, options = {}) {
    const response = await fetch(`${this.baseURL}${endpoint}`, {
      headers: {
        'Authorization': `Bearer ${this.accessToken}`,
        'Content-Type': 'application/json',
        ...options.headers
      },
      ...options
    });

    const data = await response.json();

    if (data.status >= 400 || data.code !== 'OK') {
      throw new Error(data.message || 'API request failed');
    }

    return { data: data.data, meta: data.meta };
  }

  async getLinks(options = {}) {
    const { limit = 10, start = 0, q } = options;
    const params = new URLSearchParams({ limit, start });
    if (q) params.append('q', q);
    
    return this.makeRequest(`/user/link?${params}`);
  }
}