# 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:


```http
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
```

### Request Body

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


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

## HTTP Methods

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 |


## Response Format

All successful responses return JSON:


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

### Success Status Codes

| Code | Meaning |
|  --- | --- |
| `200` | OK - Request successful |
| `201` | Created - Resource created successfully |
| `204` | No Content - Success with no response body |


## Pagination

List endpoints support pagination:

### Query Parameters


```http
GET /api/orders/?limit=50&offset=0
```

| Parameter | Description | Default |
|  --- | --- | --- |
| `limit` | Number of results per page | 10 |
| `offset` | Starting position | 0 |


### Paginated Response


```json
{
  "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:


```http
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:


```http
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:


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

## Rate Limiting

Current limits:

- **1000 requests per hour** per API token
- **Rate limit headers** included in responses:



```http
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1640000000
```

div
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:


```http
Idempotency-Key: unique-key-12345
```

This prevents duplicate resource creation if you retry the request.

## Request Examples

### GET - Retrieve a Resource


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

### POST - Create a Resource


```bash
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


```bash
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


```bash
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:


```javascript
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:


```python
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:


```bash
# 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:


```javascript
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

- [Error Handling →](/getting-started/error-handling)
- [EUDR Compliance Use Case →](/use-cases/eudr-compliance)
- [API Reference →](/supply-chain-api)