Fimfiction Developers

{json:api}

Developing applications that use different APIs can involve a lot of work in learning the idiosyncrasies of each specific API. {json:api} attempts to fix (or at least mitigate) this issue by providing a specification for APIs that reduces the effort required to learn to use a new API, reduces request calls, reduces duplication and provides consistent methods for filtering, sorting and paginating responses.

The Fimfiction API is fully compliant (to the best of my knowledge) with {json:api}. Consequently, each endpoint in this documentation does not need a full explanation of how responses look, but rather a list of supported filters, sort parameters and resource type provided with the response.

The full specification can be seen on the {json:api} website. Below you can find simple documentation for some of the major parts of the specification you have to concern yourself with as a consumer, as most of the specification pertains to provider implementations.

Table of Contents

Response Format

All responses are consistent in how they are formatted.

Example response

{
	"data": {
		"id": "1888",
		"type": "story",
		"attributes": {
			"title": "My Little Dashie",
			"short_description": "What would you do if you found a Filly Rainbow Dash in a box?",
			"description": "<p>When your life is as dull a gray as the world that surrounds you, the mundanities can make it all seem meaningless. Sometimes all we need is a little color -- or six -- to reintroduce us to what truly makes life worth living.</p><p>*6-16-2017 Edit, added Rainbow Dash tag because it triggered knighty.*</p>",
			"date_modified": "2011-10-25T22:58:34+00:00",
			"date_published": "2011-10-25T20:47:22+00:00",
			"cover_image": {
				"thumbnail": "https://cdn-img.fimfiction.net/story/hx62-1432420758-1888-tiny",
				"medium": "https://cdn-img.fimfiction.net/story/hx62-1432420758-1888-medium",
				"large": "https://cdn-img.fimfiction.net/story/hx62-1432420758-1888-large",
				"full": "https://cdn-img.fimfiction.net/story/hx62-1432420758-1888-full"
			},
			"color": {
				"hex": "907f6e",
				"rgb": [
					144,
					127,
					110
				]
			},
			"num_views": 508571,
			"total_num_views": 508571,
			"num_words": 12524,
			"num_chapters": 1,
			"num_comments": 4930,
			"rating": 94,
			"status": "complete",
			"content_rating": "everyone",
			"num_likes": 12211,
			"num_dislikes": 807
		},
		"relationships": {
			"author": {
				"data": {
					"type": "user",
					"id": "2538"
				}
			},
			"chapters": {
				"data": {
					"type": "story-chapters",
					"id": "1888"
				}
			},
			"tags": {
				"data": [
					{
						"type": "story_tag",
						"id": "7"
					},
					{
						"type": "story_tag",
						"id": "16"
					},
					{
						"type": "story_tag",
						"id": "73"
					},
					{
						"type": "story_tag",
						"id": "232"
					},
					{
						"type": "story_tag",
						"id": "235"
					}
				]
			}
		},
		"links": {
			"self": "http://fimfic.ddns.net:5002/api/v2/stories/1888"
		},
		"meta": {
			"url": "http://fimfic.ddns.net:5002/story/1888/my-little-dashie"
		}
	},
	"included": [
		{
			"id": "16",
			"type": "story_tag",
			"attributes": {
				"name": "Princess Celestia",
				"description": "",
				"type": "character",
				"num_stories": "0"
			},
			"meta": {
				"old_id": "c:17",
				"url": "http://fimfic.ddns.net:5002/tag/princess-celestia"
			}
		},
		{
			"id": "232",
			"type": "story_tag",
			"attributes": {
				"name": "Human",
				"description": "",
				"type": "genre",
				"num_stories": "0"
			},
			"meta": {
				"old_id": "g:human",
				"url": "http://fimfic.ddns.net:5002/tag/human"
			}
		},
		{
			"id": "235",
			"type": "story_tag",
			"attributes": {
				"name": "Sad",
				"description": "",
				"type": "genre",
				"num_stories": "0"
			},
			"meta": {
				"old_id": "g:sad",
				"url": "http://fimfic.ddns.net:5002/tag/sad"
			}
		},
		{
			"id": "7",
			"type": "story_tag",
			"attributes": {
				"name": "Rainbow Dash",
				"description": "Rainbow Dash is a female Pegasus pony and one of the main characters in My Little Pony Friendship is Magic. She is responsible for maintaining the weather and clearing the skies in Ponyville. As a huge fan of the [url=/tag/wonderbolts]Wonderbolts[/url], she dreams of one day joining their elite flying group. In Sonic Rainboom, [url=/tag/rarity]Rarity[/url] and [url=/tag/princess-celestia]Princess Celestia[/url] both declare that she is the best flier in all of Equestria. Rainbow Dash has a pet tortoise named [url=/tag/tank]Tank[/url], whom she chooses out of [url=/tag/fluttershy]Fluttershy's[/url] offered animals in the episode May the Best Pet Win! She represents the element of loyalty. \r\n[icon]chain[/icon] http://mlp.wikia.com/wiki/Rainbow_Dash",
				"type": "character",
				"num_stories": "0"
			},
			"meta": {
				"old_id": "c:8",
				"url": "http://fimfic.ddns.net:5002/tag/rainbow-dash"
			}
		},
		{
			"id": "73",
			"type": "story_tag",
			"attributes": {
				"name": "Main 6",
				"description": "",
				"type": "character",
				"num_stories": "0"
			},
			"meta": {
				"old_id": "c:74",
				"url": "http://fimfic.ddns.net:5002/tag/main-6"
			}
		},
		{
			"id": "2538",
			"type": "user",
			"attributes": {
				"name": "ROBCakeran53",
				"bio": {
					"bbcode": "Ladies and Gentlemen, take my advice. Pull down your pants and slide on the ice.",
					"html": "<p>Ladies and Gentlemen, take my advice. Pull down your pants and slide on the ice.</p>"
				},
				"num_followers": 3291,
				"num_stories": 16,
				"num_blog_posts": 81,
				"avatar": {
					"16": "https://cdn-img.fimfiction.net/user/25dt-1431818672-2538-16",
					"32": "https://cdn-img.fimfiction.net/user/25dt-1431818672-2538-32",
					"48": "https://cdn-img.fimfiction.net/user/25dt-1431818672-2538-48",
					"64": "https://cdn-img.fimfiction.net/user/25dt-1431818672-2538-64",
					"96": "https://cdn-img.fimfiction.net/user/25dt-1431818672-2538-96",
					"128": "https://cdn-img.fimfiction.net/user/25dt-1431818672-2538-128",
					"192": "https://cdn-img.fimfiction.net/user/25dt-1431818672-2538-192",
					"256": "https://cdn-img.fimfiction.net/user/25dt-1431818672-2538-256",
					"384": "https://cdn-img.fimfiction.net/user/25dt-1431818672-2538-384",
					"512": "https://cdn-img.fimfiction.net/user/25dt-1431818672-2538-512"
				},
				"color": {
					"hex": "bf0f0f",
					"rgb": [
						191,
						15,
						15
					]
				},
				"date_joined": "2011-10-25T06:18:06+00:00"
			},
			"links": {
				"self": "http://fimfic.ddns.net:5002/api/v2/users/2538"
			},
			"meta": {
				"url": "http://fimfic.ddns.net:5002/user/2538/ROBCakeran53"
			}
		}
	]
}

