Working with the API

Overview

This section covers practical patterns and best practices for building robust integrations with our API. You'll learn how to handle common scenarios, respect rate limits, and build efficient polling mechanisms.

---

Request and Response Patterns

Standard Request Structure

All API requests follow a consistent pattern:

[METHOD] https://api.equipme.io/v1/[resource]
Headers:
  X-API-Key: your_api_key_here
  Content-Type: application/json (for POST/PUT/PATCH)
Body: (JSON for POST/PUT/PATCH requests)

HTTP Methods

Our API uses standard HTTP methods with their conventional semantics:

Method	Purpose	Request Body	Response Body	Idempotent
GET	Retrieve resource(s)	No	Yes	Yes
POST	Create new resource	Yes	Yes (created resource)	No
PUT	Replace entire resource	Yes	Usually No	Yes
PATCH	Update specific fields	Yes	Usually No	Usually yes
DELETE	Remove resource	Usually No	Usually No	Yes

Idempotent means making the same request multiple times produces the same result as making it once.

PUT vs PATCH: We're transitioning from PUT to PATCH for updates. PUT endpoints require you to send the complete resource (all fields), while PATCH allows partial updates using JSON Patch operations. Check the API Reference for which method each endpoint supports.

Successful Responses

Status Code	When Used	Response Body
200 OK	Successful GET	Resource data
201 Created	Successful POST	Created resource including id
204 No Content	Successful DELETE or update with no return data	Empty

PATCH Requests with JSON Patch

For PATCH operations, we use the JSON Patch standard (RFC 6902). This allows you to precisely specify which fields to update without sending the entire resource.

Content-Type for PATCH requests:

Content-Type: application/json-patch+json

Common JSON Patch operations:

Operation	Purpose	Example
add	Add a new field or array element	Add an employee as manager
remove	Remove a field or array element	Clear a phone number
replace	Change a field's value	Update employee email address

Example PATCH request body:

json

[
  {
    "op": "replace",
    "path": "/status",
    "value": "active"
  },
  {
    "op": "replace",
    "path": "/email",
    "value": "[e-mail]"
  }
]

Benefits of JSON Patch:

• Send only the changes, not the entire resource
• Reduce bandwidth and processing overhead
• Support complex operations like array manipulation

See the API Reference for specific examples of PATCH operations for each endpoint.

---

Rate Limits

To ensure fair usage and platform stability, our API implements rate limiting.

Current Rate Limits

Request Type	Limit	Window
POST requests	100 requests	per second
All other requests	1000 requests	per minute

Rate limits apply per unique endpoint path with the same parameters. Different resource IDs are treated as separate endpoints.

Example:

• /v1/organization/employees/1 - 1000 requests/minute
• /v1/organization/employees/2 - 1000 requests/minute (separate limit)

Rate Limit Headers

Every successful API response includes headers indicating your current rate limit status:

X-Rate-Limit-Limit: 1000
X-Rate-Limit-Remaining: 847
X-Rate-Limit-Reset: 2026-02-06T12:14:12.5987061Z

Header	Description
X-Rate-Limit-Limit	Maximum requests allowed in the window
X-Rate-Limit-Remaining	Requests remaining in current window
X-Rate-Limit-Reset	Timestamp when the limit resets

Rate Limit Exceeded

When you exceed the rate limit, the API returns:

Status Code: 429 Too Many Requests

Headers:

Retry-After: 45

The Retry-After header indicates how many seconds to wait before retrying.

Example error response:

json

{
  "errorCode": "TooManyRequests",
  "errorDescription": "API calls quota exceeded! Maximum admitted 1000 per 1m."
}

Handling Rate Limits

Best Practices

1. Monitor rate limit headers proactively - Check X-Rate-Limit-Remaining in your responses to anticipate when you'll hit the limit
2. Implement exponential backoff - When you receive a 429 response, wait the time specified in Retry-After (or use exponential backoff for other errors)
3. Use request queuing - For applications making many requests, implement a queue that controls the request rate to stay below limits
4. Respect the Retry-After header - Always honor the wait time specified by the server
5. Distribute requests over time - Avoid sending bursts of requests; spread them evenly across the time window
6. Cache stable data - Don't repeatedly fetch resources that rarely change
7. Use date filters for polling - Only fetch resources that have changed since your last sync
8. Consider separate API keys - Use different keys for independent services to isolate their rate limits

