API / Getting started
Introduction
What the API does and where it lives.
Dustin · Founder, Dustin's Designer Den
API for developers
Build a tool that talks to Dustin's Designer Den. Create projects, upload artwork, and keep components in sync with a designer's account, all on their behalf and with their permission.
The API is free. You need an account and a token. Everything is rate limited, and every write stays inside the limits the designer already has, so an integration can never use more storage or create more projects than their plan allows.
Base URL
https://dustinsdesignerden.com/api/v1
Authorize
https://dustinsdesignerden.com/oauth/authorize
Token
https://dustinsdesignerden.com/oauth/token
/oauth/, outside the /api/v1 prefix.
That is standard, but it catches people out, so it is worth noting once.
The things you will be working with
Designer Den is a tool for making board games. The rest of these docs use five words constantly, so they are worth two minutes now.
Project
One game. A designer might have several: a main game, an expansion, a prototype. Everything else belongs to a project, and nearly every URL in this API contains its id. Your first job in any integration is usually to list a designer's projects and let them pick which one you are working on.
Component
One physical thing in the box, and the piece you will spend most of your time on.
A component has a type, and the type decides which fields matter: a card has
front and back artwork, a die has faces, a rulebook has pages. The types you can
create are
card, token, dice, board, rulebook, spinner, coin, bag, counter, timer .
A component is a definition, not a count of physical objects. One
card component with a quantity of 40 means one
card design that gets printed 40 times, not 40 separate components.
unique_id
Your own name for a component, and the single most important idea here. You invent it, we store it, and you send it every time. The first time we see one, we create the component. Every time after, we find that same component and update it.
That is what makes repeated writes safe. Without it we fall back to matching on the component's name, so the moment a designer renames a card, your next sync creates a duplicate instead of updating the original. Use whatever id your own system already has, keep it stable, and never reuse one for a different component.
Deck and stack
A named group of components that belong together and, on the virtual table, sit in a pile. A deck holds cards; a stack holds tokens. Grouping is separate from the components themselves, so deleting a deck leaves its cards in the project.
Order matters: the order you send members in becomes the order of the pile, which is the draw order when someone plays.
Asset
An image file stored in the designer's account, usually component artwork. You upload a file, get a public URL back, and put that URL on a component. Assets count against the designer's storage quota, which is why you can check what room they have left before you start.
You do not have to upload anything. If your artwork already lives on a public URL, you can point components straight at it and use no storage at all. The Syncing components guide lays out that tradeoff.
How they fit together
A typical integration does this, in this order:
- Get permission to act for a designer, and a token that proves it. See Authentication.
- Find or create the project you are working on.
- Get the artwork where it needs to be, either by uploading it or by linking to your own.
- Write the components, each carrying your own
unique_idand the artwork URL. - Group them into decks and stacks, in the order they should sit in.
- Optionally, register a webhook so you hear about later changes instead of asking.
Artwork before components is deliberate, because components carry the image URLs. Quickstart walks the shortest version of this with real calls.