Resources
This page lists all over the resource types that can be returned via the API. When submitting patch/post requests for writing content, these are the fields you should use to update. Fields that are marked read only should not be provided with those requests.
Table of Contents
Resources
- Blog Post -
blog_post - Bookshelf -
bookshelf - Chapter -
chapter - Follow -
follow - Group -
group - Group Thread -
group_thread - Private Message -
private_message - Story -
story - Story Tag -
story_tag - User -
user
Understanding this Document
Each resource below contains information regarding the attributes, relationships, etc that they contain.
Relationships
In each relationships table you can find the name of the relationship and the resource(s) it contains. [] are used to denote collections of resources.
Key
- Green - Attribute is writable
- Red - Attribute is read only
- * - Attribute is not returned by default. Manually include in
fields[type]to return it
HTML vs BBCode
The site, and thus API, both use BBCode for the submission and storing of content. However, this is not particularly useful most of the time for API consumers. All BBCode fields return a similarly named field appended with _html in order to return the html version.
For example, chapters have a content attribute as a well as a content_html attribute. The html copy is always read only.
The output HTML is slightly different to the site as things like our embeddable containers make little sense outside the context of the site. Generally the output should be fairly usable without any specific CSS.
Default Fields
Unless otherwise marked, all fields for every resource are returned. The {json:api} spec has no provision for default fields but the problem with this is that certain fields, like chapter content, require a lot of bandwidth and processing to output.
For this reason, we have decided to diverge from the spec and introduce default fields. In this documentation, a * prefixing a field name shows that it is not returned by default. You have to include it in a sparse fieldset when submitting a request.
This way forces consumers to have to consider whether they want to include, rather than exclude, an expensive resource.
Dates
Unless otherwise noted, all dates are provided and should be provided in ISO 8601 format.
Example: 2017-07-14T13:48:14+00:00
Naming Conventions
- All numeric count fields start with
num_ - All date fields start with
date_ - All fields use
snake_case - Fields ending in
_htmlare html output of the corresponding field
Resource Format
All resources follow a specific format to make them easy to handle.
Resource identifiers
All resources must include these identifiers to uniquely identify them in responses.
type- The type of the resourceid- The unique id of the resource
Properties
attributes- List of attributes in the resourcerelationships- List of relationships the resource has
Resources may have as many attributes/relationships as they require.
Example:
{
"type" : "story",
"id" : 1,
"attributes" : {
"title" : "Amazing Story"
},
"relationships" : {
"author" : {
"data" : {
"type" : "user",
"id" : "1"
}
}
}
}Blog Post
Type
blog_post
Attributes
|
title
string
|
Title of the blog post |
|
date_posted
date
|
Date the blog entry was posted |
|
*intro
string
|
HTML marked up truncated intro of the post |
|
*content
object
|
Content of the blog post |
|
*content_html
string
|
HTML version of content |
|
num_views
int
|
Number of views the blog post has |
|
num_comments
int
|
Number of comments the blog post has |
|
site_post
bool
|
Whether the post is a site post or not |
|
site_post_tag
string
|
The site post tag of this post. Only returned if site_post is true |
|
tags
[string]
|
Array of tags on this blog post |
Relationships
|
author
|
User who posted the blog post |
|
tagged_story
|
The story tagged in this blog post |
Bookshelf
Type
bookshelf
Attributes
|
name
string
|
Name of the bookshelf |
|
privacy
enum
( private | unlisted | public )
|
Privacy setting of the bookshelf |
|
description
string
|
Description of the bookshelf |
|
color
string
|
Color of the bookshelf |
|
icon
object
|
The bookshelf's icon |
|
num_stories
int
|
Number of stories in the bookshelf |
|
num_unread
int
|
Number of unread stories in the bookshelf. null when track_unread is not enabled |
|
track_unread
bool
|
Whether the bookshelf is tracking unread chapters or not |
|
quick_add
bool
|
Whether the bookshelf should be shown above stories on the site or not |
|
email_on_update
bool
|
Whether the bookshelf sends out emails on story updates or not |
|
date_created
date
|
Date the bookshelf was created |
|
date_modified
date
|
Date the bookshelf was modified |
|
order
int
|
Order of the bookshelf for controlling display order of the user's library |
Relationships
|
user
|
The user the bookshelf belongs to |
Chapter
Type
chapter
Attributes
|
chapter_number
int
|
The number of the chapter in the story. Starts at 1 |
|
title
string
|
The title of the chapters |
|
published
bool
|
Whether the chapter is published or not |
|
num_views
int
|
The number of views the chapter has |
|
num_words
int
|
The number of words in the chapter |
|
date_published
date
|
The date the chapter was first published |
|
date_modified
date
|
The date the chapter was last modified |
|
*content
string
|
The BBCode markup of the chapter |
|
*content_html
string
|
HTML version of content |
|
*authors_note
object
|
Author's note |
|
*authors_note_html
string
|
HTML version of authors_note |
|
authors_note_position
enum
( top | bottom )
|
Whether the author's note should be shown at the top or bottom of chapters |
Relationships
|
story
|
Story the chapter belongs to |
Follow
Type
follow
Attributes
|
date_followed
date
|
The date the follow was created |
Relationships
|
user
|
The user doing the following |
|
following
|
The user being followed |
Group
Type
group
Attributes
|
name
string
|
Name of the group |
|
description
string
|
Description of the group ( group frontpage ) |
|
description_html
string
|
HTML version of description |
|
num_members
int
|
Number of members in the group |
|
num_stories
int
|
Number of stories in the group |
|
nsfw
bool
|
Whether the group is marked nsfw or not |
|
open
bool
|
Whether the group is accepting new members |
|
hidden
bool
|
Whether the group is hidden or not |
|
date_created
date
|
Date the group was created |
Relationships
|
founder
|
User who founded and owns the group |
Group Thread
Type
group_thread
Attributes
|
title
string
|
The title of the thread |
|
num_posts
int
|
The number of posts in the thread |
|
date_created
date
|
The date the thread was started |
|
date_last_posted
date
|
The date of the last post in the thread |
|
sticky
bool
|
Whether the thread is stickied or not |
|
locked
bool
|
Whether the thread is locked or not |
Relationships
|
creator
|
The user who created the thread |
|
group
|
The group the thread is posted in |
|
last_poster
|
The user who posted the last post in the thread |
Private Message
Type
private_message
Attributes
|
subject
string
|
Subject of the PM |
|
content
object
|
Content of the PM |
|
content_html
string
|
HTML version of content |
|
date_sent
date
|
Date the PM was sent |
|
read
bool
|
Whether the PM has been read or not. null for PMs you did not receive |
Relationships
|
sender
|
User who sent the PM |
|
receiver
|
User who received the PM |
Story
Type
story
Attributes
|
title
string
|
The title of the story |
|
short_description
string
|
The short description of the story |
|
description
string
|
The description of the story |
|
description_html
string
|
HTML version of description |
|
published
bool
|
Whether the story is published or not. Effectively the same as checking if status = visible |
|
status
enum
( visible | not_visible | approve_queue | post_queue )
|
The publish status of the story |
|
submitted
bool
|
Whether the story has been submitted or not. Set to true to submit the story |
|
completion_status
enum
( incomplete | complete | hiatus | cancelled )
|
The completion status of the story |
|
content_rating
enum
( everyone | teen | mature )
|
The content rating of the story |
|
date_published
date
|
Date the story was first published |
|
date_modified
date
|
Date the story was last modified. Updated whenever any edit is made to the story |
|
date_updated
date
|
Date the story was last updated. Only updated when a chapter is added and only if the last bump timing was more than 12 hours ago. |
|
num_views
int
|
Number of views the story has (max on one chapter) |
|
total_num_views
int
|
Total number of views the story has (across all chapters) |
|
num_words
int
|
Number of words the story has |
|
num_comments
int
|
Number of comments the story has |
|
color
color
|
Primary color for the story (based off cover art) |
|
cover_image
object
|
The cover image for the story |
Relationships
|
author
|
The author of the story |
|
chapters
[ chapter ]
|
Chapters in the story |
|
tags
[ story_tag ]
|
The tags for this story |
|
prequel
|
Prequel |
Story Tag
Type
story_tag
Attributes
|
name
string
|
Name of the tag |
|
*description
string
|
Description of the tag |
|
type
enum
( character | genre | rating | content | series | warning | universe )
|
The type of the tag |
|
num_stories
int
|
Number of stories the tag is on. ( Currently 0, included for future use ) |
User
Type
user
Attributes
|
name
string
|
Name of the user |
|
email
string
|
The email for the user |
|
bio
object
|
The user's biography |
|
bio_html
string
|
HTML version of bio |
|
num_followers
int
|
Number of followers the user has |
|
num_stories
int
|
Number of stories the user has published |
|
num_blog_posts
int
|
Number of blog entries the user has posted |
|
date_joined
date
|
Date the user registered on the site |
|
avatar
object
|
The user's avatar |