notion-ruby-client 0.0.5 → 0.1.0.pre.beta1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.github/workflows/ci.yml +1 -0
- data/.gitignore +7 -0
- data/.rubocop.yml +9 -0
- data/CHANGELOG.md +32 -0
- data/CODE_OF_CONDUCT.md +128 -0
- data/Gemfile.lock +37 -11
- data/README.md +318 -47
- data/bin/console +31 -0
- data/lib/notion/api/endpoints/blocks.rb +35 -7
- data/lib/notion/api/endpoints/databases.rb +67 -17
- data/lib/notion/api/endpoints/pages.rb +7 -7
- data/lib/notion/api/endpoints/search.rb +41 -0
- data/lib/notion/api/endpoints/users.rb +6 -3
- data/lib/notion/api/endpoints.rb +3 -1
- data/lib/notion/api/errors/too_many_requests.rb +15 -0
- data/lib/notion/api/errors.rb +0 -2
- data/lib/notion/config.rb +2 -0
- data/lib/notion/faraday/request.rb +1 -0
- data/lib/notion/pagination/cursor.rb +5 -2
- data/lib/notion/version.rb +3 -2
- data/lib/notion-ruby-client.rb +2 -0
- data/notion-ruby-client.gemspec +3 -1
- data/spec/fixtures/notion/block.yml +146 -0
- data/spec/fixtures/notion/block_append_children.yml +76 -62
- data/spec/fixtures/notion/block_children.yml +80 -65
- data/spec/fixtures/notion/create_database.yml +149 -0
- data/spec/fixtures/notion/create_page.yml +76 -61
- data/spec/fixtures/notion/database.yml +78 -61
- data/spec/fixtures/notion/database_query.yml +81 -62
- data/spec/fixtures/notion/databases_list.yml +77 -60
- data/spec/fixtures/notion/page.yml +78 -61
- data/spec/fixtures/notion/paginated_block_children.yml +296 -242
- data/spec/fixtures/notion/paginated_database_query.yml +79 -62
- data/spec/fixtures/notion/paginated_databases_list.yml +78 -61
- data/spec/fixtures/notion/paginated_search.yml +301 -0
- data/spec/fixtures/notion/paginated_users_list.yml +143 -130
- data/spec/fixtures/notion/search.yml +160 -0
- data/spec/fixtures/notion/search_with_query.yml +152 -0
- data/spec/fixtures/notion/update_block.yml +148 -0
- data/spec/fixtures/notion/update_database.yml +152 -0
- data/spec/fixtures/notion/update_page.yml +79 -63
- data/spec/fixtures/notion/users.yml +69 -56
- data/spec/fixtures/notion/users_list.yml +143 -130
- data/spec/notion/api/endpoints/blocks_spec.rb +37 -11
- data/spec/notion/api/endpoints/databases_spec.rb +43 -9
- data/spec/notion/api/endpoints/pages_spec.rb +15 -13
- data/spec/notion/api/endpoints/search_spec.rb +26 -0
- data/spec/notion/api/endpoints/users_spec.rb +4 -4
- data/spec/notion/pagination/cursor_spec.rb +126 -0
- metadata +55 -8
- data/.rspec_status +0 -18
- data/notion-ruby-client-0.0.4.gem +0 -0
- data/scratchpad.rb +0 -22
- data/screenshots/create_notion_bot.png +0 -0
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: a9b83ad4b81b6b52c55b8b65bf33f3075733116d91470d237d000a2428f933ea
|
4
|
+
data.tar.gz: f77c9065b91514bfd3acb7ab42c8a8916c022f6725918861ab5ffce47dedd2df
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: b080379a4840e4b925a6b7bcb5e4c5ea7a25a85856947281cc95eddcc718dd16bb14466d127fca2d2b02a028e4f5df62ea3225ac1a614057578144e43220288c
|
7
|
+
data.tar.gz: aebf1260e3c10c54abebf62259beb35ab0d4ad520c8f26de98a163ed26d5e1989b09ef3d2189622a0a9b34552ac0b0d0085c567d3cd3488fc4a788fd0ba082a9
|
data/.github/workflows/ci.yml
CHANGED
data/.gitignore
ADDED
data/.rubocop.yml
CHANGED
data/CHANGELOG.md
CHANGED
@@ -1,3 +1,35 @@
|
|
1
|
+
### 0.1.0-beta1 (2021-08-29)
|
2
|
+
|
3
|
+
#### New
|
4
|
+
|
5
|
+
- Add support for the following new endpoints:
|
6
|
+
- [Update database](https://developers.notion.com/reference/update-a-database)
|
7
|
+
- [Update page](https://developers.notion.com/reference/patch-page)
|
8
|
+
- [Retrieve a block](https://developers.notion.com/reference/retrieve-a-block)
|
9
|
+
- [Update a block](https://developers.notion.com/reference/update-a-block)
|
10
|
+
- [Search](https://developers.notion.com/reference/search)
|
11
|
+
- Update Notion API Version to `2021-08-16`
|
12
|
+
- Add `bin/console` command for better DX
|
13
|
+
- Overhauled documentation
|
14
|
+
|
15
|
+
#### Upgrade instructions
|
16
|
+
|
17
|
+
- Please refer to the Notion Changelog to see breaking changes for version `2021-08-16`
|
18
|
+
- Regarding this gem, a lot of `id` parameters got renamed to `block_id`, `page_id`, `user_id` and `database_id`. You might need to rename those in your code as well.
|
19
|
+
|
20
|
+
### 0.0.8 (2021-07-27)
|
21
|
+
|
22
|
+
- Bump `Notion-Version` header to `2021-05-13` (@H0R15H0)
|
23
|
+
- Add support for the new Create database endpoint (@H0R15H0)
|
24
|
+
|
25
|
+
### 0.0.7 (2021-06-17)
|
26
|
+
|
27
|
+
- Fixes the query parameter for fetching a page resource
|
28
|
+
|
29
|
+
### 0.0.6 (2021-06-09)
|
30
|
+
|
31
|
+
- Added `Notion-Version` required header to all requests
|
32
|
+
|
1
33
|
### 0.0.5 (2020-04-25)
|
2
34
|
|
3
35
|
- Added support for Blocks endpoints
|
data/CODE_OF_CONDUCT.md
ADDED
@@ -0,0 +1,128 @@
|
|
1
|
+
# Contributor Covenant Code of Conduct
|
2
|
+
|
3
|
+
## Our Pledge
|
4
|
+
|
5
|
+
We as members, contributors, and leaders pledge to make participation in our
|
6
|
+
community a harassment-free experience for everyone, regardless of age, body
|
7
|
+
size, visible or invisible disability, ethnicity, sex characteristics, gender
|
8
|
+
identity and expression, level of experience, education, socio-economic status,
|
9
|
+
nationality, personal appearance, race, religion, or sexual identity
|
10
|
+
and orientation.
|
11
|
+
|
12
|
+
We pledge to act and interact in ways that contribute to an open, welcoming,
|
13
|
+
diverse, inclusive, and healthy community.
|
14
|
+
|
15
|
+
## Our Standards
|
16
|
+
|
17
|
+
Examples of behavior that contributes to a positive environment for our
|
18
|
+
community include:
|
19
|
+
|
20
|
+
* Demonstrating empathy and kindness toward other people
|
21
|
+
* Being respectful of differing opinions, viewpoints, and experiences
|
22
|
+
* Giving and gracefully accepting constructive feedback
|
23
|
+
* Accepting responsibility and apologizing to those affected by our mistakes,
|
24
|
+
and learning from the experience
|
25
|
+
* Focusing on what is best not just for us as individuals, but for the
|
26
|
+
overall community
|
27
|
+
|
28
|
+
Examples of unacceptable behavior include:
|
29
|
+
|
30
|
+
* The use of sexualized language or imagery, and sexual attention or
|
31
|
+
advances of any kind
|
32
|
+
* Trolling, insulting or derogatory comments, and personal or political attacks
|
33
|
+
* Public or private harassment
|
34
|
+
* Publishing others' private information, such as a physical or email
|
35
|
+
address, without their explicit permission
|
36
|
+
* Other conduct which could reasonably be considered inappropriate in a
|
37
|
+
professional setting
|
38
|
+
|
39
|
+
## Enforcement Responsibilities
|
40
|
+
|
41
|
+
Community leaders are responsible for clarifying and enforcing our standards of
|
42
|
+
acceptable behavior and will take appropriate and fair corrective action in
|
43
|
+
response to any behavior that they deem inappropriate, threatening, offensive,
|
44
|
+
or harmful.
|
45
|
+
|
46
|
+
Community leaders have the right and responsibility to remove, edit, or reject
|
47
|
+
comments, commits, code, wiki edits, issues, and other contributions that are
|
48
|
+
not aligned to this Code of Conduct, and will communicate reasons for moderation
|
49
|
+
decisions when appropriate.
|
50
|
+
|
51
|
+
## Scope
|
52
|
+
|
53
|
+
This Code of Conduct applies within all community spaces, and also applies when
|
54
|
+
an individual is officially representing the community in public spaces.
|
55
|
+
Examples of representing our community include using an official e-mail address,
|
56
|
+
posting via an official social media account, or acting as an appointed
|
57
|
+
representative at an online or offline event.
|
58
|
+
|
59
|
+
## Enforcement
|
60
|
+
|
61
|
+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
|
62
|
+
reported to the community leaders responsible for enforcement at
|
63
|
+
nicolas@orbit.love.
|
64
|
+
All complaints will be reviewed and investigated promptly and fairly.
|
65
|
+
|
66
|
+
All community leaders are obligated to respect the privacy and security of the
|
67
|
+
reporter of any incident.
|
68
|
+
|
69
|
+
## Enforcement Guidelines
|
70
|
+
|
71
|
+
Community leaders will follow these Community Impact Guidelines in determining
|
72
|
+
the consequences for any action they deem in violation of this Code of Conduct:
|
73
|
+
|
74
|
+
### 1. Correction
|
75
|
+
|
76
|
+
**Community Impact**: Use of inappropriate language or other behavior deemed
|
77
|
+
unprofessional or unwelcome in the community.
|
78
|
+
|
79
|
+
**Consequence**: A private, written warning from community leaders, providing
|
80
|
+
clarity around the nature of the violation and an explanation of why the
|
81
|
+
behavior was inappropriate. A public apology may be requested.
|
82
|
+
|
83
|
+
### 2. Warning
|
84
|
+
|
85
|
+
**Community Impact**: A violation through a single incident or series
|
86
|
+
of actions.
|
87
|
+
|
88
|
+
**Consequence**: A warning with consequences for continued behavior. No
|
89
|
+
interaction with the people involved, including unsolicited interaction with
|
90
|
+
those enforcing the Code of Conduct, for a specified period of time. This
|
91
|
+
includes avoiding interactions in community spaces as well as external channels
|
92
|
+
like social media. Violating these terms may lead to a temporary or
|
93
|
+
permanent ban.
|
94
|
+
|
95
|
+
### 3. Temporary Ban
|
96
|
+
|
97
|
+
**Community Impact**: A serious violation of community standards, including
|
98
|
+
sustained inappropriate behavior.
|
99
|
+
|
100
|
+
**Consequence**: A temporary ban from any sort of interaction or public
|
101
|
+
communication with the community for a specified period of time. No public or
|
102
|
+
private interaction with the people involved, including unsolicited interaction
|
103
|
+
with those enforcing the Code of Conduct, is allowed during this period.
|
104
|
+
Violating these terms may lead to a permanent ban.
|
105
|
+
|
106
|
+
### 4. Permanent Ban
|
107
|
+
|
108
|
+
**Community Impact**: Demonstrating a pattern of violation of community
|
109
|
+
standards, including sustained inappropriate behavior, harassment of an
|
110
|
+
individual, or aggression toward or disparagement of classes of individuals.
|
111
|
+
|
112
|
+
**Consequence**: A permanent ban from any sort of public interaction within
|
113
|
+
the community.
|
114
|
+
|
115
|
+
## Attribution
|
116
|
+
|
117
|
+
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
|
118
|
+
version 2.0, available at
|
119
|
+
https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
|
120
|
+
|
121
|
+
Community Impact Guidelines were inspired by [Mozilla's code of conduct
|
122
|
+
enforcement ladder](https://github.com/mozilla/diversity).
|
123
|
+
|
124
|
+
[homepage]: https://www.contributor-covenant.org
|
125
|
+
|
126
|
+
For answers to common questions about this code of conduct, see the FAQ at
|
127
|
+
https://www.contributor-covenant.org/faq. Translations are available at
|
128
|
+
https://www.contributor-covenant.org/translations.
|
data/Gemfile.lock
CHANGED
@@ -1,7 +1,9 @@
|
|
1
1
|
PATH
|
2
2
|
remote: .
|
3
3
|
specs:
|
4
|
-
notion-ruby-client (0.0.
|
4
|
+
notion-ruby-client (0.1.0.pre.beta1)
|
5
|
+
activesupport
|
6
|
+
dotenv
|
5
7
|
faraday (>= 1.0)
|
6
8
|
faraday_middleware
|
7
9
|
hashie
|
@@ -9,33 +11,54 @@ PATH
|
|
9
11
|
GEM
|
10
12
|
remote: http://rubygems.org/
|
11
13
|
specs:
|
12
|
-
|
14
|
+
activesupport (6.1.4.1)
|
15
|
+
concurrent-ruby (~> 1.0, >= 1.0.2)
|
16
|
+
i18n (>= 1.6, < 2)
|
17
|
+
minitest (>= 5.1)
|
18
|
+
tzinfo (~> 2.0)
|
19
|
+
zeitwerk (~> 2.3)
|
20
|
+
addressable (2.8.0)
|
13
21
|
public_suffix (>= 2.0.2, < 5.0)
|
14
22
|
ast (2.4.2)
|
23
|
+
concurrent-ruby (1.1.9)
|
15
24
|
crack (0.4.5)
|
16
25
|
rexml
|
17
26
|
diff-lcs (1.4.4)
|
18
|
-
|
27
|
+
dotenv (2.7.6)
|
28
|
+
faraday (1.7.0)
|
29
|
+
faraday-em_http (~> 1.0)
|
30
|
+
faraday-em_synchrony (~> 1.0)
|
19
31
|
faraday-excon (~> 1.1)
|
32
|
+
faraday-httpclient (~> 1.0.1)
|
20
33
|
faraday-net_http (~> 1.0)
|
21
34
|
faraday-net_http_persistent (~> 1.1)
|
35
|
+
faraday-patron (~> 1.0)
|
36
|
+
faraday-rack (~> 1.0)
|
22
37
|
multipart-post (>= 1.2, < 3)
|
23
38
|
ruby2_keywords (>= 0.0.4)
|
39
|
+
faraday-em_http (1.0.0)
|
40
|
+
faraday-em_synchrony (1.0.0)
|
24
41
|
faraday-excon (1.1.0)
|
42
|
+
faraday-httpclient (1.0.1)
|
25
43
|
faraday-net_http (1.0.1)
|
26
|
-
faraday-net_http_persistent (1.
|
27
|
-
|
44
|
+
faraday-net_http_persistent (1.2.0)
|
45
|
+
faraday-patron (1.0.0)
|
46
|
+
faraday-rack (1.0.0)
|
47
|
+
faraday_middleware (1.1.0)
|
28
48
|
faraday (~> 1.0)
|
29
49
|
hashdiff (1.0.1)
|
30
50
|
hashie (4.1.0)
|
51
|
+
i18n (1.8.10)
|
52
|
+
concurrent-ruby (~> 1.0)
|
31
53
|
jaro_winkler (1.5.4)
|
54
|
+
minitest (5.14.4)
|
32
55
|
multipart-post (2.1.1)
|
33
56
|
parallel (1.20.1)
|
34
|
-
parser (3.0.1.
|
57
|
+
parser (3.0.1.1)
|
35
58
|
ast (~> 2.4.1)
|
36
59
|
public_suffix (4.0.6)
|
37
60
|
rainbow (3.0.0)
|
38
|
-
rake (
|
61
|
+
rake (13.0.6)
|
39
62
|
rexml (3.2.5)
|
40
63
|
rspec (3.10.0)
|
41
64
|
rspec-core (~> 3.10.0)
|
@@ -63,14 +86,17 @@ GEM
|
|
63
86
|
rubocop-rspec (1.39.0)
|
64
87
|
rubocop (>= 0.68.1)
|
65
88
|
ruby-progressbar (1.11.0)
|
66
|
-
ruby2_keywords (0.0.
|
89
|
+
ruby2_keywords (0.0.5)
|
67
90
|
timecop (0.9.4)
|
91
|
+
tzinfo (2.0.4)
|
92
|
+
concurrent-ruby (~> 1.0)
|
68
93
|
unicode-display_width (1.7.0)
|
69
94
|
vcr (6.0.0)
|
70
|
-
webmock (3.
|
95
|
+
webmock (3.13.0)
|
71
96
|
addressable (>= 2.3.6)
|
72
97
|
crack (>= 0.3.2)
|
73
98
|
hashdiff (>= 0.4.0, < 2.0.0)
|
99
|
+
zeitwerk (2.4.2)
|
74
100
|
|
75
101
|
PLATFORMS
|
76
102
|
arm64-darwin-20
|
@@ -78,7 +104,7 @@ PLATFORMS
|
|
78
104
|
|
79
105
|
DEPENDENCIES
|
80
106
|
notion-ruby-client!
|
81
|
-
rake (~>
|
107
|
+
rake (~> 13)
|
82
108
|
rspec
|
83
109
|
rubocop (~> 0.82.0)
|
84
110
|
rubocop-performance (~> 1.5.2)
|
@@ -88,4 +114,4 @@ DEPENDENCIES
|
|
88
114
|
webmock
|
89
115
|
|
90
116
|
BUNDLED WITH
|
91
|
-
2.2.
|
117
|
+
2.2.16
|
data/README.md
CHANGED
@@ -1,5 +1,8 @@
|
|
1
1
|
# Notion Ruby Client
|
2
2
|
|
3
|
+
[![Gem Version](https://badge.fury.io/rb/notion-ruby-client.svg)](http://badge.fury.io/rb/notion-ruby-client)
|
4
|
+
[![CI workflow badge](https://github.com/orbit-love/notion-ruby-client/actions/workflows/ci.yml/badge.svg)](https://github.com/orbit-love/notion-ruby-client/actions/workflows/ci.yml)
|
5
|
+
|
3
6
|
A Ruby client for the Notion API.
|
4
7
|
|
5
8
|
## Table of Contents
|
@@ -7,8 +10,28 @@ A Ruby client for the Notion API.
|
|
7
10
|
- [Installation](#installation)
|
8
11
|
- [Usage](#usage)
|
9
12
|
- [Create a New Bot Integration](#create-a-new-bot-integration)
|
10
|
-
- [Declare the API
|
13
|
+
- [Declare the API token](#declare-the-api-token)
|
11
14
|
- [API Client](#api-client)
|
15
|
+
- [Instantiating a new Notion API client](#instantiating-a-new-notion-api-client)
|
16
|
+
- [Pagination](#pagination)
|
17
|
+
- [Endpoints](#endpoints)
|
18
|
+
- [Databases](#databases)
|
19
|
+
- [Query a database](#query-a-database)
|
20
|
+
- [Create a Database](#create-a-database)
|
21
|
+
- [Retrieve a database](#retrieve-a-database)
|
22
|
+
- [List databases](#list-databases)
|
23
|
+
- [Pages](#pages)
|
24
|
+
- [Retrieve a page](#retrieve-a-page)
|
25
|
+
- [Create a page](#create-a-page)
|
26
|
+
- [Update page](#update-page)
|
27
|
+
- [Blocks](#blocks)
|
28
|
+
- [Retrieve block children](#retrieve-block-children)
|
29
|
+
- [Append block children](#append-block-children)
|
30
|
+
- [Users](#users)
|
31
|
+
- [Retrieve a user](#retrieve-a-user)
|
32
|
+
- [List all users](#list-all-users)
|
33
|
+
- [Search](#search)
|
34
|
+
- [Acknowledgements](#acknowledgements)
|
12
35
|
|
13
36
|
## Installation
|
14
37
|
|
@@ -22,15 +45,15 @@ Run `bundle install`.
|
|
22
45
|
|
23
46
|
## Usage
|
24
47
|
|
25
|
-
### Create a New
|
48
|
+
### Create a New Integration
|
26
49
|
|
27
|
-
|
50
|
+
> :blue_book: **Before you start**
|
51
|
+
>
|
52
|
+
> Make sure you are an **Admin** user in your Notion workspace. If you're not an Admin in your current workspace, [create a new personal workspace for free](https://www.notion.so/notion/Create-join-switch-workspaces-3b9be78982a940a7a27ce712ca6bdcf5#9332861c775543d0965f918924448a6d).
|
28
53
|
|
29
|
-
1
|
30
|
-
2. Confirm that you are an Admin in the workspace (see Settings & Members > Members).
|
31
|
-
3. Go to Settings & Members, and click API
|
54
|
+
To create a new integration, follow the steps 1 & 2 outlined in the [Notion documentation](https://developers.notion.com/docs#getting-started). The “_Internal Integration Token_” is what is going to be used to authenticate API calls (referred to here as the “API token”).
|
32
55
|
|
33
|
-
|
56
|
+
> :blue_book: Integrations don't have access to any pages (or databases) in the workspace at first. **A user must share specific pages with an integration in order for those pages to be accessed using the API.**
|
34
57
|
|
35
58
|
### Declare the API token
|
36
59
|
|
@@ -44,7 +67,7 @@ For Rails projects, the snippet above would go to `config/application.rb`.
|
|
44
67
|
|
45
68
|
### API Client
|
46
69
|
|
47
|
-
####
|
70
|
+
#### Instantiating a new Notion API client
|
48
71
|
|
49
72
|
```ruby
|
50
73
|
client = Notion::Client.new
|
@@ -56,36 +79,46 @@ You can specify the token or logger on a per-client basis:
|
|
56
79
|
client = Notion::Client.new(token: '<secret Notion API token>')
|
57
80
|
```
|
58
81
|
|
59
|
-
####
|
82
|
+
#### Pagination
|
60
83
|
|
61
|
-
|
84
|
+
The client natively supports [cursor pagination](https://developers.notion.com/reference/pagination) for methods that allow it, such as `users_list`. Supply a block and the client will make repeated requests adjusting the value of `start_cursor` with every response. The default page size is set to 100 (Notion’s current default and maximum) and can be adjusted via `Notion::Client.config.default_page_size` or by passing it directly into the API call.
|
62
85
|
|
63
86
|
```ruby
|
64
|
-
|
65
|
-
|
66
|
-
|
67
|
-
|
68
|
-
client.users_list do |page|
|
69
|
-
# paginate through all users
|
87
|
+
all_users = []
|
88
|
+
client.users_list(page_size: 25) do |page|
|
89
|
+
all_users.concat(page.results)
|
70
90
|
end
|
91
|
+
all_users # All users, retrieved 25 at a time
|
71
92
|
```
|
72
93
|
|
73
|
-
|
94
|
+
When using cursor pagination the client will automatically pause and then retry the request if it runs into [Notion rate limiting](https://developers.notion.com/reference/errors#request-limits). (It will pause for 10 seconds before retrying the request, a value that can be overriden with `Notion::Client.config.default_retry_after`.) If it receives too many rate-limited responses in a row it will give up and raise an error. The default number of retries is 100 and can be adjusted via `Notion::Client.config.default_max_retries` or by passing it directly into the method as `max_retries`.
|
95
|
+
|
96
|
+
You can also proactively avoid rate limiting by adding a pause between every paginated request with the `sleep_interval` parameter, which is given in seconds.
|
74
97
|
|
75
98
|
```ruby
|
76
|
-
|
99
|
+
all_users = []
|
100
|
+
client.users_list(sleep_interval: 5, max_retries: 20) do |page|
|
101
|
+
# pauses for 5 seconds between each request
|
102
|
+
# gives up after 20 consecutive rate-limited responses
|
103
|
+
all_users.concat(page.results)
|
104
|
+
end
|
105
|
+
all_users
|
77
106
|
```
|
78
107
|
|
79
|
-
|
108
|
+
## Endpoints
|
109
|
+
|
110
|
+
### Databases
|
80
111
|
|
81
|
-
|
112
|
+
#### Query a database
|
113
|
+
|
114
|
+
Gets a paginated array of [Page](https://developers.notion.com/reference/page) objects contained in the database, filtered and ordered according to the filter conditions and sort criteria provided in the request.
|
82
115
|
|
83
116
|
```ruby
|
84
|
-
client.database_query(
|
117
|
+
client.database_query(database_id: 'e383bcee-e0d8-4564-9c63-900d307abdb0') # retrieves the first page
|
85
118
|
|
86
|
-
client.database_query(
|
119
|
+
client.database_query(database_id: 'e383bcee-e0d8-4564-9c63-900d307abdb0', start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')
|
87
120
|
|
88
|
-
client.database_query(
|
121
|
+
client.database_query(database_id: 'e383bcee-e0d8-4564-9c63-900d307abdb0') do |page|
|
89
122
|
# paginate through all pages
|
90
123
|
end
|
91
124
|
|
@@ -112,16 +145,95 @@ filter = {
|
|
112
145
|
}
|
113
146
|
]
|
114
147
|
}
|
115
|
-
client.database_query(
|
148
|
+
client.database_query(database_id: 'e383bcee-e0d8-4564-9c63-900d307abdb0', sort: sort, filter: filter)
|
116
149
|
```
|
117
150
|
|
118
|
-
|
151
|
+
See [Pagination](#pagination) for details about how to iterate through the list.
|
152
|
+
|
153
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/post-database-query).
|
154
|
+
|
155
|
+
#### Create a Database
|
156
|
+
|
157
|
+
Creates a database as a subpage in the specified parent page, with the specified properties schema.
|
119
158
|
|
120
159
|
```ruby
|
121
|
-
|
160
|
+
title = [
|
161
|
+
{
|
162
|
+
"type": "text",
|
163
|
+
"text": {
|
164
|
+
"content": "Grocery List",
|
165
|
+
"link": nil
|
166
|
+
}
|
167
|
+
}
|
168
|
+
]
|
169
|
+
properties = {
|
170
|
+
"Name": {
|
171
|
+
"title": {}
|
172
|
+
},
|
173
|
+
"Description": {
|
174
|
+
"rich_text": {}
|
175
|
+
},
|
176
|
+
"In stock": {
|
177
|
+
"checkbox": {}
|
178
|
+
},
|
179
|
+
"Food group": {
|
180
|
+
"select": {
|
181
|
+
"options": [
|
182
|
+
{
|
183
|
+
"name": "🥦Vegetable",
|
184
|
+
"color": "green"
|
185
|
+
},
|
186
|
+
{
|
187
|
+
"name": "🍎Fruit",
|
188
|
+
"color": "red"
|
189
|
+
},
|
190
|
+
{
|
191
|
+
"name": "💪Protein",
|
192
|
+
"color": "yellow"
|
193
|
+
}
|
194
|
+
]
|
195
|
+
}
|
196
|
+
}
|
197
|
+
}
|
198
|
+
client.create_database(
|
199
|
+
parent: { page_id: '98ad959b-2b6a-4774-80ee-00246fb0ea9b' },
|
200
|
+
title: title,
|
201
|
+
properties: properties
|
202
|
+
)
|
122
203
|
```
|
123
204
|
|
124
|
-
|
205
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/create-a-database).
|
206
|
+
|
207
|
+
#### Update a Database
|
208
|
+
|
209
|
+
Updates an existing database as specified by the parameters.
|
210
|
+
|
211
|
+
```ruby
|
212
|
+
title = [
|
213
|
+
{
|
214
|
+
"text": {
|
215
|
+
"content": "Orbit 💜 Notion"
|
216
|
+
}
|
217
|
+
}
|
218
|
+
]
|
219
|
+
client.update_database(database_id: 'dd428e9dd3fe4171870da7a1902c748b', title: title)
|
220
|
+
```
|
221
|
+
|
222
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/update-a-database).
|
223
|
+
|
224
|
+
#### Retrieve a database
|
225
|
+
|
226
|
+
Retrieves a [Database object](https://developers.notion.com/reference-link/database) using the ID specified.
|
227
|
+
|
228
|
+
```ruby
|
229
|
+
client.database(database_id: 'e383bcee-e0d8-4564-9c63-900d307abdb0')
|
230
|
+
```
|
231
|
+
|
232
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/retrieve-a-database).
|
233
|
+
|
234
|
+
#### List databases
|
235
|
+
|
236
|
+
List all [Databases](https://developers.notion.com/reference-link/database) shared with the authenticated integration.
|
125
237
|
|
126
238
|
```ruby
|
127
239
|
client.databases_list # retrieves the first page
|
@@ -133,26 +245,54 @@ client.databases_list do |page|
|
|
133
245
|
end
|
134
246
|
```
|
135
247
|
|
136
|
-
|
248
|
+
See [Pagination](#pagination) for details about how to iterate through the list.
|
249
|
+
|
250
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/list-databases).
|
251
|
+
|
252
|
+
### Pages
|
253
|
+
|
254
|
+
#### Retrieve a page
|
137
255
|
|
138
|
-
|
256
|
+
Retrieves a [Page object](https://developers.notion.com/reference-link/page) using the ID specified.
|
257
|
+
|
258
|
+
> :blue_book: Responses contains page **properties**, not page content. To fetch page content, use the [retrieve block children](#retrieve-block-children) endpoint.
|
259
|
+
|
260
|
+
```ruby
|
261
|
+
client.page(page_id: 'b55c9c91-384d-452b-81db-d1ef79372b75')
|
262
|
+
```
|
263
|
+
|
264
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/retrieve-a-page).
|
265
|
+
|
266
|
+
#### Create a page
|
267
|
+
|
268
|
+
Creates a new page in the specified database or as a child of an existing page.
|
269
|
+
|
270
|
+
If the parent is a database, the [property values](https://developers.notion.com/reference-link/page-property-value) of the new page in the properties parameter must conform to the parent [database](https://developers.notion.com/reference-link/database)'s property schema.
|
271
|
+
|
272
|
+
If the parent is a page, the only valid property is `title`.
|
273
|
+
|
274
|
+
The new page may include page content, described as [blocks](https://developers.notion.com/reference-link/block) in the children parameter.
|
139
275
|
|
140
276
|
```ruby
|
141
277
|
properties = {
|
142
|
-
"Name":
|
143
|
-
|
144
|
-
|
145
|
-
"
|
278
|
+
"Name": {
|
279
|
+
"title": [
|
280
|
+
{
|
281
|
+
"text": {
|
282
|
+
"content": "Tuscan Kale"
|
283
|
+
}
|
146
284
|
}
|
147
|
-
|
148
|
-
|
149
|
-
"Description":
|
150
|
-
|
151
|
-
|
152
|
-
"
|
285
|
+
]
|
286
|
+
},
|
287
|
+
"Description": {
|
288
|
+
"rich_text": [
|
289
|
+
{
|
290
|
+
"text": {
|
291
|
+
"content": "A dark green leafy vegetable"
|
292
|
+
}
|
153
293
|
}
|
154
|
-
|
155
|
-
|
294
|
+
]
|
295
|
+
},
|
156
296
|
"Food group": {
|
157
297
|
"name": "🥦 Vegetable"
|
158
298
|
},
|
@@ -189,17 +329,148 @@ client.create_page(
|
|
189
329
|
)
|
190
330
|
```
|
191
331
|
|
192
|
-
|
332
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/post-page).
|
193
333
|
|
194
|
-
|
195
|
-
client.page(id: 'b55c9c91-384d-452b-81db-d1ef79372b75')
|
196
|
-
```
|
334
|
+
#### Update page
|
197
335
|
|
198
|
-
|
336
|
+
Updates [page property values](https://developers.notion.com/reference-link/page-property-value) for the specified page. Properties that are not set via the `properties` parameter will remain unchanged.
|
337
|
+
|
338
|
+
If the parent is a database, the new [property values](https://developers.notion.com/reference-link/page-property-value) in the `properties` parameter must conform to the parent [database](https://developers.notion.com/reference-link/database)'s property schema.
|
199
339
|
|
200
340
|
```ruby
|
201
341
|
properties = {
|
202
342
|
"In stock": true
|
203
343
|
}
|
204
|
-
client.update_page(
|
344
|
+
client.update_page(page_id: 'b55c9c91-384d-452b-81db-d1ef79372b75', properties: properties)
|
345
|
+
```
|
346
|
+
|
347
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/patch-page).
|
348
|
+
|
349
|
+
### Blocks
|
350
|
+
|
351
|
+
#### Retrieve a block
|
352
|
+
|
353
|
+
Retrieves a [Block object](https://developers.notion.com/reference-link/block) using the ID specified.
|
354
|
+
|
355
|
+
> :blue_book: If a block contains the key `has_children: true`, use the [Retrieve block children](#retrieve-block-children) endpoint to get the list of children
|
356
|
+
|
357
|
+
```ruby
|
358
|
+
client.block(block_id: '9bc30ad4-9373-46a5-84ab-0a7845ee52e6')
|
359
|
+
```
|
360
|
+
|
361
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/retrieve-a-block).
|
362
|
+
|
363
|
+
#### Update a block
|
364
|
+
|
365
|
+
Updates the content for the specified block_id based on the block type. Supported fields based on the block object type (see [Block object](https://developers.notion.com/reference-link/block#block-type-object) for available fields and the expected input for each field).
|
366
|
+
|
367
|
+
**Note** The update replaces the entire value for a given field. If a field is omitted (ex: omitting checked when updating a to_do block), the value will not be changed.
|
368
|
+
|
369
|
+
```ruby
|
370
|
+
to_do = {
|
371
|
+
'text': [{
|
372
|
+
'text': { 'content': 'Lacinato kale' }
|
373
|
+
}],
|
374
|
+
'checked': false
|
375
|
+
}
|
376
|
+
client.update_block(block_id: '9bc30ad4-9373-46a5-84ab-0a7845ee52e6', 'to_do' => to_do)
|
377
|
+
```
|
378
|
+
|
379
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/retrieve-a-block).
|
380
|
+
|
381
|
+
#### Retrieve block children
|
382
|
+
|
383
|
+
Returns a paginated array of child [block objects](https://developers.notion.com/reference-link/block) contained in the block using the ID specified. In order to receive a complete representation of a block, you may need to recursively retrieve the block children of child blocks.
|
384
|
+
|
385
|
+
```ruby
|
386
|
+
client.block_children(block_id: 'b55c9c91-384d-452b-81db-d1ef79372b75')
|
387
|
+
|
388
|
+
client.block_children(block_id: 'b55c9c91-384d-452b-81db-d1ef79372b75', start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')
|
389
|
+
|
390
|
+
client.block_children(block_id: 'b55c9c91-384d-452b-81db-d1ef79372b75') do |page|
|
391
|
+
# paginate through all children
|
392
|
+
end
|
393
|
+
```
|
394
|
+
|
395
|
+
See [Pagination](#pagination) for details about how to iterate through the list.
|
396
|
+
|
397
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/get-block-children).
|
398
|
+
|
399
|
+
#### Append block children
|
400
|
+
|
401
|
+
Creates and appends new children blocks to the parent block specified by `block_id`.
|
402
|
+
|
403
|
+
Returns a paginated list of newly created first level children block objects.
|
404
|
+
|
405
|
+
```ruby
|
406
|
+
children = [
|
407
|
+
{
|
408
|
+
"object": 'block',
|
409
|
+
"type": 'heading_2',
|
410
|
+
"heading_2": {
|
411
|
+
"text": [{ "type": 'text', "text": { "content": 'A Second-level Heading' } }]
|
412
|
+
}
|
413
|
+
}
|
414
|
+
]
|
415
|
+
client.block_append_children(block_id: 'b55c9c91-384d-452b-81db-d1ef79372b75', children: children)
|
205
416
|
```
|
417
|
+
|
418
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/patch-block-children).
|
419
|
+
|
420
|
+
### Users
|
421
|
+
|
422
|
+
#### Retrieve a user
|
423
|
+
|
424
|
+
Retrieves a [User](https://developers.notion.com/reference/user) using the ID specified.
|
425
|
+
|
426
|
+
```ruby
|
427
|
+
client.user(user_id: 'd40e767c-d7af-4b18-a86d-55c61f1e39a4')
|
428
|
+
```
|
429
|
+
|
430
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/get-user).
|
431
|
+
|
432
|
+
#### List all users
|
433
|
+
|
434
|
+
Returns a paginated list of [Users](https://developers.notion.com/reference/user) for the workspace.
|
435
|
+
|
436
|
+
```ruby
|
437
|
+
client.users_list # retrieves the first page
|
438
|
+
|
439
|
+
client.users_list(start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')
|
440
|
+
|
441
|
+
client.users_list do |page|
|
442
|
+
# paginate through all users
|
443
|
+
end
|
444
|
+
```
|
445
|
+
|
446
|
+
See [Pagination](#pagination) for details about how to iterate through the list.
|
447
|
+
|
448
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/get-users).
|
449
|
+
|
450
|
+
### Search
|
451
|
+
|
452
|
+
Searches all pages and child pages that are shared with the integration. The results may include databases.
|
453
|
+
|
454
|
+
```ruby
|
455
|
+
client.search # search through every available page and database
|
456
|
+
|
457
|
+
client.search(query: 'Specific query') # limits which pages are returned by comparing the query to the page title
|
458
|
+
|
459
|
+
client.search(filter: { property: 'object', value: 'page' }) # only returns pages
|
460
|
+
|
461
|
+
client.search(sort: { direction: 'ascending', timestamp: 'last_edited_time' }) # sorts the results based on the provided criteria.
|
462
|
+
|
463
|
+
client.search(start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')
|
464
|
+
|
465
|
+
client.search do |page|
|
466
|
+
# paginate through all search pages
|
467
|
+
end
|
468
|
+
```
|
469
|
+
|
470
|
+
See [Pagination](#pagination) for details about how to iterate through the list.
|
471
|
+
|
472
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/post-search).
|
473
|
+
|
474
|
+
## Acknowledgements
|
475
|
+
|
476
|
+
The code, specs and documentation of this gem are an adaptation of the fantastic [Slack Ruby Client](https://github.com/slack-ruby/slack-ruby-client) gem. Many thanks to its author and maintainer [@dblock](https://github.com/dblock) and [contributors](https://github.com/slack-ruby/slack-ruby-client/graphs/contributors).
|