The SPY System provides two distinct APIs, each designed for specific use cases. These APIs are not traditional versions but serve separate purposes with unique functionalities. Please use the tabs above to navigate to the detailed documentation for each API.

Understanding the APIsCopied!

API V1: Sales and Purchase OperationsCopied!

This API is designed for managing transactional data such as orders and deliveries. It is ideal for businesses that need to automate:

• Creating Sales Orders: Streamline your order management processes.
• Fetching Purchase Orders: Retrieve detailed information about your procurement activities.

API V2: Style and Product Data ManagementCopied!

Focused on managing product-related information, this API helps you handle core business metadata. It includes capabilities like:

• Managing Style Base Data: Create, update, and list styles, colors, and related attributes.
• Retrieving Metadata: Access auxiliary data such as brands, countries, genders, and more, to enrich your product information.

Getting StartedCopied!

1. Choose the appropriate API:
   • Use API V1 for operational transactional data (e.g., orders, deliveries).
   • Use API V2 for managing product metadata (e.g., styles, brands).
2. Refer to detailed documentation: Use the tabs above to access comprehensive guides, endpoint specifications, and examples for each API.

Best PracticesCopied!

Authentication and Connection ManagementCopied!

To ensure reliable and efficient access to the SPY System API, it's crucial to manage your authentication tokens effectively and respect rate limits.

Preventing Disconnections and Timeouts: Excessive authentication requests can lead to disconnections and timeouts due to strict rate limits. Specifically, the authentication endpoint has a limit of 1 request per 6 seconds. This limit is in place to mitigate brute-force attacks and enhance security.

Common Endpoints Affected by Rate Limits: We frequently observe systems hitting the rate limit on the following endpoints:

• /api/v1/auth/login
• /api/v1/variants

Recommended Token Management: Instead of authenticating for every API call or task, we strongly recommend caching and reusing authentication tokens within your system. This significantly reduces the number of authentication requests and improves overall performance.

Our Internal Authentication Strategy (for inspiration): When integrating with external systems, we implement the following authentication token management:

1. Token Caching: Upon successful authentication, we save the token to a database (typically Redis) with an attached expiration date. For communication with the SPY API, we suggest setting a token expiration time of 13 minutes.
2. Automated Token Handling via Middleware: Our API clients incorporate middleware that automates token management:
   • Retrieve Token: Before making a request, the middleware checks the database for an existing valid token. If found, it's used directly.
   • Acquire New Token: If no token is found or the existing one has expired, the middleware calls the authentication endpoint and saves the new token to the database.
   • Handle Invalid Tokens: If a request fails due to an invalid authentication token (even if provided), the middleware automatically removes the expired token from the database and re-authenticates to acquire a fresh token.

Handling Rate Limits (HTTP 429 Responses)Copied!

To robustly handle 429 Too Many Requests responses, we recommend implementing a retry mechanism with exponential backoff:

1. Middleware Implementation: Utilize middleware to intercept 429 responses.
2. Initial Delay: Upon receiving a 429, pause for a short duration (e.g., 1 second for the first retry).
3. Exponential Backoff: If subsequent retries also result in a 429, increase the delay before the next attempt (e.g., double the sleep time).
4. Retry Limit: Implement a maximum number of retries to prevent indefinite looping.

This strategy ensures that your application gracefully handles temporary rate limit exceedances without overwhelming the API.