Synchronous and Asynchronous APIs

Every API call follows a request and response pattern, but when and how you receive the response differs depending on the type of API. Understanding the difference helps you choose the right approach for your application, avoid timeouts, and design an integration that scales with your data needs.

Synchronous APIs

A synchronous API processes your request and returns the result in the same HTTP connection. Your application sends a request, waits, and receives either the data or an error in the response. Nothing further is needed to get the result.

How It Works

1. Your application sends a request to the API.
2. The API processes the request immediately.
3. The API returns the full response (data or error) on the same connection.
4. Your application continues with its next step.

Characteristics

• Immediate results. The response contains the data you asked for, so there is no second step to retrieve it.
• Simple to implement. One request produces one response, which makes the flow easy to code, test, and debug.
• Bounded by timeouts. Because the connection stays open, the request must finish within the client's and server's timeout limits. Very large or complex requests may not complete in time.
• Blocking. The calling thread or process waits for the response unless your code explicitly handles the call in the background.

Best Suited For

• Looking up a small number of investments or data points.
• Interactive experiences, such as populating a screen when a user opens a page or runs a search.
• Workflows where the next step depends directly on the previous result.
• Quick validation or lookup calls.

Asynchronous APIs

An asynchronous API accepts your request, acknowledges it, and processes it in the background. Instead of returning the data right away, the API returns a reference, such as a job or request identifier, that you use to check on the work and retrieve the results when they are ready.

How It Works

1. Your application submits a request to the API.
2. The API validates the request and responds right away with an acknowledgment and an identifier for the job.
3. The API processes the request in the background.
4. Your application finds out the job is complete, either by polling a status endpoint at intervals or by receiving a notification, if supported.
5. Your application retrieves the results using the job identifier.

Characteristics

• Non-blocking. Your application is free to do other work, or submit additional requests, while the first request is processed.
• Built for volume. Large requests, such as many identifiers or long time series, can run for as long as needed without holding a connection open.
• More moving parts. Your application must track job identifiers, check status, handle partial failures, and retrieve results in a separate call.
• Results are available later. There is a delay between submitting a request and having data, so the design must tolerate waiting.

Best Suited For

• Bulk retrieval across large lists of investments.
• Scheduled or overnight data loads and batch jobs.
• Requests that are known to take longer than a typical timeout window.
• Back-end pipelines where no user is waiting on the response.

Side-By-Side Comparison

Choosing Between Synchronous and Asynchronous

Use the following questions to guide your decision.

• Is a person or process waiting on the answer right now? If yes, a synchronous API usually gives the best experience.
• How much data are you requesting? Small requests fit comfortably in a synchronous call. If a request is large enough to risk a timeout, choose an asynchronous API.
• How many requests do you need to run at once? If you need to process many requests in parallel without tying up your application, asynchronous is the better fit.
• How much complexity can your integration take on? Synchronous is simpler. Choose asynchronous when the scale or duration of the work justifies the extra handling.

Many applications use both. For example, an application might use a synchronous API to display data for a single investment on demand, and an asynchronous API to refresh data for an entire universe of investments overnight.

Handling Requests with No Results

Both synchronous and asynchronous APIs can return a successful response in which some of the queried investments have no data. Where applicable, the response metadata lists the queried investment identifiers for which no results were returned, along with the reason. Common reasons include:

• Account is not entitled for the identifier.
• Identifier was not recognized.

A successful response does not guarantee that every identifier you queried has data. Check the metadata in each response, and handle unreturned identifiers in your application, for example by logging them, retrying after correcting the identifier, or contacting your account representative about entitlements.

Best Practices

For Synchronous APIs

• Set client timeouts that match the expected response time, and handle timeout errors gracefully.
• Keep requests small and focused. If requests regularly grow large or slow, consider moving to an asynchronous approach.
• Retry only when it is safe to do so, and use backoff between attempts.

For Asynchronous APIs

• Store the job identifier as soon as you receive it, so you can recover if your application restarts.
• Poll for status at a reasonable interval rather than continuously, to avoid unnecessary load and rate limiting.
• Handle every job outcome, including completed, failed, and partially completed jobs.
• Retrieve results promptly, as they may only be available for a limited time.

For Both

• Inspect response metadata for unreturned identifiers on every call.
• Log request and job identifiers to simplify troubleshooting.
• Respect rate limits and handle error responses explicitly.