API Documentation
This is a preliminary proposal based on http://pastebin.com/5quWjita and is intended as a starting point for discussion and initial development.
- Visitor: A person that is not logged in and is simply browsing the page.
- User: A person that has created a user and logged in. No special requirements or pre-approval.
- Administrator: A user with special rights that allow for user administration, editing adventures, comments, etc.
Question: Should we have moderators or other user levels between User and Administrator?
All endpoints follow the guidelines for a semantic web, with a verb (GET, POST, PUT, DELETE) and a URL. GET and PUT requests are idempotent (meaning they can be repeated with the same result) while POST and DELETE are not.
The endpoints also assume a fully front-end powered interface with pure JSON API endpoints except for the initial requests. As such, no endpoints describe page displays except for the initial visits (frontpage, admin panel).
In cases where multiple user authorization levels are mentioned it relates to whether you are editing things you have ownership over (your own user, your own added adventures, etc.) or other peoples things.
| Method | Endpoint | Function | Authorization |
|---|---|---|---|
| GET | / | Frontpage | Visitor |
| GET | /manage/ | Admin Panel | Administrator |
| Method | Endpoint | Function | Authorization |
|---|---|---|---|
| GET | /users/ | List users | User |
| POST | /users/login/ | Login action | User |
| POST | /users/logout/ | Logout action | User |
| POST | /users/register/ | Create new user | Visitor |
| GET | /users/:userID:/ | Get user | User |
| PUT | /users/:userID:/ | Update user | User / Admin |
| DELETE | /users/:userID:/ | Delete user | User / Admin |
| Method | Endpoint | Function | Authorization |
|---|---|---|---|
| GET | /adventures/?:params: | Adventures Search | Visitor |
| POST | /adventures/ | Add Adventure | Visitor |
| GET | /adventures/:advID:/ | Get Adventure | Visitor |
| PUT | /adventures/:advID:/ | Edit Adventure | User / Admin |
| DELETE | /adventures/:advID:/ | Delete Adventure | User / Admin |
Possible adventure search parameters:
- query: Free form search
- page: Pagination (default 1)
- title: Search for titles containing value
- publisher: Limit to specific publisher (hardcoded list?)
- edition: Limit search to a specific D&D Edition
- setting: Limit search to a specific setting (hardcoded list?)
- pub_year/month: Limit to adventures published in the specific year (optionally specific month as well)
- level: Limit to adventures where level is within the minlvl / maxlvl for the adventure.
- maxlvl/minlvl: Limit to adventures that have an exact maxlvl and/or minlvl.
- sessions: Expected number of sessions to complete (on average).
- hours: Expected number of hours to complete (on average).
- maps: Limit search to adventures with maps
- art: Limit search to adventures with art
- artist: Search for artist names containing value
- rating: Limit search to adventures with minimum rating value
- alignment: Limit adventures to those where PCs are expected to be of alignment value
- locale: Limit to adventures within this locale value (ie. Underdark, Urban, Cave, etc.)
- magic: Limit to adventures that match this value (ie. High Magic, Low Magic, No Magic)
- series: Limit to adventures that are part of a series
- theme: Limit to adventures with a specific theme (Haunted, Mystery, Exploration, etc.)
- pctemplates:: Limit to adventures that has pre-made player characters