REST Web Services Request Processing

Besides synchronous execution, you can also execute requests asynchronously in REST web services.

The asynchronous execution of requests is useful for long-running requests. With asynchronous requests, you send a request to REST web services, where it is placed in a processing queue and handled asynchronously with other requests. Your client application does not wait for a response. After a job is submitted, a job ID is returned in the REST web services response. Your client application can then check the status and result of the request by referencing the job ID. Asynchronous processing can be useful if you expect your connection to NetSuite to be slow or unstable.

Asynchronous REST jobs are handled within REST Async Processors, according to the number of SuiteCloud Plus licenses. For information about SuiteCloud Plus, see SuiteCloud Plus Settings.

Note:

The processing of asynchronous REST calls does not affect the governance limits of asynchronous SuiteScript processes. The governance limits are calculated independently. However, extensive async REST usage can affect the overall performance so it may cause performance degradation in the running of scripts.

Asynchronous request execution also supports an idempotency retry mechanism, which allows you to handle a particular query through a unique key. Idempotent retry helps to avoid creating duplicate records, and it prevents the submission of the same task multiple times. It also helps you find loose-running jobs after a connection failure.

You can execute any REST request asynchronously by using the Prefer: respond-async request header. The response to the request contains the following HTTP header that you can use to retrieve the status of the request: Location: https://demo123.suitetalk.api.netsuite.com/services/rest/async/v1/job/<id>.

Sending an Asynchronous Request

You can send a request similar to the following:

            POST https://demo123.suitetalk.api.netsuite.com/services/rest/record/v1/customer/<id>?fields=companyName,email,entityStatus
 Prefer: respond-async

The following is an example response. The job ID is displayed in the location response header.

            HTTP 202 Accepted
Preference-Applied: respond-async
Content-Type: application/json
Location: /services/rest/async/v1/job/123456

Then you can send a request using the job ID in the response header to retrieve the status of the request that is in progress: GET https://demo123.suitetalk.api.netsuite.com/services/rest/async/v1/job/1.

The following is the response:

            {
    "links": [
        {
            "rel": "self",
            "href": "https://demo123.suitetalk.api.netsuite.com/services/rest/async/v1/job/1"
        }
    ],
    "completed": false,
    "id": "1",
    "progress": "pending",
    "task": {
        "links": [
            {
                "rel": "self",
                "href": "https://demo123.suitetalk.api.netsuite.com/services/rest/async/v1/job/1/task"
            }
        ]
    }
}

Sending an Asynchronous Request Using an Idempotency Key

The following is an example of a request that contains an idempotency key. The idempotency key enables you to refer to a request through a unique key, and also helps you avoid duplicate requests.

            POST /services/rest/record/v1/account
X-NetSuite-idempotency-key: cac827ea-3543-4cda-add2-bae634326c27
prefer: respond-async
{
  "name" : "My secret account"
}

The following is an example of a response you receive after sending a duplicate request.

            HTTP 400 Conflict
Preference-Applied: respond-async
Location: /services/rest/async/v1/job/123456
Content-Type: application/json
{
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10",
    "title": "Conflict",
    "status": 400,
    "o:errorDetails": [
        {
            "detail": "A request with the same idempotency key is already submitted.             See the "Location" header for a link to the previously submitted job",
            "o:errorCode": "IDEMPOTENCY_ERROR"
        }
    ]
}

Polling for the Status of a Completed Asynchronous Request

You can send a request similar to the following to get the task ID of the asynchronous request: GET https://demo123.suitetalk.api.netsuite.com/services/rest/async/v1/job/1/task/

Then you can send a request similar to the following to see the status of a completed asynchronous request: GET https://demo123.suitetalk.api.netsuite.com/services/rest/async/v1/job/1/task/1

The following example shows the returned result:

            {
    "links": [
        {
            "rel": "related",
            "href": "https://demo123.suitetalk.api.netsuite.com/services/rest/async/v1/job/1/task/1/result"
        },
        {
            "rel": "self",
            "href": "https://demo123.suitetalk.api.netsuite.com/services/rest/async/v1/job/1/task/1"
        },
    ],
    "completed": true,
    "endTime":  2020-12-09T12:04:40Z,
    "id": "1",
    "progress": "succeeded",
    "startTime": "2020-12-09T12:04:28Z"
}

Getting the Result of an Executed Request

You can send a request similar to the following to get the result of the executed request: GET https://demo123.suitetalk.api.netsuite.com/services/rest/async/v1/job/1/task/1/result.