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

Both token types work identically for API calls. The only difference is how they're obtained and managed.

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

Field	Type	Description
status	number	HTTP status code
code	string	Response code ('OK' for success, error codes for failures)
message	string	Human-readable success or error message
data	object	Response data (for successful requests)
meta	object	Additional metadata (pagination, error details, etc.)

HTTP Status Codes

2xx Success

• 200 OK - Request successful
• 201 Created - Resource created
• 204 No Content - Success, no data

4xx Client Errors

• 400 Bad Request - Invalid request
• 401 Unauthorized - Invalid token
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource not found
• 429 Too Many Requests - Rate limited

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

Parameter	Type	Description
limit	number	Number of items to return (max 100)
start	number	Number of items to skip (offset)
q	string	Search 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

Check Status and Code Fields: Use HTTP status codes and the "code" field to determine success or failure. Success responses have status 2xx and code "OK".

Handle Pagination Correctly: Use the "total" field in meta to determine total count and calculate if there are more pages.

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}`);
  }
}

Rate Limits

Error Handling