Data

The data parameter is in every request that is not an error. It can contain either a single resource or a collection of resources.

Include

The include parameter is a collection of resources included with the main data in the response. It never contains duplicate type/id pairs.

Links

The links parameter contains a list of relevant links for the response. Primarily this is used for pagination, where any selection of first/next/prev/last may be included and used for subsequent requests.

Filtering

Endpoints that return collections of resources can frequently be filtered. For each documented endpoint you can find the list of filters and what format they take.

Providing these filters is as simple as adding filter[key] query parameters.

Example:

/api/v2/stories?filter[words]=1000,10000

In this example we are filtering out stories with less than 1,000 words and more than 10,000 words. As many filters can be provided as you wish unless otherwise documented by the endpoint. For the sake of readability this example uses [] but actual requests should url encode these as %5B%5D

Sorting

Collection endpoints also can often be sorted. The endpoint documentation provides a list of supported sort parameters.

Sort Format

The sort query parameter supports multiple sort fields by comma delimiting each field. Each field sorts ascending, but can be changed to descending by prefixing the field with -. Not all endpoints support multiple sort parameters (as it frequently does not make sense to do so).

Example:

/api/v2/users?sort=-stories,date_joined

In this example we are sorting users by the number of stories they have posted descending and then sorting by date joined ascending.

The regex used to validate these parameters is ^([+-])?(\w+[\w_-]*)$

Includes

Endpoints can return additional resources related to the main collection / resource. To do this, provide a include query parameter with a comma delimited list of relationships to include.

Example:

/api/v2/stories?include=author

In this example we return the author relationship resources for each story in the response.

Nested relationships are also supported.

/api/v2/groups/1/threads?include=group.founder

Sparse Fieldsets

By default, each resource returns its full representation. However, frequently consumers do not need all of a resource's fields and thus transferring / computing them is a waste. In order to prevent this being the case, sparse fieldsets allow consumers to supply a list of fields they wish for resources to return.

The fields[type] query parameter is used to supply the comma delimited list of fields for that resource type to return. The list of fields includes those in attributes and relationships.

Example:

/api/v2/stories/1888?fields[story]=title,short_description,author

In this example we are selecting just the title and short_descrption attributes as well as the author relationship

Pagination

Large collections can be paginated with the page parameter. Different endpoints have different pagination strategies. The endpoint documentation outlines what strategy is used and the default / maximum values.

Cursor

Cursor based pagination uses a page[size] parameter to control the number of results that are returned. the links section of the response will contain links to subsequent pages.

Page

Page based pagination uses both a page[size] and page[page] parameter. The page number defaults to 1 so you don't typically ever have to provide it because like cursor pagination, links will contain links to subsequent pages but you can manually jump to any page this way by constructing the url yourself.