From bf5c41b9065b7bc9bea95098d014e490918fac8f Mon Sep 17 00:00:00 2001 From: David Stotijn Date: Wed, 7 Sep 2022 22:16:39 +0200 Subject: [PATCH] Update README --- README.md | 136 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 83 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index a57ae9a..207af24 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,15 @@ # go-notion -[![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/dstotijn/go-notion?label=go%20module)](https://github.com/dstotijn/go-notion/tags) -[![Go Reference](https://pkg.go.dev/badge/github.com/dstotijn/go-notion.svg)](https://pkg.go.dev/github.com/dstotijn/go-notion) +[![GitHub tag (latest +SemVer)](https://img.shields.io/github/v/tag/dstotijn/go-notion?label=go%20module)](https://github.com/dstotijn/go-notion/tags) +[![Go +Reference](https://pkg.go.dev/badge/github.com/dstotijn/go-notion.svg)](https://pkg.go.dev/github.com/dstotijn/go-notion) [![GitHub](https://img.shields.io/github/license/dstotijn/go-notion)](LICENSE) -[![Go Report Card](https://goreportcard.com/badge/github.com/dstotijn/go-notion)](https://goreportcard.com/report/github.com/dstotijn/go-notion) +[![Go Report +Card](https://goreportcard.com/badge/github.com/dstotijn/go-notion)](https://goreportcard.com/report/github.com/dstotijn/go-notion) -**go-notion** is a client for the -[Notion API](https://developers.notion.com/reference), written in +**go-notion** is a client for the [Notion +API](https://developers.notion.com/reference), written in [Go](https://golang.org/). ## Features @@ -14,42 +17,72 @@ The client supports all (non-deprecated) endpoints available in the Notion API, as of September 4, 2022: -### Databases - -- [x] [Query a database](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.QueryDatabase) -- [x] [Create a database](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.CreateDatabase) -- [x] [Update database](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.UpdateDatabase) -- [x] [Retrieve a database](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.FindDatabaseByID) - -### Pages - -- [x] [Retrieve a page](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.FindPageByID) -- [x] [Create a page](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.CreatePage) -- [x] [Update page](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.UpdatePage) -- [x] [Retrieve a page property](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.FindPagePropertyByID) - -### Blocks - -- [x] [Retrieve a block](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.FindBlockByID) -- [x] [Update block](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.UpdateBlock) -- [x] [Retrieve block children](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.FindBlockChildrenByID) -- [x] [Append block children](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.AppendBlockChildren) -- [x] [Delete block](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.DeleteBlock) - -### Users - -- [x] [Retrieve a user](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.FindUserByID) -- [x] [List all users](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.ListUsers) -- [x] [Retrieve your token's bot user](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.FindCurrentUser) - -### Search +
+Databases + +- [x] [Query a + database](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.QueryDatabase) +- [x] [Create a + database](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.CreateDatabase) +- [x] [Update + database](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.UpdateDatabase) +- [x] [Retrieve a + database](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.FindDatabaseByID) +
+ +
+Pages + +- [x] [Retrieve a + page](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.FindPageByID) +- [x] [Create a + page](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.CreatePage) +- [x] [Update + page](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.UpdatePage) +- [x] [Retrieve a page + property](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.FindPagePropertyByID) +
+ +
+Blocks + +- [x] [Retrieve a + block](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.FindBlockByID) +- [x] [Update + block](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.UpdateBlock) +- [x] [Retrieve block + children](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.FindBlockChildrenByID) +- [x] [Append block + children](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.AppendBlockChildren) +- [x] [Delete + block](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.DeleteBlock) +
+ +
+Users + +- [x] [Retrieve a + user](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.FindUserByID) +- [x] [List all + users](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.ListUsers) +- [x] [Retrieve your token's bot + user](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.FindCurrentUser) +
+ +
+Search - [x] [Search](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.Search) +
-### Comments +
+Comments -- [x] [Retrieve comments](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.FindCommentsByBlockID) -- [x] [Create a comment](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.CreateComment) +- [x] [Retrieve + comments](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.FindCommentsByBlockID) +- [x] [Create a + comment](https://pkg.go.dev/github.com/dstotijn/go-notion#Client.CreateComment) +
## Installation @@ -57,13 +90,10 @@ as of September 4, 2022: $ go get github.com/dstotijn/go-notion ``` -## Getting started - -To obtain an API key, follow Notion’s [getting started guide](https://developers.notion.com/docs/getting-started). - -### Code example +## Usage -First, construct a new `Client`: +To obtain an API key, follow Notion’s [getting started +guide](https://developers.notion.com/docs/getting-started). ```go import "github.com/dstotijn/go-notion" @@ -71,12 +101,7 @@ import "github.com/dstotijn/go-notion" (...) client := notion.NewClient("secret-api-key") -``` - -Then, use the methods defined on `Client` to make requests to the API. For -example: -```go page, err := client.FindPageByID(context.Background(), "18d35eb5-91f1-4dcb-85b0-c340fd965015") if err != nil { // Handle error... @@ -85,17 +110,22 @@ if err != nil { 👉 Check out the docs on [pkg.go.dev](https://pkg.go.dev/github.com/dstotijn/go-notion) for a complete -reference, and the [examples](/examples) directory for more example code. +reference and the [examples](/examples) directory for more example code. ## Status -The Notion API is currently in _public beta_. +The Notion API itself is out of beta. This library is updated periodically +following documented changes from the Notion +[changelog](https://developers.notion.com/changelog). -⚠️ Although the API itself is versioned, this client **will** make breaking -changes in its code until `v1.0` of the module is released. +**Note:** This library **will** make breaking changes in its code until +`v1.0` of the module is released. There are no immediate plans for a `v1.0` +release. I want the design choices to be solidified and battle-tested more +before committing to a stable release (and the possible burden of a "v2+" Go +module should I want to introduce breaking changes). ## License [MIT License](LICENSE) -© 2021 [David Stotijn](https://v0x.nl) +© 2022 [David Stotijn](https://v0x.nl)