Skip to main content

Getting Started

Welcome to the XD Soba API documentation! This guide will help you get started with our API, covering authentication, basic usage, and common patterns.

Authentication​

All API requests require authentication using JWT (JSON Web Tokens). To authenticate:

  1. Send a POST request to /gateway/auth/login with your credentials
  2. Use the returned token in the Authorization header for subsequent requests
# Example login request
curl -X POST "https://api.xdsoba.com/gateway/auth/login" \
     -H "Content-Type: application/json" \
     -d '{"username": "your_username", "password": "your_password"}'

Include the token in your requests:

curl -X GET "https://api.xdsoba.com/gateway/your-endpoint" \
     -H "Authorization: Bearer your_token_here"

Base URL​

All API endpoints are relative to the base URL:

https://api.xdsoba.com

Common Headers​

Include these headers in your requests:

  • Authorization: Bearer <token> - Required for authenticated endpoints
  • Content-Type: application/json - Required for POST/PUT requests
  • Accept: application/json - Recommended for all requests

Rate Limiting​

To ensure fair usage and system stability, we implement rate limiting:

  • 100 requests per minute per API key
  • Rate limit headers are included in responses:
    • X-RateLimit-Limit: Maximum requests per window
    • X-RateLimit-Remaining: Remaining requests in current window
    • X-RateLimit-Reset: Time until the rate limit resets

Error Handling​

The API uses standard HTTP status codes and returns error details in the response body:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message",
    "details": "Additional error details if available"
  }
}

Common status codes:

  • 200 OK: Request successful
  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Invalid or missing authentication
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server-side error

Next Steps​

Now that you understand the basics, you can:

Need help? Contact our support team at support@xdsoba.com