---

Common Integration Patterns

Pattern 1: Initial Data Synchronization

When setting up a new integration, you'll need to fetch all existing data:

Approach:

1. Start with the first page of the list endpoint
2. Process the items (store in your database, etc.)
3. Follow the next link to retrieve the next page
4. Repeat until next is null
5. Store the current timestamp for future incremental updates

Considerations:

• Add small delays between pages to respect rate limits
• Track progress (items processed vs. total) for monitoring
• Handle interruptions gracefully (store last successfully processed page)

Pattern 2: Incremental Updates (Polling)

After initial synchronization, regularly check for changes:

Approach:

1. Retrieve your last sync timestamp
2. Make a request with updatedAfter filter using that timestamp
3. Process all pages of changed resources
4. Update your local data store
5. Store the current timestamp as the new "last sync"

Best Practices:

• Choose polling intervals based on your business needs (see table below)
• Use after/updatedAfter filters to minimize data transfer
• Handle pagination properly - changes might span multiple pages
• Add a small time overlap (e.g., subtract 1-2 seconds from last sync) to account for potential clock drift

Update Frequency	Recommended Interval	Use Case
Real-time	1-2 minutes	Critical order updates
Regular	30-60 minutes	General synchronization
Periodic	2-24 hours	Historical data, reports, re-sync

Pattern 3: Bulk Operations

When you need to create or update many resources:

Considerations:

• Implement request queuing to respect rate limits (especially the limit for POST requests)
• Process items in batches with delays between batches
• Track successes and failures separately
• Implement retry logic for failed operations
• Provide progress indicators for long-running operations

Error Handling:

• Don't stop the entire batch on first error
• Collect all failures for review
• Log failures with context for debugging
• Consider implementing a dead-letter queue for problematic items

Pattern 4: Detecting Deletions

The API returns 404 for deleted resources, but how do you detect deletions during polling?

Approach 1: Full reconciliation (periodic)

• Periodically fetch all resource IDs from the API
• Compare with your local database
• Mark resources missing from API as deleted

Approach 2: Handle 404s during detail fetches

• When fetching specific resources that return 404, mark them as deleted or inaccessible
• Note: 404 could mean deleted OR no access due to permissions

---

Error Handling Strategies

All API integrations should implement robust error handling to deal with various failure scenarios. Our API uses standard HTTP status codes and provides detailed error responses to help you diagnose and resolve issues.

Key principles:

• Always check HTTP status codes before processing responses
• Implement retry logic for transient errors (rate limits, server errors)
• Don't retry authentication or business logic errors
• Log errors with sufficient context for debugging

For comprehensive information on error handling, including:

• Complete error response format
• All error codes and their meanings
• Retry strategies and exponential backoff patterns
• Troubleshooting guides for common issues

See the Error Handling chapter.

---

Performance Optimization

Minimize Unnecessary Requests

Strategies:

• Use list responses when they contain sufficient data; don't fetch details unnecessarily
• Cache stable resources (employee profiles that rarely change)
• Batch related operations when possible
• Use date filters to fetch only changed data

---

Testing Your Integration

Testing Checklist

Before deploying your integration to production, verify:

• Authentication works - API key is valid and requests succeed
• Error handling - Application handles all error types gracefully
• Rate limiting - Retry logic works correctly for 429 responses
• Pagination - All pages are fetched correctly; navigation links work
• Date filtering - Polling correctly fetches only changed data
• Network failures - Timeouts and connection errors are handled
• Empty responses - Application handles zero results correctly
• Large datasets - System handles maximum pagination limits
• Concurrent requests - Thread safety if using parallel requests
• Deleted resources - 404 responses handled appropriately
• JSON Patch operations - PATCH requests formatted correctly

---

Debugging Tips

Common issues and solutions:

1. Intermittent 401 errors - Check if API key has expiration date
2. Slow requests - Check network latency; consider geographic location
3. Missing data in polls - Verify date filter includes correct timezone (UTC)
4. Pagination stops early - Check if you're properly following next links
5. Rate limit hits - Monitor X-Rate-Limit-Remaining; implement request queuing