This article introduces how to use Kintone's
kintone.api() method to run Kintone REST APIs.
This method can be used in the following three ways:
Method 1: Using Callbacks
A callback is a function that is passed as an argument to another function.
kintone.api() chooses which of the callbacks to call, depending on the success or failure of the API. Specify the success callback function as the fourth argument and the error callback function as the fifth argument.
Below is an example of writing callback functions when running the Get Record API. This code retrieves data from an example Product App within Kintone and displays the record contents in the console.
When the REST API request succeeds, the
successCallback function is called.
In some cases, named functions such as
failureCallback do not need to be specified, as shown in the code below.
There are two things to be careful about when using callbacks in the
- The function will proceed to the next line of code without waiting for the asynchronous method to finish
- Callback hell is likely to occur when callbacks are performed many times
More details are explained below.
The function will proceed to the next line of code without waiting for the asynchronous method to finish
kintone.api() is an asynchronous method. Although callbacks will run after the asynchornous call gives back a response, the line after
kintone.api() in the code will run without waiting for the asynchronous call to finish.
For example, let's retrieve a record from the Product App, update the
event object, and return the
event object so that the "price" field is saved into the Quotation App. The following sample updates the
event object within the callback, but will result in the "price" field being empty.
In the above example, the code runs
kintone.api(), which is an asynchronous method. As asynchronous methods run simultaneously, the next line of code,
return event, runs before
kintone.api() finishes the callback.
The flow is as follows:
kintone.api()runs and makes a call to the
- The response from
/k/v1/record.jsonis received, thus kicks off the callback function
const itemRecord = resp.record;is run
event.record.price.value = itemRecord.amount.value;is run
event object was returned before it was updated. Therefore, no changes were made to the "price" field.
The nesting of callbacks can lead to a phenomenon commonly known as callback hell.
In the following example,
kintone.api() is used to retrieve three records from a Product app one after another, using callbacks. The nested callbacks are stacked below one after another, forming a pyramid structure, making the code difficult to read and maintain. This scenario is termed callback hell.
Method 2: Using Promises
To solve these problems with asynchronous calls and callbacks, use Promises.
A Promise is an object representing the eventual completion or failure of an asynchronous operation. Promises can be used with the
Resolve the problem of functions proceeding to the next line of code without waiting for asynchronous methods to finish
The following example is the code of The function will proceed to the next line of code without waiting for the asynchronous method to finish problem rewritten using Promises.
By omitting the callback function,
kintone.api() returns a Promise object.
Kintone events have a mechanism to wait for the asynchronous methods to finish running if the Promise object is returned (note that not all events are supported).
In the example code above, the event waits for
kintone.api() to finish. One of the two callback methods within the
then() method then runs, depending on the success or failure of the call. If the call succeeds, the promise is "fulfilled", and the record of the Quotation app will be updated. If the call fails, the promise is "rejected", and the error details are displayed in the console.
Resolve callback hell using Promises
Promises can solve callback hell. The following example is the code of the Callback hell problem rewritten using Promises.
Compared to the previous callback hell code, the nesting is shallower, and the code is easier to read.
return kintone.api() in line 6, 9 and 13 returns Promise objects. By returning a Promise object in the event handler, the next operation can be processed after waiting for asynchronous processes in the event handler to finish.
Method 3: Using Async/Await
Async/await is also a method to escape the callback hell. It serves as a better way of approaching promises because it is removing the usage of
then() method, which again depends on callbacks.
Resolve function not waiting for callbacks to finish
The following example is the code of Resolve the problem of functions proceeding to the next line of code without waiting for asynchronous methods to finish rewritten using async/await.
There are two important points to note when using async/await:
- Functions using
awaitcan be used
- The operator
awaitneeds to be added at the beginning of an asynchronous function.
Therefore, in the above example, the following codes were implemented:
asyncwas added to the
awaitwas added at the beginning of the asynchronous
Resolve callback hell using Async/Await
The following example is the code of Resolve callback hell using Promises rewritten using async/await.
The process that was connected with
then() is eliminated, making the code clearer and easier to read.