NotionSwift
Unofficial Notion SDK for iOS & macOS.
This is still work in progress version, the module interface might change.
API Documentation
This library is a client for the official Notion API. For more details and documentation please check Notion Developer Portal
Installation
CocoaPods
pod 'NotionSwift', '0.4.0'
Swift Package Manager
dependencies: [
.package(url: "https://github.com/chojnac/NotionSwift.git", .upToNextMajor(from: "0.4.0"))
]
Usage
Currently, this library supports only the "internal integration" authorization mode. For more information about authorization and instruction how to obtain NOTION_TOKEN please check Notion Offical Documentation.
Important: Integrations are granted access to resources (pages and databases) which users have shared with the integration. Resources that are not shared with the integration are not visible by API endpoints.
Creating a Notion client.
let notion = NotionClient(accessKeyProvider: StringAccessKeyProvider(accessKey: "{NOTION_TOKEN}"))
List all databases
The https://api.notion.com/v1/databases is deprecated. To recommended way to list all databases is to use https://api.notion.com/v1/search endpoint. In theory, search allows filtering results by object type. However, currently, the only filter allowed is object which will filter by type of object (either page or database) To narrow search results, use code snippet belove.
// fetch avaiable databases
notion.search(request: .init(filter: .database)) { result in
let databases = result.map { objects in
objects.results.compactMap({ object -> Database? in
if case .database(let db) = object {
return db
}
return nil
})
}
print(databases)
}
Query a database
In this example we will get all pages in the database. To narrow results use params argument.
let databaseId = Database.Identifier("{DATABASE UUIDv4}")
notion.databaseQuery(databaseId: databaseId) {
print($0)
}
Retrieve a database
let databaseId = Database.Identifier("{DATABASE UUIDv4}")
notion.database(databaseId: databaseId) {
print($0)
}
Create a database
let parentPageId = Page.Identifier("e67db074-973a-4ddb-b397-66d3c75f9ec9")
let request = DatabaseCreateRequest(
parent: .pageId(parentPageId),
icon: .emoji("🤔"),
cover: .external(url: "https://images.unsplash.com/photo-1606787366850-de6330128bfc"),
title: [
.init(string: "Created at: \(Date())")
],
properties: [
"Field 10": .richText
]
)
notion.databaseCreate(request: request) {
print($0)
}
Update a database
let id = Database.Identifier("{DATABASE UUIDv4}")
// update cover, icon & add a new field
let request = DatabaseUpdateRequest(
title: nil,
icon: .emoji("🤔"),
cover: .external(url: "https://images.unsplash.com/photo-1606787366850-de6330128bfc"),
properties: [
"Field 10": .richText
]
)
notion.databaseUpdate(databaseId: id, request: request) {
print($0)
}
Retrieve a page
Retrieve page properties.
let pageId = Block.Identifier("{PAGE UUIDv4}")
notion.page(pageId: pageId) {
print($0)
}
Page content (text for example) is represented as an array of blocks. The example below loads properties and page content.
let pageId = Block.Identifier("{PAGE UUIDv4}")
notion.page(pageId: pageId) { [notion] in
print("---- Properties ----- ")
print($0)
switch $0 {
case .success(let page):
notion.blockChildren(blockId: page.id.toBlockIdentifier) {
print("---- Children ----- ")
print($0)
}
default:
break
}
}
Note: The API returns only the direct children of the page. If there is content nested in the block (nested lists for example) it requires other calls.
Create a page
let parentPageId = Block.Identifier("{PAGE UUIDv4}")
let request = PageCreateRequest(
parent: .page(parentPageId),
properties: [
"title": .init(
type: .title([
.init(string: "Lorem ipsum \(Date())")
])
)
],
children: blocks
)
notion.pageCreate(request: request) {
print($0)
}
Update page properties
let pageId = Block.Identifier("{PAGE UUIDv4}")
// update title property
let request = PageProperiesUpdateRequest(
properties: [
.name("title"): .init(
type: .title([
.init(string: "Updated at: \(Date())")
])
)
]
)
notion.pageUpdateProperties(pageId: pageId, request: request) {
print($0)
}
Retrieve block children
Note: This endpoint returns only the first level of children, so for example, nested list items won't be returned. In that case, you need to make another request with the block id of the parent block.
let pageId = Block.Identifier("{PAGE UUIDv4}")
notion.blockChildren(blockId: pageId) {
print($0)
}
Append block children
let pageId = Block.Identifier("{PAGE UUIDv4}")
// append paragraph with styled text to a page.
let blocks: [WriteBlock] = [
.init(type: .paragraph(.init(text: [
.init(string: "Lorem ipsum dolor sit amet, "),
.init(string: "consectetur", annotations: .bold),
.init(string: " adipiscing elit.")
])))
]
notion.blockAppend(blockId: pageId, children: blocks) {
print($0)
}
Update a block
let blockId = Block.Identifier("{BLOCK UUIDv4}")
let text: [RichText] = [
.init(string: "Current time: "),
.init(string: Date().description, annotations: .bold)
]
let block = UpdateBlock(value: .paragraph(text: text))
notion.blockUpdate(blockId: blockId, value: block) {
print("Updated: ", $0)
}
Block delete
let blockId = Block.Identifier("{BLOCK UUIDv4}")
notion.blockDelete(blockId: block.id) {
print("Delete: ", $0)
}
Retrieve a user
let id = User.Identifier("{USER UUIDv4}")
notion.user(userId: id) {
print($0)
}
List all users
notion.usersList() {
print($0)
}
Search
Search for pages & databases with a title containing text "Lorem"
notion.search(
request: .init(
query: "Lorem"
)
) {
print($0)
}
Search for all databases and ignore pages.
notion.search(
request: .init(
filter: .database
)
) {
print($0)
}
Get all pages & databases
notion.search() {
print($0)
}
Logging and debugging
NotionSwift provide an internal rudimental logging system to track HTTP traffic. To enable it you need to set a build-in or custom logger handler and decide about log level (.info by default). With .track log level you can see all content of a request. This is useful to track mapping issues between library data models and API.
Example logging configuration:
// This code should be in the ApplicationDelegate
NotionSwift.Environment.logHandler = NotionSwift.PrintLogHandler() // uses print command
NotionSwift.Environment.logLevel = .trace // show me everything
License
NotionSwift is available under the MIT license. See the LICENSE file for more info.
45 Nov 29, 2022
19 Dec 20, 2022
112 Dec 19, 2022
1 Jun 30, 2020
2 Jun 20, 2022
10 Dec 24, 2022
16 Jul 29, 2022
2 Feb 5, 2022
0 Jan 21, 2022
146 Nov 24, 2022
5 Oct 29, 2022
35 Oct 26, 2022
0 May 6, 2022
0 Oct 21, 2021
1 Dec 6, 2022
8 Jan 10, 2022
25 Dec 14, 2022
522 Jan 6, 2023
230 Mar 18, 2022