Learn how to interact with Coolset APIs effectively.
All API requests should be made to:
https://developers-scranton.coolset.comEvery request must include:
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/jsonFor POST, PUT, and PATCH requests, send data as JSON:
{
"field1": "value1",
"field2": "value2"
}We use standard HTTP methods:
| Method | Usage |
|---|---|
GET | Retrieve resources |
POST | Create new resources |
PATCH | Update existing resources (partial) |
PUT | Update existing resources (full) |
DELETE | Remove resources |
All successful responses return JSON:
{
"id": 123,
"field": "value",
"created_at": "2024-10-28T12:00:00Z",
"updated_at": "2024-10-28T12:00:00Z"
}| Code | Meaning |
|---|---|
200 | OK - Request successful |
201 | Created - Resource created successfully |
204 | No Content - Success with no response body |
List endpoints support pagination:
GET /api/orders/?limit=50&offset=0| Parameter | Description | Default |
|---|---|---|
limit | Number of results per page | 10 |
offset | Starting position | 0 |
{
"count": 250,
"next": "https://developers-scranton.coolset.com/api/orders/?limit=50&offset=50",
"previous": null,
"results": [...]
}Many endpoints support filtering via query parameters:
GET /api/orders/?status=pending&created_after=2024-01-01Common filters:
created_at__gte- Created after datecreated_at__lte- Created before datesearch- Full-text search- Status and type filters (endpoint-specific)
Use the ordering parameter:
GET /api/orders/?ordering=-created_at- Prefix with
-for descending order - Multiple fields:
ordering=status,-created_at
(Coming soon) Select specific fields to reduce payload size:
GET /api/orders/?fields=id,identifier,statusCurrent limits:
- 1000 requests per hour per API token
- Rate limit headers included in responses:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1640000000If you exceed the rate limit, you'll receive a 429 Too Many Requests response. Wait until the reset time before retrying.
POST requests are idempotent when you include an idempotency key:
Idempotency-Key: unique-key-12345This prevents duplicate resource creation if you retry the request.
curl -X GET https://developers-scranton.coolset.com/api/orders/123/ \
-H "Authorization: Bearer YOUR_API_TOKEN"curl -X POST https://developers-scranton.coolset.com/api/orders/ \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"identifier": "ORDER-12345",
"type": "purchase",
"status": "pending"
}'curl -X PATCH https://developers-scranton.coolset.com/api/orders/123/ \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"status": "completed"
}'curl -X DELETE https://developers-scranton.coolset.com/api/orders/123/ \
-H "Authorization: Bearer YOUR_API_TOKEN"Always paginate large result sets:
async function getAllOrders() {
let allOrders = [];
let url = 'https://developers-scranton.coolset.com/api/orders/?limit=100';
while (url) {
const response = await fetch(url, { headers });
const data = await response.json();
allOrders = allOrders.concat(data.results);
url = data.next;
}
return allOrders;
}Implement exponential backoff:
import time
def make_request_with_retry(url, max_retries=3):
for attempt in range(max_retries):
response = requests.get(url, headers=headers)
if response.status_code == 429:
wait_time = 2 ** attempt
time.sleep(wait_time)
continue
return responseReduce data transfer by filtering server-side:
# Good: Filter on server
GET /api/orders/?status=pending
# Bad: Fetch all and filter client-side
GET /api/orders/ # Then filter locallyCache data when appropriate to reduce API calls:
const cache = new Map();
async function getOrder(id) {
if (cache.has(id)) {
return cache.get(id);
}
const order = await fetchOrder(id);
cache.set(id, order);
return order;
}