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