API Tutorial - Learn how to create a Notion Wiki for Guild Wars 2 (part 3)
Getting Started with the Notion API
Introduction
Welcome to Part 3 of this blog series! In this part, we'll explore how to set up the Notion API.
In Part 2, we interacted with the public API endpoints offered by Guild Wars 2, so there was no need for security clearances. In this part, however, we'll be modifying our personal Notion pages, so security is a must. We don't want strangers to be able to view and modify our databases. This step-by-step tutorial will help you get the Notion API set up quickly.
If you have not read part 2 of our series, check it out here:
Part 2 — Getting Started with the Guild Wars 2 API.
Creating a Notion Integration
Notion provides an API that can be used to interact with Notion pages and databases. To leverage their API, Notion also introduced Integrations to help control which pages can be accessed through the API.
Many other companies like Dropbox and Make have already created their own integrations, allowing for synchronization and automations between their services and Notion. You can find the full listing of available integrations here: https://www.notion.so/integrations/all.
To get started with the Notion API, you need to create your own Notion integration and give it access to your Notion workspace. This can be accomplished by following their documentation (https://www.notion.so/my-integrations).
An integration requires a name, an associated workspace, and a list of capabilities. The following screenshot shows the setup needed for our purposes. For the name, I’ve chosen “GW2 Wiki Builder”, the associated workspace is simply the parent workspace of your Guild Wars 2 page, and for capabilities, we only need to insert content, but it’s nice to have the option for updating and reading content later.
After submitting your configurations, you'll be provided with a secret integration token that looks like this: secret_NUJXQCTlgUi.V2F5reGnxUB7FYSqaek2aT. Copy and paste it somewhere safe for later use.
Set up a Notion Wiki
In this series, we only explore the Guild Wars 2 /items endpoint. However, there are many more endpoints offered by their API. By the end of this series, you will have the skills and knowledge to work with those other endpoints. To accommodate this, we'll design our Notion wiki to be expandable.
To start, create a page in Notion titled "Guild Wars 2". This will serve as the Wiki’s home page.
Then, inside the “Guild Wars 2” page, create another page titled "Items" to serve as a database for GW2 items. In this page, be sure to select “Table” to convert the plain page into a database.
Connect your Integration to the Wiki
Once you have created your integration, you need to grant it explicit access to the pages you want it to be able to modify. Because we’ll want it to modify our Items database and also possibly other databases in the future, we’ll connect the integration to the entire Wiki page, so it’ll have access to all subpages in the future.
Return to the Guild Wars 2 Notion page (refresh if needed). To connect the integration, open the options menu in the top-right corner, then select the "Add Connections" option and choose the "GW2 Wiki Builder" integration.
At this point, we can make API requests to Notion, similar to how we did with Guild Wars 2. However, we need to provide Postman with authentication parameters to prevent Notion from blocking the requests. We’ll handle this shortly.
Getting the Database ID
When dealing with databases through the API, Notion requires specifying the ID of the database. The question then is: where do we find this ID? Unfortunately, the answer is not straightforward. However, this article https://neverproductive.com/database-id-notion/ provides a clear explanation of where to find the ID and how to extract it.
In a nutshell, Notion embeds the database ID within the URL. So first, navigate to the Items database in Notion (if you haven’t already, turn this page into a table database).
Depending on your Notion settings, the URL of this page may look differently but the steps to extract database ID remain the same. The steps include:
Find the last forward slash (/). Delete it along with everything before it.
Find the question mark (?). Delete it and everything after.
Example
If your database page URL looks like the text below, then the database ID is the red section. Copy this ID and store it securely for future use.
https://www.notion.so/devonfazekas/3d63f7b561d24f3eb39072986f088a4b?v=65769c7858da4162a59977ad9f45c1ea
Setting up Postman for Notion
In this section, we'll go through the steps to authorize Postman to use Notion's APIs. We'll need to provide Postman with authentication parameters to prevent Notion from blocking the requests. To do this, we'll create a new Collection in Postman and add the integration token we created earlier.
Authorize Postman
As previously mentioned, Notion will block all unknown senders of API requests to protect your personal data. To authorize Postman, click on your Notion Collection. Under the Authorization tab, change the type to "Bearer Token" and paste your secret key into the Token field. Save your changes.
Test the Notion API
The Notion API offers many endpoints to play with. Check out their documentation for the full list: https://developers.notion.com/reference/intro.
Let's try a test request to ensure success in our setup. In Postman, create a new request titled “Query Database” within your Notion collection. Note: If you create a request outside the collection, it won't inherit the authorization token and will be blocked.
The URL for the endpoint is https://api.notion.com/v1/databases/:id/query, which should return information about our database. According to the documentation, this is a POST type, not a GET type like before, so be sure to choose that option next to the endpoint’s URL section.
This URL has a path variable, denoted by a colon and the variable name (e.g. :id). You can see it identified in the Params tab in Postman. Referring back to the documentation, this path variable expects the ID of a database. Paste the database ID into its value.
If you tried to send this request now (go ahead and try), Notion would return an error, stating that the request is missing the version number. The documentation elaborates on why a version number is necessary, and what value it expects. Simply add Notion-Version as the key under the Headers tab, with a value of 2022-02-22. Your setup should match the image below.
Press [Send] to send the request. If all is correct, you'll see 200 OK in the status, and the JSON response object below it.
Conclusion
Congratulations! 🎉 You now have the Notion API set up and ready to go. In the next part of this series, we'll start designing our Notion database to store the data we get from the Guild Wars 2 API. See you there!