Skip to main content

API Usage Guide

This guide covers best practices and common patterns for using the XD Soba API effectively.

Request Patterns​

Pagination​

Most list endpoints support pagination using the following query parameters:

?page=1&pageSize=20
  • page: The page number (starts at 1)
  • pageSize: Number of items per page (default: 20, max: 100)

Example response:

{
  "items": [...],
  "totalCount": 100,
  "pageSize": 20,
  "currentPage": 1,
  "totalPages": 5
}

Filtering​

Many endpoints support filtering using query parameters:

# Filter by date range
?startDate=2024-01-01&endDate=2024-12-31

# Filter by status
?status=active

# Search by text
?search=query

Sorting​

Sort results using the sortBy and sortDirection parameters:

?sortBy=createdAt&sortDirection=desc

Common Operations​

Creating Resources​

Most creation endpoints follow this pattern:

POST /gateway/{resource}
Content-Type: application/json

{
  "name": "Example",
  "description": "Optional description",
  "status": "active"
}

Updating Resources​

Update operations typically use PUT or PATCH:

PUT /gateway/{resource}/{id}
Content-Type: application/json

{
  "name": "Updated Name",
  "status": "inactive"
}

Deleting Resources​

Deletion is usually done with DELETE method:

DELETE /gateway/{resource}/{id}

Best Practices​

Error Handling​

  1. Always check the response status code
  2. Parse error responses for detailed information
  3. Implement retry logic for 5xx errors
  4. Handle rate limiting (429) appropriately

Performance​

  1. Use pagination to limit response size
  2. Implement client-side caching where appropriate
  3. Use compression (gzip) for large responses
  4. Batch operations when possible

Security​

  1. Never store tokens in client-side code
  2. Rotate API keys regularly
  3. Use HTTPS for all requests
  4. Validate all input data

Common Use Cases​

Entity Management​

# Create a new entity
POST /gateway/entities
{
  "name": "New Entity",
  "type": "customer"
}

# List entities with filters
GET /gateway/entities?type=customer&status=active

# Update entity
PUT /gateway/entities/{id}
{
  "status": "inactive"
}

Delivery Regions​

# Create delivery region
POST /gateway/delivery-regions
{
  "name": "Region Name",
  "boundaries": [...]
}

# List regions
GET /gateway/delivery-regions?active=true

Items and Groups​

# Create item
POST /gateway/items
{
  "name": "Item Name",
  "groupId": "group-id"
}

# List items in group
GET /gateway/items?groupId=group-id

Testing​

  1. Use the sandbox environment for testing
  2. Test error scenarios
  3. Verify rate limiting behavior
  4. Test with different data volumes

Support​

If you need help: