{"id":16697006,"url":"https://github.com/seratch/notion-sdk-jvm","last_synced_at":"2025-04-03T21:14:04.173Z","repository":{"id":38015687,"uuid":"367397489","full_name":"seratch/notion-sdk-jvm","owner":"seratch","description":"A Notion SDK for Any JVM Language","archived":false,"fork":false,"pushed_at":"2024-09-30T18:23:05.000Z","size":624,"stargazers_count":137,"open_issues_count":20,"forks_count":25,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-10-13T17:45:46.013Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://developers.notion.com/","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/seratch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-14T15:02:44.000Z","updated_at":"2024-09-30T21:49:22.000Z","dependencies_parsed_at":"2023-10-16T14:32:37.891Z","dependency_job_id":"dbe70ecc-09c3-4431-9484-d3bb955d0685","html_url":"https://github.com/seratch/notion-sdk-jvm","commit_stats":null,"previous_names":[],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seratch%2Fnotion-sdk-jvm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seratch%2Fnotion-sdk-jvm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seratch%2Fnotion-sdk-jvm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seratch%2Fnotion-sdk-jvm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/seratch","download_url":"https://codeload.github.com/seratch/notion-sdk-jvm/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247078862,"owners_count":20879952,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-12T17:45:44.793Z","updated_at":"2025-04-03T21:14:04.149Z","avatar_url":"https://github.com/seratch.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- markdownlint-disable --\u003e\n\u003cdiv align=\"center\"\u003e\n    \u003ch1\u003eNotion SDK for Any JVM Language\u003c/h1\u003e\n    \u003cp\u003e\n        \u003cb\u003eA simple and easy to use client for the \u003ca href=\"https://developers.notion.com/\"\u003eNotion API\u003c/a\u003e\u003c/b\u003e\n    \u003c/p\u003e\n    \u003cbr/\u003e\n\u003c/div\u003e\n\u003c!-- markdownlint-enable --\u003e\n\n[![Maven Central](https://img.shields.io/maven-central/v/com.github.seratch/notion-sdk-jvm-core.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22com.github.seratch%22%20AND%20a:%22notion-sdk-jvm-core%22)\n[![CI Build](https://github.com/seratch/notion-sdk-jvm/actions/workflows/ci-build.yml/badge.svg)](https://github.com/seratch/notion-sdk-jvm/actions/workflows/ci-build.yml)\n\nHere is a [Notion API](https://developers.notion.com/) SDK for any JVM language users :wave: \n\nThis project aims to provide a Notion API client for any JVM language developers without hurdles. To realize the goal, its code is written in Kotlin with a nice consideration for Java compatibility.\n\nThis SDK works on [Android runtime](https://developer.android.com/) and any distributions based on [OpenJDK](https://openjdk.java.net/). With regard to programming languages, this project provides out-of-the-box supports for Java (of course!) and [Kotlin](https://kotlinlang.org/). We don't have nice wrappers for some other JVM languages such as [Scala](https://www.scala-lang.org/), [Groovy](https://groovy-lang.org/), and [Clojure](https://clojure.org/), but your code using this library should work in the languages too.\n\n### Getting Started\n\nYou can start using this library just by adding `notion-sdk-jvm-core` dependency to your project.\n\nFor Gradle users:\n\n```gradle\next.notionSdkVersion = \"1.11.1\"\ndependencies {\n  // This dependency is at least required\n  implementation(\"com.github.seratch:notion-sdk-jvm-core:${notionSdkVersion}\")\n}\n```\n\nFor Maven users:\n\n```xml\n\u003cproperties\u003e\n  \u003cnotion-sdk.version\u003e1.11.1\u003c/notion-sdk.version\u003e\n\u003c/properties\u003e\n\n\u003cdependencies\u003e\n  \u003cdependency\u003e\n    \u003cgroupId\u003ecom.github.seratch\u003c/groupId\u003e\n    \u003cartifactId\u003enotion-sdk-jvm-core\u003c/artifactId\u003e\n    \u003cversion\u003e${notion-sdk.version}\u003c/version\u003e\n  \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\nAs this library is in Kotlin, using in the same language is the smoothest :) Let's start with the following code, which manipulates Notion pages :wave:\n\n```kotlin\nimport notion.api.v1.NotionClient\nimport notion.api.v1.model.common.ObjectType\nimport notion.api.v1.model.pages.PageParent\nimport notion.api.v1.request.search.SearchRequest\nimport notion.api.v1.model.pages.PageProperty\n\nfun main() {\n  NotionClient(token = System.getenv(\"NOTION_TOKEN\")).use { client -\u003e\n    // Find the \"Test Database\" from the list\n    val database = client\n      .search(\n        query = \"Test Database\",\n        filter = SearchRequest.SearchFilter(\"database\", property = \"object\")\n      )\n      .results\n      .find { it.asDatabase().properties.containsKey(\"Severity\") }\n      ?.asDatabase()\n      ?: error(\"Create a database named 'Test Database' and invite this app's user!\")\n    // Alternatively if you know the UUID of the Database, use `val database = client.retrieveDatabase(\"...\")`.\n\n    // All the options for \"Severity\" property (select type)\n    val severityOptions = database.properties[\"Severity\"]!!.select!!.options!!\n    // All the options for \"Tags\" property (multi_select type)\n    val tagOptions = database.properties[\"Tags\"]!!.multiSelect!!.options!!\n    // A user object for \"Assignee\" property (people type)\n    val assignee = client.listUsers().results.first() // Just picking a random user.\n\n    // Create a new page in the database\n    val newPage = client.createPage(\n      // Use the \"Test Database\" as this page's parent\n      parent = PageParent.database(database.id),\n      // Set values to the page's properties\n      // (Values of referenced options, people, and relations must be pre-defined before this API call!)\n      properties = mapOf(\n        \"Title\" to PageProperty(title = \"Fix a bug\".asRichText()),\n        \"Severity\" to PageProperty(select = severityOptions.single { it.name == \"High\" }),\n        \"Tags\" to PageProperty(multiSelect = listOf(\"Tag1\", \"Tag2\").map { tag -\u003e tagOptions.single { it.name == tag } }),\n        \"Due\" to PageProperty(date = PageProperty.Date(start = \"2021-05-13\", end = \"2021-12-31\")),\n        \"Velocity Points\" to PageProperty(number = 3),\n        \"Assignee\" to PageProperty(people = listOf(assignee)),\n        \"Done\" to PageProperty(checkbox = true),\n        \"Link\" to PageProperty(url = \"https://www.example.com\"),\n        \"Contact\" to PageProperty(email = \"foo@example.com\"),\n      )\n    )\n    \n    // Properties can be addressed by their ID too.\n    val severityId = newPage.properties[\"Severity\"]!!.id\n\n    // Update properties in the page\n    val updatedPage = client.updatePage(\n        pageId = newPage.id,\n        // Update only \"Severity\" property\n        properties = mapOf(\n          severityId to PageProperty(select = severityOptions.single { it.name == \"Medium\" }),\n        )\n      )\n\n    // Fetch the latest data of the page\n    val retrievedPage = client.retrievePage(newPage.id)\n  }\n}\n\nprivate fun String.asRichText(): List\u003cPageProperty.RichText\u003e =\n  listOf(PageProperty.RichText(text = PageProperty.RichText.Text(content = this)))\n```\n\n#### Using in Java\n\nEven when you use this SDK in Java and other languages, all the classes/methods should be accessible. If you find issues, please let us know the issue in [this project's issue tracker](https://github.com/seratch/notion-sdk-jvm/issues).\n\n```java\npackage integration_tests;\n\nimport notion.api.v1.NotionClient;\nimport notion.api.v1.model.search.SearchResults;\nimport org.junit.Assert;\n\npublic class Readme {\n  public static void main(String[] args) {\n    NotionClient client = new NotionClient(System.getenv(\"NOTION_TOKEN\"));\n    try {\n      SearchResults results = client.search(\"Test Database\");\n      Assert.assertNotNull(results);\n    } finally {\n      client.close();\n    }\n  }\n}\n```\n\n### OAuth Support\n\nThe Notion app installation via the OAuth flow is also supported. To learn how to implement it, please check [an example app built with Ktor web framework](https://github.com/seratch/notion-sdk-jvm/blob/main/core/src/test/kotlin/OAuthAppExample.kt) in the core library project.\n\n### Plugins\n\nBy default, the `NotionClient` utilizes only JDK's `java.net.HttpURLConnection` and [Gson](https://github.com/google/gson) library for JSON serialization.\n\nFor HTTP communications and logging, you can easily switch to other implementations.\n\n#### Pluggable HTTP Client\n\nAs some may know, `java.net.HttpURLConnection` does not support PATCH request method :cry:. Thus, the default `httpClient` has to make an \"illegal reflective access\" to overcome the limitation for perfoming PATCH method requests (see [this class](https://github.com/seratch/notion-sdk-jvm/blob/main/core/src/main/kotlin/notion/api/v1/http/HttpUrlConnPatchMethodWorkaround.kt) for details). \n\n**The PATCH method workaround does not work with OpenJDK 19 or newer**. Thus, if you use PATCH method API calls such as [`PATCH https://api.notion.com/v1/pages/{page_id}`](https://developers.notion.com/reference/patch-page), we recommend other `httpClient` implementations listed below. If you don't use PATCH method APIs at all and don't want to add any extra dependencies, the default `httpClient` works fine for you.\n\n* [`java.net.HttpClient`](https://docs.oracle.com/en/java/javase/11/docs/api/java.net.http/java/net/http/HttpClient.html) in JDK 11+\n* `okhttp3.OkHttpClient` in [OkHttp](https://square.github.io/okhttp/) 5.x (still alpha)\n* `okhttp3.OkHttpClient` in [OkHttp](https://square.github.io/okhttp/) 4.x\n* `okhttp3.OkHttpClient` in [OkHttp](https://square.github.io/okhttp/) 3.x\n\n```gradle\n// Add this if you use java.net.http.HttpClient in JDK 11+\n// Please note that this module does not work on Android runtime\nimplementation(\"com.github.seratch:notion-sdk-jvm-httpclient:${notionSdkVersion}\")\n\n// Add this if you use OkHttp 5.x (still alpha)\n// If you have other dependencies relying on okhttp 5.x (e.g., Retrofit)\nimplementation(\"com.github.seratch:notion-sdk-jvm-okhttp5:${notionSdkVersion}\")\n\n// Add this if you use OkHttp 4.x\n// Although the package name is `okhttp3`, the latest version is 4.x\nimplementation(\"com.github.seratch:notion-sdk-jvm-okhttp4:${notionSdkVersion}\")\n\n// Add this if you use OkHttp 3.x\n// If you have other dependencies relying on okhttp 3.x (e.g., Retrofit)\nimplementation(\"com.github.seratch:notion-sdk-jvm-okhttp3:${notionSdkVersion}\")\n```\n\nYou can switch the `httpClient` in either of the following ways:\n\n```kotlin\nimport notion.api.v1.NotionClient\nimport notion.api.v1.http.JavaNetHttpClient\n\nval client = NotionClient(\n    token = System.getenv(\"NOTION_TOKEN\"),\n    httpClient = JavaNetHttpClient(),\n)\n```\n\nor\n\n```kotlin\nimport notion.api.v1.NotionClient\nimport notion.api.v1.http.OkHttp3Client\n\nval client = NotionClient(token = System.getenv(\"NOTION_TOKEN\"))\nclient.httpClient = OkHttp3Client()\n```\n\n#### Pluggable Logging\n\nYou can change the `logger` property of a `NotionClient` instances Currently, this library supports its own stdout logger (default), `java.util.logging`, and slf4j-api based ones. Here are the steps to switch to an slf4j-api logger. Add the following optional module along with your favorite implementation (e.g., logback-classic, slf4j-simple).\n\n```gradle\nimplementation(\"com.github.seratch:notion-sdk-jvm-slf4j:${notionSdkVersion}\") // slf4j-api 1.7\nimplementation(\"org.slf4j:slf4j-simple:1.7.36\")\n```\n\nNow you can switch to your slf4j logger. As with the `httpClient` example, you can use the setter method too.\n\n```kotlin\nimport notion.api.v1.NotionClient\nimport notion.api.v1.http.JavaNetHttpClient\nimport notion.api.v1.logging.Slf4jLogger\n\n// for slf4j-simple\nSystem.setProperty(\"org.slf4j.simpleLogger.defaultLogLevel\", \"debug\")\n\nval client = NotionClient(\n    token = System.getenv(\"NOTION_TOKEN\"),\n    httpClient = JavaNetHttpClient(),\n    logger = Slf4jLogger(),\n)\n```\n\nIf you desire to use slf4j-api v2 instead, you can use the module for the major version as below:\n\n```gradle\nimplementation(\"com.github.seratch:notion-sdk-jvm-slf4j2:${notionSdkVersion}\") // slf4j-api 2.0\nimplementation(\"org.slf4j:slf4j-simple:2.0.0\")\n```\n\n#### Why isn't JSON serialization pluggable?\n\nWe don't support other JSON libraries yet. There are two reasons:\n\n##### Necessity of polymorphic serializers for list objects\n\nIn the early development stage of this SDK, we started with [kotlinx.serialization](https://github.com/Kotlin/kotlinx.serialization). It worked well except for the Search API responses. The `results` returned by the API requires polymorphic serializers for `properties: List\u003cDatabaseProperty | PageProperty\u003e` (this is a pseudo-code illustrating the property is a list of union type). We could not find a way to handle the pattern with the library at that time.\n\n##### Easily enabling camelCased property names\n\nWe know a few novel Kotlin libraries do not support the conversions between snake_cased keys and camelCased keys. Although we do respect the opinion and see the benefit, we still prefer consistent field naming in the Java world. This is another major reason why we did not go with either of kotlinx.serialization and Moshi.\n\n### Supported Java Runtimes\n\n* OpenJDK 8 or higher\n* All Android runtime versions supported by Kotlin 1.x\n\nAs `notion-sdk-jvm-httpclient` utilizes `java.net.http.HttpClient`, the module works with JDK 11 and higher versions.\n\n### License\n\nThe MIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseratch%2Fnotion-sdk-jvm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseratch%2Fnotion-sdk-jvm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseratch%2Fnotion-sdk-jvm/lists"}