Skip to main content

Making API Requests

Learn how to interact with Coolset APIs effectively.

Base URL​

All API requests should be made to:

https://developers-scranton.coolset.com

Request Format​

Headers​

Every request must include:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Request Body​

For POST, PUT, and PATCH requests, send data as JSON:

{
  "field1": "value1",
  "field2": "value2"
}

HTTP Methods​

We use standard HTTP methods:

MethodUsage
GETRetrieve resources
POSTCreate new resources
PATCHUpdate existing resources (partial)
PUTUpdate existing resources (full)
DELETERemove resources

Response Format​

All successful responses return JSON:

{
  "id": 123,
  "field": "value",
  "created_at": "2024-10-28T12:00:00Z",
  "updated_at": "2024-10-28T12:00:00Z"
}

Success Status Codes​

CodeMeaning
200OK - Request successful
201Created - Resource created successfully
204No Content - Success with no response body

Pagination​

List endpoints support pagination:

Query Parameters​

GET /api/orders/?limit=50&offset=0
ParameterDescriptionDefault
limitNumber of results per page10
offsetStarting position0

Paginated Response​

{
  "count": 250,
  "next": "https://developers-scranton.coolset.com/api/orders/?limit=50&offset=50",
  "previous": null,
  "results": [...]
}

Filtering​

Many endpoints support filtering via query parameters:

GET /api/orders/?status=pending&created_after=2024-01-01

Common filters:

  • created_at__gte - Created after date
  • created_at__lte - Created before date
  • search - Full-text search
  • Status and type filters (endpoint-specific)

Sorting​

Use the ordering parameter:

GET /api/orders/?ordering=-created_at
  • Prefix with - for descending order
  • Multiple fields: ordering=status,-created_at

Field Selection​

(Coming soon) Select specific fields to reduce payload size:

GET /api/orders/?fields=id,identifier,status

Rate Limiting​

Current 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: 1640000000
warning

If you exceed the rate limit, you'll receive a 429 Too Many Requests response. Wait until the reset time before retrying.

Idempotency​

POST requests are idempotent when you include an idempotency key:

Idempotency-Key: unique-key-12345

This prevents duplicate resource creation if you retry the request.

Request Examples​

GET - Retrieve a Resource​

curl -X GET https://developers-scranton.coolset.com/api/orders/123/ \
  -H "Authorization: Bearer YOUR_API_TOKEN"

POST - Create a Resource​

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"
  }'

PATCH - Update a Resource​

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"
  }'

DELETE - Remove a Resource​

curl -X DELETE https://developers-scranton.coolset.com/api/orders/123/ \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Best Practices​

1. Use Pagination​

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

2. Handle Rate Limits​

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 response

3. Use Filtering​

Reduce 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 locally

4. Cache Responses​

Cache 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;
}

Next Steps​