A Notion API (currently beta) client library for Kotlin, Java and more.
This library is written in Kotlin Multiplatform so in theory it can be used from the JVM, Android, iOS, Linux, MacOS, Windows, Javascript and more. In practice it has been tested and has samples for the JVM (Kotlin and Java), and MacOS (Kotlin).
Several flavors of the client are available to match your needs:
- Coroutines (
suspend) based: the default client for Kotlin projects - Blocking: useful for Java projects, or if you have your own async mechanism
Futurebased (JVM only): useful for Java projects
The artifact is hosted on the Maven Central repository.
repositories {
/* ... */
mavenCentral()
}dependencies {
/* ... */
implementation 'org.jraf:klibnotion:1.11.0'
}The easiest way to see how to use it is to look at the samples:
You can also explore the docs.
You will find your Internal Integration Token by following the instructions here.
val notionClient = NotionClient.newInstance(
ClientConfiguration(
Authentication(TOKEN)
)
)To get other flavors of the client:
- Blocking:
BlockingNotionClient blockingClient = BlockingNotionClientUtils.asBlockingNotionClient(notionClient) - Future:
FutureNotionClient futureClient = FutureNotionClientUtils.asFutureNotionClient(notionClient)
The client gives access to several API "areas":
Each area exposes related APIs, for
instance: notionClient.pages.getPage
.
The APIs that are paginated all follow the same principle:
- take
a
Paginationobject as a parameter, which defines the page to retrieve - return
a
ResultPage<T>with the result list but also a reference to the nextPaginationobjects (handy when retrieving several pages).
A small DSL is available on the page creation API, here's an example usage:
heading1("First section")
paragraph("Hello, World!")
heading1("Second section")
paragraph("This paragraph is bold", annotations = Annotations.BOLD) {
paragraph("Sub paragraph 1")
paragraph("Sub paragraph 2") {
paragraph("Sub sub paragraph") {
}
}
}
heading2("But then again")
heading3("Actually")
paragraph("That's the case")
heading3("But really")
paragraph(RichTextList().text("This ")
.text("word", Annotations(color = Color.RED))
.text(" is red"))
bullet("There's this,")
bullet("there's that,")
bullet("then there's...") {
paragraph("Will this work?")
}
bullet("indentation?") {
bullet("indentation? 2") {
bullet("indentation? 3")
}
}
number("First")
number("Second") {
number("Second second")
}
number("Third")
toDo("This one is checked", true)
toDo("This one is not checked", false)
toggle("This is a toggle!") {
paragraph("This first paragraph is inside the toggle")
paragraph("This second paragraph is inside the toggle")
heading3("This too!")
} |
|
- Use
oAuth.getUserPromptUrito get a URI that will prompt users to agree to add your integration to their workspace - After agreeing and upon success, they will be redirected to a specific URI containing a code.
Use
oAuth.extractCodeAndStateFromRedirectUrito extract the code from this URI. - Exchange the code for an access token
using
oAuth.getAccessToken - Save this token. You can now use it by setting
the
accessTokenproperty of theAuthenticationobject you used when building yourNotionClient.
See the sample for a working example.
To log HTTP requests/response, pass
a HttpConfiguration
to NotionClient.newInstance()
.
Several levels
are available: NONE, INFO, HEADERS, BODY and ALL
A proxy can be configured by passing
a HttpConfiguration
to NotionClient.newInstance()
.
- This library uses the
2021-08-16version of the Notion API. - This library is in active development.
- The Notion API is still evolving actively and therefore there are some changes that have not been implemented by this library yet.
- Pull requests are welcome!
- If you want to contribute, it is recommended you first try an issue with the "good first issue" label.
In theory Kotlin Multiplatform projects can also target Javascript but as of today the author couldn't understand how to make that work. Please contact the author if you want to help :)
Note: this project is not officially related to or endorsed by Notion.
Copyright (C) 2021-present Benoit 'BoD' Lubek (BoD@JRAF.org)
and contributors (https://github.com/BoD/klibnotion/graphs/contributors)
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.