Kintone Technical Training - REST API

Here is the REST API study content of Kintone Technical Training.
If you want to access the reference link in it directly, please download this PDF file.
We hope you enjoy Kintone technical training journey!

[ Video ]
https://www.youtube.com/watch?v=VpWyDbhhEcg

[ Programs & App Template ]
https://github.com/Cybozu-GTA/kintone-technical-training-materials

Transcript

1. Kintone Technical Training - REST API 1 Cybozu, Inc.
2. 2 Notice • This material was created using the October 2020 version of Kintone. • We may change our contents without prior notice.
3. 3 Before you start… • You have a Kintone Account with Kintone administrator's privilege. • You have the understanding of some programming languages. • You installed Google Chrome and Visual Studio Code (VSCode). • You installed REST Client (Visual Studio Code Extension) to your Visual Studio Code environment. • You’ve downloaded the App Template (Company List, Sales Deals) and imported it. Lookup/Action Related Records Self Related Records Company List Sales Deals
4. 4 Agenda • How to Enhance Kintone usability • Kintone REST API • Request Method for Kintone REST API • Request Example of Kintone REST API • Hands-on • Create App from API • Add Record from API
5. 5 How to Enhance Kintone Usability
6. Kintone – A Visual Software Builder 6
7. 3 Pillars of The Kintone Platform Process Management Data Communication 7
8. 8 When/What Do the Users Need Enhancement? Data Generation Data Update Data Export Data Input Assistance Data Search Views Integration with Other services ü Bulk input ü Iterative data ü Bulk update ü Batch processing ü Excel ü CSV by own format ü Validation ü Automatic numbering ü Conditional format ü Filtering ü Search ü Aggregation ü Chart/Graph ü Calendar/Scheduler/Time sheet ü Map ü Mobile ü Invoice/Accounting ü Project management ü E-mail Typical cases ...
9. 9 How to Enhance Kintone Usability STEP1 STEP2 STEP3 STEP4 No-Code ü Native Features Extensions ü Plug-ins ü Connected Services Customization ü Coding Integrations ü iPaaS ü EAI, ETL
10. 10 Kintone Customization Functionalities Kintone JavaScript API Kintone REST API Allow users to connect with other services Allow users to customize the views on Kintone on built-in Kintone native views on canvas views Other services
11. 11 Kintone REST API & JavaScript API User/Department Data Process Management Communication • Events on Kintone views • Kintone REST API request Kintone JavaScript API • App records • App settings Kintone REST API • User/Department User API Views
12. 12 Kintone REST API
13. 13 Kintone REST API Overview API List (Usage) ü App Records • GET • POST • PUT • DELETE ü App Settings • GET • POST • PUT ü Comments ü Spaces https://kintone.dev/en/docs/kintone/rest-api/
14. 14 General Parts of REST API Call üURL üMethod • GET • POST • PUT • DELETE üHeaders • Content-Type ex.) application/json, application/xml • Authorization Information üBody • Text data ex.) JSON format, URL encoded form format • Binary data (Blob) API Server REST Client Request Response
15. 15 Kintone REST API Overview Communication Protocol Data Format Character Encoding • HTTPS • JSON • UTF-8 Authentication • Password authentication • API token authentication • Session authentication https://kintone.dev/en/docs/kintone/rest-api/overview/kintone-rest-api-overview/ Request URI https://your_subdomain.kintone.com/k/v1/your_APIpath.json https://your_subdomain.kintone.com/k/guest/your_spaceID/v1/your_APIpath.json • General • Apps in guest spaces Request Headers • Host: your_subdomain.kintone.com:443 • Content-Type: application/json • (Authentication) Replace kintone.com with cybozu.com if your domain is ***.cybozu.com.
16. 16 Authentication üPassword authentication • X-Cybozu-Authorization: a2ludG9uZTpkZXZlbG9wZXI= üAPI token authentication • X-Cybozu-API-Token: 9wOomr3kpP9d1JS34Uyz72xqQ1pLI4PkcziRFTuZ üSession authentication (REST API Access from JavaScript) • Session authentication is a method of authentication where a session ID is assigned to a user by the web server, and saved as a cookie • This cookie is used to identify and authenticate the user X-Cybozu-Authorization is placed in the request header with a BASE64 encoded login name and password. BASE64 encode format is following: log_in_name:password. For example, for a login name of "kintone" and a password of "developer", BASE64 encode "kintone:developer" https://kintone.dev/en/docs/kintone/rest-api/overview/kintone-rest-api-overview/
17. 17 Request Method for Kintone REST API
18. 18 REST API Request Method There are several options for requesting REST APIs. • curl • Kintone REST API Request (kintone.api) • XMLHttpRequest (XHR) • Fetch API • REST Client (Visual Studio Code Extension) • Advanced REST Client (Google Chrome Extension) • Postman
19. 19 REST API Request Method • curl is a command line tool and library for transferring data with URLs. curl curl -X GET 'https://your_subdomain.kintone.com/k/v1/record.json?app=your_app_id& id=your_record_id' ¥ -H 'X-Cybozu-API-Token: your_api_token' Here are the sample codes to get a record with each request method.
20. 20 REST API Request Method • Kintone REST API Request is the Kintone original API to run Kintone REST APIs from your JavaScript code. Kintone REST API Request (kintone.api) kintone.api(kintone.api.url('/k/v1/record', true), 'GET', { app: kintone.app.getId(), id: your_record_id }, function(resp) { // success console.log(resp) }, function(error) { // error console.log(error); });
21. 21 REST API Request Method • XMLHttpRequest is the API to communicate with servers. It allows you to retrieve data without having to refresh entire page. XMLHttpRequest (XHR) var appId = kintone.app.getId(); var params = '?app=' + appId + '&id=your_record_id'; var url = kintone.api.url('/k/v1/record', true) + params; var xhr = new XMLHttpRequest(); xhr.open('GET', url); xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest'); xhr.onload = function() { if (xhr.status === 200) { // success console.log(JSON.parse(xhr.responseText)); } else { // error console.log(JSON.parse(xhr.responseText)); } }; xhr.send(); Note that it causes negative effects to the user experience. • synchronous requests block the executions of codes, causing the screen to be unresponsive until the request is finished • synchronous XMLHttpRequest is deprecated in major browsers, displaying warnings in the console
22. 22 REST API Request Method • Fetch API is the API to communicate with servers. • It is similar to XMLHttpRequest, but more simple and modern way. Fetch API Note that you cannot use on the Internet Explorer browser for now. var appId = kintone.app.getId(); var params = '?app=' + appId + '&id=your_record_id'; var url = kintone.api.url('/k/v1/record', true) + params; var headers = { 'X-Requested-With': 'XMLHttpRequest' }; fetch(url, { headers: headers }).then(function(resp) { return resp.json(); }).then(function(resp) { console.log(resp); }).catch(function(error) { console.log(error); });
23. 23 REST API Request Method • REST Client is the Visual Studio Code Extension that can send HTTP request and view the response in Visual Studio Code directly. REST Client (Visual Studio Code Extension) We will use this in this material!
24. 24 REST API Request Method • Advanced REST Client is the Google Chrome Extension that can send HTTP request within the browser. Advanced REST Client (Google Chrome Extension)
25. 25 REST API Request Method • Postman is a collaboration platform for API development. • You can send HTTP request using its app. Postman
26. 26 Request Example of Kintone REST API
27. 27 Preparation - Add Demo Records • Add demo records to Company List app. Company List Add 2 records. Company Name: Kintone Company Name: Cybozu
28. 28 Request Example by REST Client (Visual Studio Code Extension) https://marketplace.visualstudio.com/items?itemName=humao.rest-client Install here if you haven’t installed yet
29. 29 Preparation for Using REST Client GitHub link • Open “Example for Records.http” with Visual Studio Code • Access the file from the GitHub link right above
30. 30 Preparation for Using REST Client Replace with your own parameters • Sub-domain • Replace kintone.com with cybozu.com if your domain is ***.cybozu.com. • API Token • Generating API Tokens > https://get.kintone.help/k/en/user/app_settings/api_t oken.html • Sales Deals App ID • User Code (log-in name) • You can get your own user code by requesting on Google Chrome DevTool as below. kintone.getLoginUser(); The easiest way to check the app ID of Sales Deals app is to see the URL when you open Sales Deals app list view. And you can also use App Management page.
31. 31 Request Example by REST Client (Visual Studio Code Extension) Method URL Request Headers Request Body Response Headers Response Body
32. 32 Request Example by REST Client - POST/records Method, URL, Headers, Body You don’t have to include “type” when you request POST/PUT method
33. 33 Request Example by REST Client - POST/records Response
34. 34 Request Example by REST Client - POST/records { "app": 6, "records": [ { "Company_Name_Search": { "value": "Kintone" }, "Deal_Name": { "value": "Kintone app creation" }, "Rep": { "value": [{"code": "yamaroo"}] } }, { "Company_Name_Search": { "value": "Cybozu" }, "Deal_Name": { "value": "Kintone JavaScript customization" }, "Rep": { "value": [{"code": "sadaharu"}] } } ] } Request body Record detail views
35. Request Example by REST Client - GET/records Method, URL, Headers 35 The request without Request Body don’t need Content-Type header
36. Request Example by REST Client - GET/records Response 36
37. Request Example by REST Client - GET/records Response 37 Field Object
38. Request Example by REST Client - GET/records Response The value format of multi-select type field becomes an array • Field Type > https://kintone.dev/en/docs/kintone/overview/field-types/ 38 Field Object Field code Field type Field value
39. 39 Request Example by REST Client - Other GitHub link • Try other request methods in the program file. Access the GitHub link right above. • PUT/records • DELETE/records • POST/file • PUT/record for updating file
40. 40 Request Example by Advanced REST Client - GET/records The request without Request Body don’t need Content-Type header Method, URL, Headers (Google Chrome Extension) Replace kintone.com with cybozu.com if your domain is ***.cybozu.com. Appendix
41. 41 Request Example by Advanced REST Client - GET/records Field Object "Signed_Contract_Value": { "type": "Number", "value": "100000" } Field code Field type Field value The value format of multi-select type field becomes an array • Field Type > https://kintone.dev/en/docs/kintone/overview/field-types/ Response Appendix
42. 42 Request Example by Advanced REST Client - POST/records Method, URL, Headers Replace kintone.com with cybozu.com if your domain is ***.cybozu.com. Appendix
43. 43 Request Example by Advanced REST Client - POST/records Body Appendix You don’t have to include “type” when you request POST/PUT method
44. 44 Request Example by Advanced REST Client - POST/records Response Appendix
45. 45 Hands-on
46. 46 Preparation – Field Codes of Company List App Name Field Code Type City Address City_Address Text Company LinkedIn Company_LinkedIn Link Company Name Company_Name Text Company Size Company_Size Drop-down Company Type Company_Type Drop-down Company Website Company_Website Link Contact Name Contact_Name Text Department Department Text E mail E_mail Link Industry Industry Drop-down Job Title Job_Title Drop-down LinkedIn LinkedIn Link Related Sales Deals Records Related_Sales_Deals_Records Related records State or Country State_or_Country Text Street Address Street_Address Text Telephone Number Telephone_Number Link Zip Code Zip_Code Text
47. Name Additional Attribute #1 Company Name Prohibit duplicate values 47 Preparation – Add Field Attribute to Company List App #1 Check this additional attribute has already been set in the field setting
48. 48 Create App from API
49. The App to Build 49 Company List Sales Deals Lookup/Action Related Records Self Related Records Contact Log Lookup Self Related Records Create from API Completed
50. 50 Create Contact Log App from API 1. Add preview app - POST/preview/app 2. Update general settings - PUT/preview/app/settings 3. Add form fields - POST/preview/app/form/fields 4. Update form layout - PUT/preview/app/form/layout 5. Update views - PUT/preview/app/views 6. Deploy app settings - POST/preview/app/deploy
51. 51 Preparation for Using REST Client • Open “Hands-on.http”, then copy and paste one section by one with Visual Studio Code • Access the file from the GitHub link right above • Base 64 encoded id:password string Easy method to get base64 encoded string btoa that is a JavaScript method can create a base 64 encoded string. Kintone ID: kintone Password: developer btoa a2ludG9uZTpkZXZlbG9wZXI= To open the console panel in Google Chrome Mac: Command + Option + J Win: Ctrl + Shift + J https://developers.google.com/web/tools/chrome-devtools Base 64 encoding GitHub link
52. 52 1. Add Preview App - POST/preview/app https://kintone.dev/en/docs/kintone/rest-api/apps/add-preview-app/ 1. Replace with your own parameters • Sub-domain • Replace kintone.com with cybozu.com if your domain is ***.cybozu.com. • Base 64 encoded id:password • Company List App ID Request The easiest way to check the app ID of Company List app is to see the URL when you open Company List app list view. And you can also use App Management page.
53. 53 1. Add Preview App - POST/preview/app https://kintone.dev/en/docs/kintone/rest-api/apps/add-preview-app/ 2. Click Send Request Response Request 3. Substitute app ID to @contactLogAppId
54. 54 1. Add Preview App - POST/preview/app 4. Click gear icon 5. Click Kintone Administration 6. Click App Management
55. 55 1. Add Preview App - POST/preview/app 7. You can see an app you created 8. Click gear icon 9. You can see a preview app in the setting view (Don’t click Activate App here. You continue setting up through API)
56. 56 2. Update General Settings - PUT/preview/app/settings https://kintone.dev/en/docs/kintone/rest-api/apps/update-general-settings/ Response Request Setting View 10. Click Send Request 11. You can see revision increased 12. Refresh browser (Icon was changed)
57. 57 3. Add Form Fields - POST/preview/app/form/fields https://kintone.dev/en/docs/kintone/rest-api/apps/add-form-fields/ Response Request Setting View 13. Click Send Request 14. You can see revision increased 15. Refresh browser (Fields were added)
58. 58 4. Update form layout - PUT/preview/app/form/layout https://kintone.dev/en/docs/kintone/rest-api/apps/update-form-layout/ Response Request Setting View 16. Click Send Request 17. You can see revision increased 18. Refresh browser (Layout was updated)
59. 59 5. Update Views - PUT/preview/app/views 19. Click Views 20. You can see no views
60. 60 5. Update Views - PUT/preview/app/views https://kintone.dev/en/docs/kintone/rest-api/apps/update-views/ Response Request Setting View 21. Click Send Request 22. You can see revision increased 23. Refresh browser (View was added)
61. 61 6. Deploy App Settings - POST/preview/app/deploy https://kintone.dev/en/docs/kintone/rest-api/apps/deploy-app-settings/ Response Request Setting View 24. Click Send Request 25. Refresh browser (App was activated) 26. Click Contact Log
62. 62 Contact Log App was Built List View Record Edit View
63. 63 Add Record from API
64. 64 Add a Record from API Upload File Add Record 1. Click Send Request 2. Enter fileKey here 3. Click Send Request https://kintone.dev/en/docs/kintone/rest-api/files/upload-file/ https://kintone.dev/en/docs/kintone/rest-api/records/add-record/ • The fileKey will be expired after 3 days if the Add Record or Update Record API is not used. • The fileKey can only be used once.
65. 65 Thank you for joining this session!!
66. 66 References • Kintone Developer Program – API Docs • https://kintone.dev/en/docs/ • Kintone Help Site • https://get.kintone.help/k/en/