For some endpoints, Rutter support different response_mode
parameters. This parameter allows you to specify whether to:
- Call the API in a synchronous fashion & wait for the response. This is the default behavior if no response_mode is specified.
- Call the API in an asynchronous fashion, receive a response immediately with a URL pointer to the request job, and wait for the result to be updated via the URL.
Using the async response mode is recommended when:
- You want to make idempotent operations to avoid creating duplicate requests when sending the same payload. You can accomplish this by passing the distinct value through the
Idempotency-Key
request header. - You have specific latency requirements, and do not wish to wait multiple seconds for a response from the Rutter endpoint.
- You want to make a large set of operations at the same time. This allows Rutter to intelligently avoid rate limit when making many requests to an external platform.
Request: How to include the response_mode
parameter
The response_mode
parameter will appear in the request body of the API call. The value of the parameter can be either prefer_sync
or async
.
{
"response_mode": "async", // or "prefer_sync"
"invoice": {
"account_id": "00000000-0000-0000-0000-000000000000",
"customer_id": "00000000-0000-0000-0000-000000000000",
"due_date": "2023-01-02T02:34:56.000Z",
"issue_date": "2023-01-02T02:34:56.000Z",
"currency_code": "USD",
"line_items": [
{
"total_amount": 10,
"description": "A Rutter Shirt",
"item": {
"id": "00000000-0000-0000-0000-000000000000",
"quantity": 1,
"unit_amount": 10
}
}
]
}
}
Content-Type: "application/json"
Authorization: "Basic 00000"
User-Agent: "PostmanRuntime/7.32.3"
Accept: "application/json"
Cache-Control: "no-cache"
Postman-Token: "00000000-0000-0000-0000-000000000000"
Host: "production.rutterapi.com"
Accept-Encoding: "gzip, deflate, br"
Connection: "keep-alive"
Content-Length: "1000"
Idempotency-Key: "12345678-90ab-cdef-fedc-ba0987654321"
Response Mode: Prefer Sync
If you set response_mode
to be prefer_sync
, the request will try to return a synchronous response if the entire product is created within 30 seconds. If it takes longer, we will return an async_response object that contains a URL pointer to be used to query the status of the request as it continues to make progress on our server. This async_response object is the same format as if you set response_mode
to be async
.
Response Mode: Async
If you set response_mode
to be async
, the request will be run asynchronously and the API will immediately return an async_response. Query the response_url field on async_response for the status of the request.
If an async_response is returned, it has the following properties:
Property | Type | Description |
---|---|---|
id | String | A unique UUID string representing the ID of the Async Job. |
response_url | String | A link to the Fetch a Job endpoint. By making a GET request to this URL, you can retrieve the status and result of the job. |
status | String | The status of the job. One of the following
|
We suggest querying the response_url field for the status of the request. The response_url corresponds to the Fetch a Job endpoint, and will return the successful result or errors encountered during the request.
Async Job Webhook
When an Asynchronous Job is successful, we will also send a webhook to your configured webhook URLs.
{
"type": "JOB",
"code": "JOB_COMPLETED",
"job": {
"id": "3446b185-117f-46bc-939b-aa53de5c35c1",
"status": "success",
"request": {
"url": "https://production.rutterapi.com/versioned/products",
"method": "POST",
"body": {
// Asynchronous Job Request Body
}
},
"response": {
"http_status": 200,
"body": {
// Asynchronous Job Response Body
}
}
}
}
The AsynchronousJob object
Properties
id
stringstatus
enumresponse
objectoptionalresponse
attributesrequest
objectThe request that kicked off the job
request
attributesFetch a Job
GET /jobs/:idRequest Parameters
id
stringpathThe ID of the job.
Response Body
id
stringstatus
enumresponse
objectoptionalresponse
attributesrequest
objectThe request that kicked off the job
request
attributes