# Notion
## Features
### Connections / integrations
- [Build your first integration](https://developers.notion.com/docs/create-a-notion-integration)
To share a page with an integration, you need to press "...":
![[Pasted image 20240726105111.png]]
### Databases
- [Creating a database](https://www.notion.so/help/guides/creating-a-database)
### AI features
- Talk with page
- Create AI favourite actions
- Create a block to "generate" -> can be used as template
### Gallery view of databases
Pretty wild way of doing database views
![[Pasted image 20240726103347.png]]
![[Pasted image 20240726103429.png]]
## Blocks
> [!ai]+ Claude
>
> [Creating the Notion API](https://www.notion.so/blog/creating-the-notion-api)
>
> # Notion's Block Architecture
>
> 1. **Block Basics**
> - Everything in Notion is a block (text, images, lists, database rows, pages)
> - Blocks are flexible units of information that can be transformed and moved freely
> - Each block has: ID, Properties, Type, Content, and Parent
>
> 2. **Block Structure**
> - Blocks can be nested inside other blocks
> - The "content" attribute stores an array of child block IDs
> - The hierarchical relationship between blocks forms a "render tree"
>
> 3. **Flexibility and Transformation**
> - Blocks can be transformed between types while preserving properties
> - Indentation in Notion reflects the structure of the render tree
>
> 4. **Permissions**
> - Blocks inherit permissions from their parent blocks
> - A separate "parent" attribute is used for permissions to avoid ambiguity
>
> 5. **Block Lifecycle**
> - Creation: Client generates new block, applies changes locally, sends to server
> - Server Processing: Validates changes, commits to database, notifies real-time update service
> - Real-time Updates: Clients receive updates via WebSocket connections
>
> 6. **Reading Blocks**
> - Clients attempt to load from local cache first
> - If data is missing, request from server using "loadPageChunk" API
> - Loaded data is cached and rendered using React
>
> https://claude.ai/share/a439ac76-7364-4641-b1bd-8fc365fe88b4
## Notion API
> [!ai]+ Claude
>
> [Creating the Notion API](https://www.notion.so/blog/creating-the-notion-api)
>
> # Notion API Development: Key Decisions and Challenges
>
> ## 1. Representing Page Content
>
> ### Block-Based Architecture
> - Notion's content is divided into blocks (images, bullet lists, database rows, pages)
> - Challenge: Translating arbitrary trees of richly-formatted user content into a consistent API
>
> ### Inline Rich Text Formatting
> - Options considered:
> a) Markdown: High portability, low fidelity
> b) Custom JSON: Low portability, high fidelity
> - Chose Custom JSON due to:
> - Notion's rich formatting options not supported by standard Markdown
> - Need for custom block types and Notion-specific features
> - Easier pagination of content trees
>
> ### Paginating Block Hierarchies
> - Challenge: Handling large pages with nested blocks
> - Options considered:
> a) Breadth-first pagination
> b) Depth-first pagination
> - Chose breadth-first pagination for performance reasons
>
> ## 2. API Versioning
> - Opted for global versioning with date-tagged releases
> - Reasons:
> - Encourages small, safe version bumps
> - Easier for clients to manage than per-resource versioning
>
> ## 3. Fetching Page Properties
>
> ### Simple Properties
> - Straightforward JSON representation for basic properties (e.g., text, date, user)
>
> ### Complex Properties: Relations and Rollups
> - Relations: Associate pages across different databases
> - Rollups: Aggregate properties from associated pages
> - Challenges:
> - Loading relations requires multiple database lookups
> - Computing rollups adds another layer of complexity
>
> ### Paginating Relations
> - Implemented cursor-based pagination
> - Allows bounded number of pages to be returned
> - Handles real-time updates to relations
>
> ### Paginating Numeric Rollups
> - Challenge: Computing live rollups with incomplete data
> - Solution:
> - Compute partial results for each batch
> - Encode partial results in cursors as accumulators
> - Update accumulators with each new batch until final value is reached
> - Works for rollups that are:
> - Embarrassingly parallel (can be divided into independent subproblems)
> - Sub-linear space representation (accumulator grows slowly)
>
> ## 4. Design Philosophy
> - Prioritized quality and flexibility over quick delivery
> - Aimed to create a powerful, adaptable tool matching Notion's core principles
> - Focused on handling complex scenarios like relation properties and rollups
>
> ## 5. Future Considerations
> - Potential for community-developed conversion tools (e.g., JSON to standard formats)
> - Ongoing improvements to handle enterprise-scale usage and performance optimization
>
> https://claude.ai/share/a439ac76-7364-4641-b1bd-8fc365fe88b4
## Links
- [The data model behind Notion's flexibility](https://www.notion.so/blog/data-model-behind-notion)
- [Creating the Notion API](https://www.notion.so/blog/creating-the-notion-api)
- [Build your first integration](https://developers.notion.com/docs/create-a-notion-integration)
- [GitHub - phacks/notion-ruby-client: A Ruby client for the Notion API](https://github.com/phacks/notion-ruby-client)
## Code samples
```ruby
# frozen_string_literal: true
require 'notion'
require 'dotenv'
require 'yaml'
Dotenv.load
Notion.configure do |config|
config.token = ENV['NOTION_API_TOKEN']
end
client = Notion::Client.new
all_users = []
client.users_list(page_size: 25) do |page|
all_users.concat(page.results)
end
puts YAML.dump(all_users)
```
> [!failure]- Failure
> Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":" Your credit balance is too low to access the Claude API. Please go to Plans & Billing to upgrade or purchase credits."}}
>
> - plugin:obsidian-textgenerator-plugin:97213 APIError4.generate
> plugin:obsidian-textgenerator-plugin:97213:18
>
> - plugin:obsidian-textgenerator-plugin:97936 Anthropic2.makeStatusError
> plugin:obsidian-textgenerator-plugin:97936:26
>
> - plugin:obsidian-textgenerator-plugin:97979 Anthropic2.makeRequest
> plugin:obsidian-textgenerator-plugin:97979:28
>
> - plugin:obsidian-textgenerator-plugin:5083 async RetryOperation.eval [as _fn] plugin:obsidian-textgenerator-plugin:5083:19
>
>