API: Overview

Goal

We want to make it easy for developers to make cool stuff to be used at the tabletop, or to enhance the gaming experience.

Status and Version

The API is production ready and the most current version is 1.0

UPDATE 12/22/2022 - The API Authorization is currently broken, so the API itself is not currently usable. The plan is to upgrade to OAuth 2.0, but we do not currently have an estimate of when that will happen.

Step by step

Browse the API docs to see if the methods you need are available.
Read up a little on OAuth and see if we've got an API wrapper for your language. If no wrapper exists, see if there is a good OAuth library for your particular language, and study the particulars for Obsidian Portal's OAuth implementation.
Register a new application. You'll need to be logged in, since we want to know who made what app.
Write your app and start making requests!

Identifiers

All the identifiers used are UUIDs These are 128-bit unique identifiers. To store them, make sure you use a string of at least 32 characters in length.

Mini objects

Some API methods return mini-objects as part of the response. These are a compact representation of an object (like a user) that includes the most basic parts. The goal of the mini-objects are to avoid needing to re-query the API for basic tasks like displaying a user's name or linking to a particular campaign.

Tips

Store and use identifiers whenever possible. There are some places where we accept usernames or slugs in lieu of identifiers. These are not guaranteed to be permanent and can be changed by the users. Retrieve the identifier for a resource and use that for all future requests to avoid issues where something is changed.
Use the correct subdomain. Authenticated API calls should be made to the api subdomain. However, due to SSL and cookie limitations, when initiating the OAuth authentication (retrieving the tokens and authorizing the user), you must use the www subdomain. Read more about OAuth on Obsidian Portal