Skip to main content

API Usage Guide

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

Request Patterns​

Pagination​

Most listing endpoints support pagination using the following parameters:

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

Example response:

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

Filters​

Many endpoints support filters 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​

Create Resources​

Most creation endpoints follow this pattern:

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

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

Update Resources​

Update operations typically use PUT or PATCH:

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

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

Delete Resources​

Deletion is usually done with the DELETE method:

DELETE /{resource}/{id}

Best Practices​

Error Handling​

  1. Always check the response status code
  2. Analyze 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 when 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/entity
{
  "name": "New Entity",
  "entityType": "0"
}

Delivery Regions​

# Create delivery region
POST /gateway/delivery-region
{
  "id": "1",
  "description": "Region Name"
}

Items​

# Create item
POST /gateway/item
{
  "keyId": "IT01",
  "description": "Item Name"
}

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: