Introduction

When you're participating in a hackathon, efficiency and quick iteration are key to success. One tool that can help you manage data efficiently is Kintone, a powerful no-code/low-code platform that allows you to create web-based databases with ease.

In this guide, we'll walk you through how to create a simple Kintone App to store scores for games, and demonstrate how to interact with the Kintone API using some local Python code.

Get your Kintone Environment

First we need to get our hands on a Kintone Environment!
Developers are entitled to use the Kintone Developer License - an environment that can be used for free for 1 year ❤

Get your Kintone Developer License by filling out the form.
https://kintone.dev/en/developer-license-registration-form/

Create your Kintone Database

Web Databases in Kintone are called "Apps".
Creating these Apps are easy in Kintone - you can drag-and-drop the fields that you need, without needing to code.

Follow the instructions on the following link to create a new App.
https://get.kintone.help/k/en/id/040133.html

These are the fields we will include in the Kintone App for this article:

The field layout should look like the following:

After that, proceed to the Settings tab, and generate an API Token that will be used for the authentication. Set the permissions for View records and Add records.

https://get.kintone.help/k/en/id/040471.html

Once this is done, save the settings, and click on the blue "Activate App" button.

Manually Input Some Data

Since there is no data yet inside the App, manually add in some data so that we have something to work with.
https://get.kintone.help/k/en/id/040715.html

Now we're ready to interact with the Web Database with some Python code!

Sample Python Code to Interact with Kintone

Now that your app is set up, let's look at how you can interact with the Kintone API using Python. We'll cover how to add a record, retrieve all records, and query records based on difficulty.

Get a Python environment ready on your local machine. Since we will be using the requests library to make our API calls, install the library with the following command:

pip install requests

1. Adding a Record to the Kintone App

Below is a sample Python script that adds a new record to the Kintone App.

import requests
import json

def add_record():
    API_endpoint = "https://{YOUR_SUBDOMAIN}.cybozu.com/k/v1/record.json"
    app_id = "{APP_ID}"

    kintone_headers = {
        "X-Cybozu-API-Token": "{API_TOKEN}",
        "Content-Type": "application/json"
    }

    bodydata = {
        "app": app_id,
        "record": {
            "player": {
                "value": "John Doe"
            },
            "score": {
                "value": "1500"
            },
            "diff": {
                "value": "Medium"
            }
        }
    }

    try:
        response = requests.post(API_endpoint, headers=kintone_headers, data=json.dumps(bodydata))
        jsondata = response.json()
        print(jsondata)

    except requests.exceptions.RequestException as error:
        print(error)

add_record()

The App ID is a number that can be found in the URL of the Kintone App.
If the request is successful, a JSON is responded that includes the ID of the newly added record.

{'id': '7', 'revision': '1'}

If the request is successful, but the record data is empty, it may be because the keys inside the body data were incorrect. Make sure that the keys for the fields are stated as their field codes, and not their field names.

2. Retrieving All Records from the Kintone App

The following Python script will retrieve all records stored in your Kintone App.

import requests

def get_all_records():
    API_endpoint = "https://{YOUR_SUBDOMAIN}.cybozu.com/k/v1/records.json"
    app_id = "{APP_ID}"
    API_endpoint = API_endpoint   "?app="   app_id

    kintone_headers = {
        "X-Cybozu-API-Token": "{API_TOKEN}",
    }

    try:
        response = requests.get(API_endpoint, headers=kintone_headers)
        jsondata = response.json()
        print(jsondata)

    except requests.exceptions.RequestException as error:
        print(error)

get_all_records()

If the request is successful, the response will include a JSON of all the records in the App.

"records": [
    {
      "difficulty": {
        "type": "DROP_DOWN",
        "value": null
      },
      "score": {
        "type": "NUMBER",
        "value": "1500"
      },
      "Record Number": {
        "type": "RECORD_NUMBER",
        "value": "7"
      },
      "Updated By": {
        "type": "MODIFIER",
        "value": {
          "code": "Administrator",
          "name": "Administrator"
        }
      },
      "Created By": {
        "type": "CREATOR",
        "value": {
          "code": "Administrator",
          "name": "Administrator"
        }
      },
      "playername": {
        "type": "SINGLE_LINE_TEXT",
        "value": ""
      },
      "$revision": {
        "type": "__REVISION__",
        "value": "1"
      },
      "Updated Datetime": {
        "type": "UPDATED_TIME",
        "value": "2024-10-06T02:33:00Z"
      },
      "Created Datetime": {
        "type": "CREATED_TIME",
        "value": "2024-10-06T02:33:00Z"
      },
      "$id": {
        "type": "__ID__",
        "value": "7"
      }
    },
    {
      "difficulty": {
        "type": "DROP_DOWN",
        "value": "Hard"
      },
      "score": {
        "type": "NUMBER",
        "value": "34000"
      },
      "Record Number": {
        "type": "RECORD_NUMBER",
        "value": "6"
      },
      "Updated By": {
        "type": "MODIFIER",
        "value": {
          "code": "will",
          "name": "will-yama"
        }
      },
      "Created By": {
        "type": "CREATOR",
        "value": {
          "code": "will",
          "name": "will-yama"
        }
      },
      "playername": {
        "type": "SINGLE_LINE_TEXT",
        "value": "Kelly Smiles"
      },
      "$revision": {
        "type": "__REVISION__",
        "value": "1"
      },
      "Updated Datetime": {
        "type": "UPDATED_TIME",
        "value": "2024-10-06T01:41:00Z"
      },
      "Created Datetime": {
        "type": "CREATED_TIME",
        "value": "2024-10-06T01:41:00Z"
      },
      "$id": {
        "type": "__ID__",
        "value": "6"
      }
    },...

We have cut off the above JSON response half way through for this article, as it is quite long.

3. Retrieving Records with Query Filtering

In some cases, you may want to retrieve records based on specific conditions, such as fetching records where the difficulty is set to "Hard". Add a query to the GET request to achieve this.

import requests

def get_all_records():
    API_endpoint = "https://{YOUR_SUBDOMAIN}.cybozu.com/k/v1/records.json"
    app_id = "{APP_ID}"
    query = "difficulty in (\"Hard\")"
    API_endpoint = API_endpoint   "?app="   app_id   "&query="   query

    kintone_headers = {
        "X-Cybozu-API-Token": "{API_TOKEN}",
    }

    try:
        response = requests.get(API_endpoint, headers=kintone_headers)
        jsondata = response.json()
        print(jsondata)

    except requests.exceptions.RequestException as error:
        print(error)

get_all_records()

If the request is successful, the response will include a JSON of the filtered records.

"records": [

    {

    "difficulty": {

        "type": "DROP_DOWN",

        "value": "Hard"

    },

    "score": {

        "type": "NUMBER",

        "value": "34000"

    },

    "Record Number": {

        "type": "RECORD_NUMBER",

        "value": "6"

    },

    "Updated By": {

        "type": "MODIFIER",

        "value": {

        "code": "will",

        "name": "William Sayama"

        }

    },

    "Created By": {

        "type": "CREATOR",

        "value": {

        "code": "will",

        "name": "William Sayama"

        }

    },

    "playername": {

        "type": "SINGLE_LINE_TEXT",

        "value": "Kelly Smiles"

    },

    "$revision": {

        "type": "REVISION",

        "value": "1"

    },

    "Updated Datetime": {

        "type": "UPDATED_TIME",

        "value": "2024-10-06T01:41:00Z"

    },

    "Created Datetime": {

        "type": "CREATED_TIME",

        "value": "2024-10-06T01:41:00Z"

    },

    "$id": {

        "type": "ID",

        "value": "6"

    }

    },

    {

    "difficulty": {

        "type": "DROP_DOWN",

        "value": "Hard"

    },

    "score": {

        "type": "NUMBER",

        "value": "45000"

    },

    "Record Number": {

        "type": "RECORD_NUMBER",

        "value": "5"

    },

    "Updated By": {

        "type": "MODIFIER",

        "value": {

        "code": "will",

        "name": "William Sayama"

        }

    },

    "Created By": {

        "type": "CREATOR",

        "value": {

        "code": "will",

        "name": "William Sayama"

        }

    },

    "playername": {

        "type": "SINGLE_LINE_TEXT",

        "value": "Jay Pudding"

    },

    "$revision": {

        "type": "REVISION",

        "value": "1"

    },

    "Updated Datetime": {

        "type": "UPDATED_TIME",

        "value": "2024-10-06T01:38:00Z"

    },

    "Created Datetime": {

        "type": "CREATED_TIME",

        "value": "2024-10-06T01:38:00Z"

    },

    "$id": {

        "type": "ID",

        "value": "5"

    }

    },

    {

    "difficulty": {

        "type": "DROP_DOWN",

        "value": "Hard"

    },

    "score": {

        "type": "NUMBER",

        "value": "34000"

    },

    "Record Number": {

        "type": "RECORD_NUMBER",

        "value": "2"

    },

    "Updated By": {

        "type": "MODIFIER",

        "value": {

        "code": "will",

        "name": "William Sayama"

        }

    },

    "Created By": {

        "type": "CREATOR",

        "value": {

        "code": "will",

        "name": "William Sayama"

        }

    },

    "playername": {

        "type": "SINGLE_LINE_TEXT",

        "value": "Jam Flipping"

    },

    "$revision": {

        "type": "REVISION",

        "value": "2"

    },

    "Updated Datetime": {

        "type": "UPDATED_TIME",

        "value": "2024-10-06T01:38:00Z"

    },

    "Created Datetime": {

        "type": "CREATED_TIME",

        "value": "2024-10-05T01:26:00Z"

    },

    "$id": {

        "type": "ID",

        "value": "2"

    }

    }

],

"totalCount": null

Conclusion

By setting up a Kintone App and interacting with it via API, you can easily manage data for your projects. Whether you're keeping track of player performances or storing other types of data, Kintone’s flexible API makes it easy to integrate into any hackathon project.

This guide has provided examples for adding records, retrieving all records, and querying records with specific conditions, allowing you to customize your data management according to your needs.

Good luck at your hackathon, and happy coding with Kintone!