Introduction
The Dbljump API is a system for cataloging and serving data about video games and the video game industry.
It is part of a wider group of software, Dbljump, which is made up of:
- The Dbljump PostgreSQL database
- The back-end dbljump/rails-api, a Ruby on Rails application that manages the database and provides the API described here. This is currently under development.
- The front-end client dbljump/client-ember, an Ember.js application that provides a web user interface. This is currently under development.
- Dbljump.com, the web domain where it all comes together
This API is therefore designed to be used exclusively by the Dbljump front-end client.
This documentation, which describes the features of the API and how to use them, is intended for use by the Dbljump development team. It was built with Slate and is hosted with GitHub Pages.
For more information, or if you want to contribute or join us, please visit www.dbljump.com.
How to use
Basic rules for making API requests.
Domain
URLs in this documentation exclude the domain where the production API is hosted. Prepend the current domain name to URLs when making requests, e.g. http://api.dbljump.com/articles/games.
JSON API specification
This API accepts and returns JSON data, following the JSON API specification as closely as possible.
Read more about the specification.
HTTP headers: request content-type and version
In accordance with the JSON API spec, all requests must include two HTTP headers, which declare the content-type and API version number:
Accept:application/vnd.api+json; version={vnum}Content-Type:application/vnd.api+json; version={vnum}
Replace {vnum} with the API version number you want to use. The current version number is 1, and this is not expected to change anytime soon!
HTTP headers: response content-type
Successful responses include the following HTTP header:
Content-Type:application/vnd.api+json; charset=utf-8
Authorizing requests and logging in users
Many Dbljump API requests require authorization. This API uses JWTs for authentication and authorization, instead of HTTP sessions. When authorization is needed, it must be provided via a JSON web token (JWT) included in the Authorization HTTP header.
The presence and payload content of a JWT determines:
- whether or not a user is ‘logged in’
- the authorization level of the user identified by the JWT
- whether the request is authorized (based on the validity of the JWT and the user’s authorization level)
HTTP headers: request authorizations
A valid Authorization header and JWT must always be included when the client user is logged in and always excluded when the client user is not logged in.
The header must be provided as follows:
Authorization:Bearer {user-jwt}
Replace {user-jwt} with a JWT returned by a successful user authentication request.
The JWT payload
As well providing request authorization, JWTs contain a JSON payload the client can decode and use to identify the logged-in user.
| JWT payload attribute | Description |
|---|---|
user_id |
Can be used to get the logged-in user’s record. |
user_role |
Determines the user’s authorization level. Can be member, editor or admin. |
expiry |
The JWT expiry date and time. |
User role and authorization level
API request authorization also depends on the role of the user that the passed JWT belongs to.
Users can have one of three roles:
| Role | Description |
|---|---|
member |
Ordinary user. Can sign in and view pages but has very limited abilities. |
editor |
Can create, edit (and in some cases delete) articles and images. |
admin |
Can do everthing, including managing users, places, platform, genres and so on. |
This documentation describes the authorization level required to use each each API feature.
Using URL queries
URL query examples
# Include all primary_image items related to articles in the response:
/articles/games?include=primary_image
# Specify sparse fieldsets for users and images (users are included by
# default):
/users/2/images?fields[users]=username,avatar&fields[images]=title,thumb
# Use filter to only return items where kind == 'photo':
/media/images?filter[kind]=photo
# Specify 10 items per page and return page 5:
/users?page[size]=10&page[number]=5
# Sort by two fields: kind (ascending) and created_by_id (descending
# as prepended by a dash):
/media/images?sort=kind,-created_by_id
# Search for platforms related to 'nintendo'
/platforms?search=nintendo
This API supports URL queries, including those specified by JSON API:
| Query | Description |
|---|---|
fields[{type}] |
Specify sparse fieldsets. You must provide the type(s) and field name(s). |
filter[{field}] |
Filter data by a given field and value. |
include[{type}] |
Include resources related to the main dataset. |
page[size] |
Specify how many items should be on each page. Defaults to 30. |
page[number] |
Specify the page number. Defaults to 1. |
search |
Use with GET collection endpoints. Search by string. |
sort |
Sort the data by specified fields. Prepend the field name with a - to sort descending. |
Filter fields
Below is a table of fields by which you can filter each record-type.
| Record type | Filterable fields |
|---|---|
| articles | type, kind, origin_date, origin_year, origin_place_id, ended, end_date, end_year, latest_place_id, status, created_by_id, last_review_outcome, last_reviewed_by_id, published_at |
| genres | created_by_id |
| places | kind, parent_id, created_by_id |
| platforms | holder_id, sphere, kind, parent_id, created_by_id |
| users | gender, role, birthday, country_id, activated_at |
| credits | credited_id, game_id, version_id, place_id, role, category |
| kinships | parent_id, child_id, kind, start_year, end_year |
| names | article_id, version_id, name_or_title, family_name, given_names, kind, writing_system, year_adopted, year_dropped, dropped |
| notes | article_id, version_id, type, category, cite_website, created_by_id |
| images | kind, year, date, place_id, uploaded_by_id, usage_type, usage_license_code, attributed_name |
| versions | game_id, platform_id, status, fps_target, fps_unlocked, res_w, res_h, res_unlocked |
| releases | version_id, place_id, date, year, physical, digital |
Searchable record types
Below is a list of record types that accept search queries.
companiesgamesgenresimagespeopleplacesplatformsusers
Sort fields
Below is a table of fields by which you can sort each record-type.
| Record type | Sortable fields |
|---|---|
| articles | type, sort_title, origin_date, origin_year, created_by_id, status, last_submitted_at, last_reviewed_at, last_review_outcome, published_at |
| genres | name, short_name, parent_id, created_by_id |
| places | name, formatted, type, kind, parent_id, created_by_id, iso_code |
| platforms | holder_id, name, short_name, sphere, kind, parent_id, created_by_id |
| users | email, family_name, gender, username, role, birthday, country_id, last_signed_in_at, sign_in_count, activation_sent_at, activated_at, password_reset_sent_at |
| credits | credited_id, game_id, version_id, place_id, role, category |
| kinships | kind, start_year, end_year |
| names | name_or_title, family_name, given_names, kind, writing_system, year_adopted, year_dropped, dropped |
| notes | type, category, cite_website, created_by_id |
| images | kind, title, year, date, place_id, uploaded_by_id, usage_type |
| versions | game_id, platform_id, status, fps_target, fps_unlocked, res_w, res_h, res_unlocked |
| releases | version_id, place_id, date, year, physical, digital |
Articles
Use this feature to get mixed collections of game, company and people articles.
Default response attributes
| Attribute | Description |
|---|---|
| display_title (str) | The main article title |
| sort_title (str) | Removes ‘The’ for company and game names; puts family name first for people |
| slug (str) | Unique parameterized display_title used for friendly URLs |
| description (str) | Article summary text |
| last_submitted_at (time) | Date and time last submitted for peer review |
| last_reviewed_at (time) | Date and time last peer reviewed |
| last_review_outcome (str) | Outcome of last peer review |
| last_review_comments (str) | Comments from last peer review |
| published_at (time) | Date and time published |
| status (str) | Publishing status |
Relationships
| Relationship | JSON API type |
|---|---|
| primary_images | images |
| created_by | users |
| last_reviewed_by | users |
Get all articles
Response body |
HTTP 200
# GET /articles?articles?page[size]=2&sort=-status&filter[type]=game
{
"data": [
{
"id": "95",
"type": "games",
"attributes": {
"display_title": "Shadow of the Beast",
"sort_title": "Shadow of the Beast",
"slug": "shadow-of-the-beast",
"description": "Shadow of the Beast is 1989 fantasy platform game developed by Reflections and published by Psygnosis.",
"last_submitted_at": null,
"last_reviewed_at": null,
"last_review_outcome": null,
"last_review_comments": null,
"published_at": "2017-08-15T09:33:50.976Z",
"status": "published"
},
"relationships": {
"primary_image": {
"data": {
"id": "87",
"type": "images"
},
"links": {
"related": "http://localhost:3000/media/images/shadow-of-the-beast-amiga-screenshot"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/1"
}
},
"last_reviewed_by": {
"data": null
}
},
"meta": {
"description": "Find Shadow of the Beast trivia, screenshots, credits and other info at Dbljump, the video game reference.",
"keywords": "Shadow of the Beast, 1989, Amiga, Atari ST, Commodore 64, Amstrad CPC, ZX Spectrum, Genesis, Master System, Lynx, FM Towns, TurboGrafx-CD, game, credits, screenshots, trivia, dbljump, video games, pc games, gaming",
"created_at": "2017-08-15T09:33:50.982Z",
"updated_at": "2017-08-15T09:34:27.992Z"
}
},
{
"id": "94",
"type": "games",
"attributes": {
"display_title": "North & South",
"sort_title": "North & South",
"slug": "north-south",
"description": "North & South is a 1989 American Civil War-themed strategy game developed by Infogrames.",
"last_submitted_at": null,
"last_reviewed_at": null,
"last_review_outcome": null,
"last_review_comments": null,
"published_at": "2017-08-15T09:33:50.928Z",
"status": "published"
},
"relationships": {
"primary_image": {
"data": {
"id": "86",
"type": "images"
},
"links": {
"related": "http://localhost:3000/media/images/north-south-atari-st-screenshot"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/1"
}
},
"last_reviewed_by": {
"data": null
}
},
"meta": {
"description": "Find North & South trivia, screenshots, credits and other info at Dbljump, the video game reference.",
"keywords": "North & South, 1989, Amiga, Atari ST, Commodore 64, MS-DOS, MSX, Nintendo Entertainment System, ZX Spectrum, Amstrad CPC, Nord et Sud, game, credits, screenshots, trivia, dbljump, video games, pc games, gaming",
"created_at": "2017-08-15T09:33:50.934Z",
"updated_at": "2017-08-15T09:34:27.462Z"
}
}
],
"included": [
{
"id": "87",
"type": "images",
"attributes": {
"original": "http://localhost:3000/uploads/images/87/shadow-of-the-beast-amiga-screenshot-1708151034.jpg",
"thumb": "http://localhost:3000/uploads/images/87/th_shadow-of-the-beast-amiga-screenshot-1708151034.jpg",
"title": "Shadow of the Beast Amiga screenshot"
},
"links": {
"self": "http://localhost:3000/media/images/shadow-of-the-beast-amiga-screenshot"
},
"meta": {
"description": "'Shadow of the Beast Amiga screenshot' is a video game image at Dbljump.",
"keywords": "Shadow of the Beast Amiga screenshot, screen, Psygnosis Limited, image, picture, media, dbljump, video games, pc games, gaming",
"created_at": "2017-08-15T09:34:27.853Z",
"updated_at": "2017-08-15T09:34:27.853Z"
}
},
{
"id": "1",
"type": "users",
"attributes": {
"username": "tikithekiwi",
"avatar_thumb": "http://localhost:3000/uploads/user_avatar/1/th_tikithekiwi-1708151031.jpg"
},
"links": {
"self": "http://localhost:3000/users/1"
},
"meta": {
"description": "Tiki the Kiwi is a member at Dbljump, the video game reference.",
"keywords": "tikithekiwi, Tiki the Kiwi, user, dbljump, video games, pc games, gaming",
"last_signed_in_at": null,
"last_sign_in_ip": null,
"sign_in_count": 0,
"activated_at": "2017-08-15T09:31:43.431Z",
"created_at": "2017-08-15T09:31:45.327Z",
"updated_at": "2017-08-15T09:31:45.327Z"
}
},
{
"id": "86",
"type": "images",
"attributes": {
"original": "http://localhost:3000/uploads/images/86/north-south-atari-st-screenshot-1708151034.gif",
"thumb": "http://localhost:3000/uploads/images/86/th_north-south-atari-st-screenshot-1708151034.gif",
"title": "North & South Atari ST screenshot"
},
"links": {
"self": "http://localhost:3000/media/images/north-south-atari-st-screenshot"
},
"meta": {
"description": "'North & South Atari ST screenshot' is a video game image at Dbljump.",
"keywords": "North & South Atari ST screenshot, screen, Infogrames, image, picture, media, dbljump, video games, pc games, gaming",
"created_at": "2017-08-15T09:34:27.293Z",
"updated_at": "2017-08-15T09:34:27.293Z"
}
}
],
"links": {
"self": "http://localhost:3000/articles?filter%5Btype%5D=game&page%5Bnumber%5D=1&page%5Bsize%5D=2&sort=-id",
"next": "http://localhost:3000/articles?filter%5Btype%5D=game&page%5Bnumber%5D=2&page%5Bsize%5D=2&sort=-id",
"last": "http://localhost:3000/articles?filter%5Btype%5D=game&page%5Bnumber%5D=10&page%5Bsize%5D=2&sort=-id"
},
"meta": {
"total_items": 19
}
}
Retrieve a collection of articles.
HTTP request
GET /articles
URL queries
- See the ‘Using URL queries’ section for more information and a table of sort query fields.
| Filter field | Acceptable values |
|---|---|
| type | game, company, person |
| status | draft, submitted, published_at |
| origin_date | 1800-01-01 or later |
| origin_year | 1800 or later |
| ended | true or false |
| end_date | 1800-01-01 or later |
| end_year | 1800 or later |
| created_by_id | Valid user ID |
| last_review_outcome | ok, fail_style, fail_incomplete, fail_accuracy |
Success HTTP response code
200 OK
Articles: Games
Resources related to game articles.
Request attributes
See Create a new game and Update a game.
Response attributes
Get all games
Response body |
HTTP 200
# GET /articles/games?page[size]=2
{
"data": [
{
"id": "45",
"type": "games",
"attributes": {
"display_title": "Pong",
"description": "Pong is a table tennis sports game and is one of the earliest arcade video games.",
"origin_date": "1972-11-29",
"origin_year": 1972,
"slug": "pong"
},
"relationships": {
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/1"
}
}
},
"links": {
"self": "http://localhost:3000/articles/games/pong"
}
},
{
"id": "46",
"type": "games",
"attributes": {
"display_title": "The Wonderful 101",
"description": "The Wonderful 101 is an action-adventure video game developed by Platinum Games for the Nintendo Wii U.",
"origin_date": "2013-08-23",
"origin_year": 2013,
"slug": "the-wonderful-101"
},
"relationships": {
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/1"
}
}
},
"links": {
"self": "http://localhost:3000/articles/games/the-wonderful-101"
}
}
],
"links": {
"self": "http://localhost:3000/articles/games?page%5Bnumber%5D=1&page%5Bsize%5D=2",
"next": "http://localhost:3000/articles/games?page%5Bnumber%5D=2&page%5Bsize%5D=2",
"last": "http://localhost:3000/articles/games?page%5Bnumber%5D=2&page%5Bsize%5D=2"
},
"meta": {
"total_items": 3
}
}
Retrieve all game articles. Automatically paginated.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /articles/games
URL query parameters
| Parameter | Default | Description |
|---|---|---|
| fields[{record-type}] | All fields | Return only specified fields, e.g. ?fields[games]=display_title,origin_date |
| filter[{field}] | All records | Filter search by field, e.g. ?filter[origin_year]=2015 |
| page[number] | 1 | Select the page number, e.g. ?page[number]=3 |
| page[size] | 30 | Select the number of records per page, e.g. ?page[size]=20 |
Success HTTP response code
200 OK
Get a single game
Response body |
HTTP 200
# GET /articles/games/the-wonderful-101
{
"data": {
"id": "46",
"type": "games",
"attributes": {
"display_title": "The Wonderful 101",
"description": "The Wonderful 101 is an action-adventure video game developed by Platinum Games for the Nintendo Wii U.",
"slug": "the-wonderful-101",
"last_submitted_at": null,
"last_reviewed_at": null,
"last_review_outcome": null,
"last_review_comments": null,
"published_at": "2017-06-28T17:04:28.473Z",
"status": "published",
"origin_date": "2013-08-23",
"origin_year": 2013
},
"relationships": {
"primary_image": {
"data": null,
"links": {
"related": "http://localhost:3000/media/images/nintendo-office-photo"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/1"
}
},
"last_reviewed_by": {
"data": null
},
"titles": {
"data": [
{
"id": "58",
"type": "game_titles"
},
{
"id": "59",
"type": "game_titles"
},
{
"id": "60",
"type": "game_titles"
}
],
"links": {
"related": "http://localhost:3000/articles/games/the-wonderful-101/titles"
}
},
"notes": {
"data": [
{
"id": "12",
"type": "game_notes"
}
],
"links": {
"related": "http://localhost:3000/articles/games/the-wonderful-101/notes"
}
},
"genres": {
"data": [
{
"id": "1",
"type": "genres"
},
{
"id": "2",
"type": "genres"
},
{
"id": "23",
"type": "genres"
}
],
"links": {
"related": "http://localhost:3000/articles/games/the-wonderful-101/genres"
}
},
"versions": {
"data": [
{
"id": "1",
"type": "game_versions"
}
],
"links": {
"related": "http://localhost:3000/articles/games/the-wonderful-101/versions"
}
},
"images": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/games/the-wonderful-101/images"
}
},
"company_credits": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/games/the-wonderful-101/company_credits"
}
},
"person_credits": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/games/the-wonderful-101/company_credits"
}
}
},
"links": {
"self": "http://localhost:3000/articles/games/the-wonderful-101"
}
},
"included": [
{
"id": "1",
"type": "users",
"attributes": {
"username": "tikithekiwi",
"avatar": null
},
"links": {
"self": "http://localhost:3000/users/1"
}
},
{
"id": "1",
"type": "genres",
"attributes": {
"name": "action",
"short_name": ""
},
"links": {
"self": "http://localhost:3000/genres/action"
}
},
{
"id": "2",
"type": "genres",
"attributes": {
"name": "adventure",
"short_name": ""
},
"links": {
"self": "http://localhost:3000/genres/adventure"
}
},
{
"id": "23",
"type": "genres",
"attributes": {
"name": "comedy",
"short_name": ""
},
"links": {
"self": "http://localhost:3000/genres/comedy"
}
}
],
"meta": {
"keywords": "The Wonderful 101, 2013, game, credits, screenshots, trivia, dbljump, video games, pc games, gaming",
"description": "Find The Wonderful 101 trivia, screenshots, credits and other info at Dbljump, the video game reference.",
"created_at": "2017-06-28T17:04:28.478Z",
"updated_at": "2017-06-28T17:04:28.478Z"
}
}
Retrieve a single game article. Games are publicly available. No sign-in is required.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /articles/games/{slug} (replace {slug} with record slug)
Success HTTP response code
200 OK
Response attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| display_title | string | Y | The article title, usually the company name. |
| description | text | A short biography up to 800 chars. | |
| origin_date | date | Between 1st Jan 1800 and the present. | |
| origin_year | integer | Between 1800 and the present year. |
Relationships
| Association | Record type | Relationship type |
|---|---|---|
| created_by | users | belongs_to |
| genres | genres | has_many |
| primary_image | images | belongs_to |
Meta
The meta section of the JSON response includes keywords, description, created_at and updated_at attributes.
Create a new game
Request body |
POST /articles/games
{
"data": {
"type": "games",
"attributes": {
"display_title": "New Game",
"description": "New Game is an action game developed by some company or other.",
"origin_date": "2015-01-03",
"origin_year": ""
},
"relationships": {
"primary_image": {
"data": {
"id": "1",
"type": "images"
}
}
}
}
}
Response body |
HTTP 201
{
"data": {
"id": "50",
"type": "games",
"attributes": {
"display_title": "New Game",
"description": "New Game is an action game developed by some company or other.",
"slug": "new-game",
"last_submitted_at": null,
"last_reviewed_at": null,
"last_review_outcome": null,
"last_review_comments": null,
"published_at": null,
"status": "draft",
"origin_date": "2015-01-03",
"origin_year": 2015
},
"relationships": {
"primary_image": {
"data": {
"id": "1",
"type": "images"
},
"links": {
"related": "http://localhost:3000/media/images/nintendo-office-photo"
}
},
"created_by": {
"data": {
"id": "2",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/2"
}
},
"last_reviewed_by": {
"data": null
},
"titles": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/games/new-game/titles"
}
},
"notes": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/games/new-game/notes"
}
},
"genres": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/games/new-game/genres"
}
},
"versions": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/games/new-game/versions"
}
},
"images": {
"data": [
{
"id": "1",
"type": "images"
}
],
"links": {
"related": "http://localhost:3000/articles/games/new-game/images"
}
},
"company_credits": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/games/new-game/company_credits"
}
},
"person_credits": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/games/new-game/company_credits"
}
}
},
"links": {
"self": "http://localhost:3000/articles/games/new-game"
}
},
"included": [
{
"id": "1",
"type": "images",
"attributes": {
"file": "http://localhost:3000/uploads/images/1/nintendo-hq-kyoto-2006.jpg",
"title": "Nintendo office"
},
"links": {
"self": "http://localhost:3000/media/images/nintendo-office-photo"
}
},
{
"id": "2",
"type": "users",
"attributes": {
"username": "neil",
"avatar": "http://localhost:3000/uploads/user_avatar/2/1706221451.jpg"
},
"links": {
"self": "http://localhost:3000/users/2"
}
}
],
"meta": {
"keywords": "New Game, 2015, game, credits, screenshots, trivia, dbljump, video games, pc games, gaming",
"description": "Find New Game trivia, screenshots, credits and other info at Dbljump, the video game reference.",
"created_at": "2017-06-27T22:31:20.875Z",
"updated_at": "2017-06-27T22:31:20.875Z"
}
}
Create a new game article. User must be an editor or admin. The genres relationship cannot be edited.
- User authentication: required
- Authorization level: editor or admin
HTTP request
POST /articles/games
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| display_title | string | Y | 1-250 characters. |
| description | text | 1-800 characters. | |
| origin_date | date | Between 1st Jan 1800 and the present. | |
| origin_year | integer | Between 1800 and the present year. |
Relationships
Check this section’s code example to see how to update these relationships.
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| primary_image | belongs_to | images | The main article image, usually a game poster. |
Success HTTP response code
201 Created
Update a game
Request body |
PATCH /articles/games/dark-souls
{
"data": {
"type": "games",
"id": "pong",
"attributes": {
"display_title": "Changed Name",
"description": "Updated description for an updated article.",
"origin_date": "1995-11-17",
"origin_year": ""
},
"relationships": {
"primary_image": {
"data": {
"id": "1",
"type": "images"
}
},
"genres": {
"data": [
{ "type": "genres", "id": "5" },
{ "type": "genres", "id": "12" }
]
}
}
}
}
Response body |
HTTP 200
{
"data": {
"id": "47",
"type": "games",
"attributes": {
"display_title": "Changed Name",
"description": "Updated description for an updated article.",
"slug": "changed-name-7f116bac-0ccd-421e-bc25-090cccc63a41",
"last_submitted_at": null,
"last_reviewed_at": null,
"last_review_outcome": null,
"last_review_comments": null,
"published_at": "2017-06-28T17:04:28.494Z",
"status": "published",
"origin_date": "1995-11-17",
"origin_year": 1995
},
"relationships": {
"primary_image": {
"data": {
"id": "1",
"type": "images"
},
"links": {
"related": "http://localhost:3000/media/images/nintendo-office-photo"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/1"
}
},
"last_reviewed_by": {
"data": null
},
"titles": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/games/changed-name-7f116bac-0ccd-421e-bc25-090cccc63a41/titles"
}
},
"notes": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/games/changed-name-7f116bac-0ccd-421e-bc25-090cccc63a41/notes"
}
},
"genres": {
"data": [
{
"id": "12",
"type": "genres"
},
{
"id": "5",
"type": "genres"
}
],
"links": {
"related": "http://localhost:3000/articles/games/changed-name-7f116bac-0ccd-421e-bc25-090cccc63a41/genres"
}
},
"versions": {
"data": [
{
"id": "2",
"type": "game_versions"
},
{
"id": "3",
"type": "game_versions"
},
{
"id": "4",
"type": "game_versions"
}
],
"links": {
"related": "http://localhost:3000/articles/games/changed-name-7f116bac-0ccd-421e-bc25-090cccc63a41/versions"
}
},
"images": {
"data": [
{
"id": "1",
"type": "images"
}
],
"links": {
"related": "http://localhost:3000/articles/games/changed-name-7f116bac-0ccd-421e-bc25-090cccc63a41/images"
}
},
"company_credits": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/games/changed-name-7f116bac-0ccd-421e-bc25-090cccc63a41/company_credits"
}
},
"person_credits": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/games/changed-name-7f116bac-0ccd-421e-bc25-090cccc63a41/company_credits"
}
}
},
"links": {
"self": "http://localhost:3000/articles/games/changed-name-7f116bac-0ccd-421e-bc25-090cccc63a41"
}
},
"included": [
{
"id": "1",
"type": "images",
"attributes": {
"file": "http://localhost:3000/uploads/images/1/nintendo-hq-kyoto-2006.jpg",
"title": "Nintendo office"
},
"links": {
"self": "http://localhost:3000/media/images/nintendo-office-photo"
}
},
{
"id": "1",
"type": "users",
"attributes": {
"username": "tikithekiwi",
"avatar": null
},
"links": {
"self": "http://localhost:3000/users/1"
}
},
{
"id": "12",
"type": "genres",
"attributes": {
"name": "role-playing game",
"short_name": "RPG"
},
"links": {
"self": "http://localhost:3000/genres/role-playing-game"
}
},
{
"id": "5",
"type": "genres",
"attributes": {
"name": "educational",
"short_name": ""
},
"links": {
"self": "http://localhost:3000/genres/educational"
}
}
],
"meta": {
"keywords": "Changed Name, 1995, PlayStation 3, Xbox 360, Windows, game, credits, screenshots, trivia, dbljump, video games, pc games, gaming",
"description": "Find Changed Name trivia, screenshots, credits and other info at Dbljump, the video game reference.",
"created_at": "2017-06-28T17:04:28.500Z",
"updated_at": "2017-06-28T17:08:46.331Z"
}
}
Update an existing game article. The user must be an editor. The genres relationship can be edited.
- User authentication: required
- Authorization level: admin
HTTP request
PATCH /articles/games/{slug} (replace {slug} with record slug)
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| display_title | string | Y | 1-250 characters. |
| description | text | 1-800 characters. | |
| origin_date | date | Between 1st Jan 1800 and the present. | |
| origin_year | integer | Between 1800 and the present year. |
Relationships
Check this section’s code example to see how to update these relationships.
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| primary_image | belongs_to | images | The main article image, usually a game poster. | |
| genres | has_many | genres | The genres this game belongs to. |
Success HTTP response code
200 OK
Delete a game
Delete an existing game article. User must be an editor or admin.
- User authentication: required
- Authorization level: editor or admin
HTTP request
DELETE /articles/games/{slug} (replace {slug} with record slug)
Success HTTP response code
204 No Content
Errors
Errors specific to creating and updating game articles.
| HTTP code | Error code | Pointer | Title |
|---|---|---|---|
| 400 | GAME_DISPLAY_TITLE_BLANK | display_title | Display title is required. |
| 400 | GAME_DISPLAY_TITLE_TOO_LONG | display_title | Display title cannot be more than 250 characters. |
| 400 | GAME_DESCRIPTION_TOO_LONG | description | Description cannot be more than 800 characters. |
| 400 | GAME_ORIGIN_DATE_INCLUSION | origin_date | Release date must be a past date not before 1800. |
| 400 | GAME_ORIGIN_YEAR_INCLUSION | origin_year | Release year must be a past year not before 1800. |
Articles: Game Versions
Resources related to game versions. There can be one version of a game per platform.
Request attributes
See Create a new game version and Update a game version.
Response attributes
Get all game versions
Response body |
HTTP 200
# GET /articles/game_versions?page[size]=2
{
"data": [
{
"id": "83",
"type": "game_versions",
"attributes": {
"status": "extant",
"fps_target": 30,
"fps_unlocked": null,
"res_w": 1280,
"res_h": 720,
"res_unlocked": null
},
"relationships": {
"game": {
"data": {
"id": "79",
"type": "games"
},
"links": {
"related": "http://localhost:3000/articles/games/dark-souls"
}
},
"platform": {
"data": {
"id": "13",
"type": "platforms"
},
"links": {
"related": "http://localhost:3000/platforms/sony-playstation-3"
}
},
"primary_image": {
"data": null
},
"images": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/game_versions/83/images"
}
}
},
"meta": {
"description": "Find facts, images and credits for the PlayStation 3 version of Dark Souls at Dbljump, the video game reference.",
"keywords": "Dark Souls, PlayStation 3, platform, version, dbljump, video games, pc games, gaming",
"created_at": "2017-07-27T22:24:39.631Z",
"updated_at": "2017-07-27T22:24:39.631Z"
}
},
{
"id": "84",
"type": "game_versions",
"attributes": {
"status": "extant",
"fps_target": 30,
"fps_unlocked": null,
"res_w": 1280,
"res_h": 720,
"res_unlocked": null
},
"relationships": {
"game": {
"data": {
"id": "79",
"type": "games"
},
"links": {
"related": "http://localhost:3000/articles/games/dark-souls"
}
},
"platform": {
"data": {
"id": "18",
"type": "platforms"
},
"links": {
"related": "http://localhost:3000/platforms/microsoft-xbox-360"
}
},
"primary_image": {
"data": null
},
"images": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/game_versions/84/images"
}
}
},
"meta": {
"description": "Find facts, images and credits for the Xbox 360 version of Dark Souls at Dbljump, the video game reference.",
"keywords": "Dark Souls, Xbox 360, platform, version, dbljump, video games, pc games, gaming",
"created_at": "2017-07-27T22:24:39.641Z",
"updated_at": "2017-07-27T22:24:39.641Z"
}
}
],
"links": {
"self": "http://localhost:3000/articles/games/dark-souls/versions?page%5Bnumber%5D=1&page%5Bsize%5D=2",
"next": "http://localhost:3000/articles/games/dark-souls/versions?page%5Bnumber%5D=2&page%5Bsize%5D=2",
"last": "http://localhost:3000/articles/games/dark-souls/versions?page%5Bnumber%5D=2&page%5Bsize%5D=2"
},
"meta": {
"total_items": 3
}
}
Retrieve all game versions. Automatically paginated.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /articles/game_versions
URL query parameters
| Parameter | Default | Description |
|---|---|---|
| fields[{record-type}] | All fields | Return only specified fields, e.g. ?fields[game_versions]=status,fps_target |
| filter[{field}] | All records | Filter search by field, e.g. ?filter[status]=rumored |
| page[number] | 1 | Select the page number, e.g. ?page[number]=3 |
| page[size] | 30 | Select the number of records per page, e.g. ?page[size]=20 |
Success HTTP response code
200 OK
Get a single game version
Response body |
HTTP 200
# GET /articles/game_versions/80
{
"data": {
"id": "80",
"type": "game_versions",
"attributes": {
"status": "extant",
"fps_target": 30,
"fps_unlocked": null,
"res_w": 1280,
"res_h": 720,
"res_unlocked": null
},
"relationships": {
"game": {
"data": {
"id": "82",
"type": "games"
},
"links": {
"related": "http://localhost:3000/articles/games/the-legend-of-zelda-breath-of-the-wild"
}
},
"platform": {
"data": {
"id": "25",
"type": "platforms"
},
"links": {
"related": "http://localhost:3000/platforms/nintendo-wii-u"
}
},
"primary_image": {
"data": null
},
"images": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/game_versions/80/images"
}
}
},
"meta": {
"description": "Find facts, images and credits for the Wii U version of The Legend of Zelda: Breath of the Wild at Dbljump, the video game reference.",
"keywords": "The Legend of Zelda: Breath of the Wild, Wii U, platform, version, dbljump, video games, pc games, gaming",
"created_at": "2017-07-27T22:24:39.603Z",
"updated_at": "2017-07-27T22:24:39.603Z"
}
},
"included": [
{
"id": "82",
"type": "games",
"attributes": {
"display_title": "The Legend of Zelda: Breath of the Wild"
},
"links": {
"self": "http://localhost:3000/articles/games/the-legend-of-zelda-breath-of-the-wild"
},
"meta": {
"description": "Find The Legend of Zelda: Breath of the Wild trivia, screenshots, credits and other info at Dbljump, the video game reference.",
"keywords": "The Legend of Zelda: Breath of the Wild, 2017, Switch, Wii U, game, credits, screenshots, trivia, dbljump, video games, pc games, gaming",
"created_at": "2017-07-27T22:24:38.651Z",
"updated_at": "2017-07-27T22:25:04.144Z"
}
},
{
"id": "25",
"type": "platforms",
"attributes": {
"name": "Wii U"
},
"links": {
"self": "http://localhost:3000/platforms/nintendo-wii-u"
},
"meta": {
"description": "Find out about games for Wii U by Nintendo Co., Ltd. at Dbljump, the video game reference.",
"keywords": "Wii U, WiiU, Nintendo, home, system, platform, dbljump, video games, pc games, gaming",
"created_at": "2017-07-27T22:24:36.910Z",
"updated_at": "2017-07-27T22:24:36.910Z"
}
}
]
}
Retrieve a single game version. Game versions are publicly available. No sign-in is required.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /articles/game_versions/{id} (replace {id} with record ID)
Success HTTP response code
200 OK
Response attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| status | string | Y | Must be ‘extant’, 'rumored’, 'canceled’ or 'unknown’. |
| fps_target | number | Version target refresh rate. Max 1000. | |
| fps_unlocked | boolean | True if framerate is dynamic based on hardware (usually for modern PC games). | |
| res_w | number | Native display resolution width, e.g. '720’. Max 10,000. | |
| res_h | number | Native display resolution height, e.g. '1280’. Max 10,000. | |
| res_unlocked | boolean | True if resolution is dynamic based on hardware (usually for modern PC games). |
Relationships
| Association | Record type | Relationship type |
|---|---|---|
| game | games | belongs_to |
| platform | platforms | belongs_to |
Meta
The meta section of the JSON response includes keywords, description, created_at and updated_at attributes.
Create a new game version
Request body |
POST /articles/game_versions
{
"data": {
"type": "game_versions",
"attributes": {
"status": "rumored",
"fps_target": "60",
"fps_unlocked": "false",
"res_w": "1920",
"res_h": "1080",
"res_unlocked": "false"
},
"relationships": {
"game": {
"data": {
"id": "79",
"type": "games"
}
}
},
"platform": {
"data": {
"id": "60",
"type": "platforms"
}
}
}
}
}
Response body |
HTTP 201
{
"data": {
"id": "96",
"type": "game_versions",
"attributes": {
"status": "rumored",
"fps_target": 60,
"fps_unlocked": false,
"res_w": 1920,
"res_h": 1080,
"res_unlocked": false
},
"relationships": {
"game": {
"data": {
"id": "79",
"type": "games"
},
"links": {
"related": "http://localhost:3000/articles/games/dark-souls"
}
},
"platform": {
"data": {
"id": "60",
"type": "platforms"
},
"links": {
"related": "http://localhost:3000/platforms/commodore-international-commodore-64"
}
},
"primary_image": {
"data": null
},
"images": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/game_versions/96/images"
}
}
},
"meta": {
"description": "Find facts, images and credits for the Commodore 64 version of Dark Souls at Dbljump, the video game reference.",
"keywords": "Dark Souls, Commodore 64, platform, version, dbljump, video games, pc games, gaming",
"created_at": "2017-07-30T21:21:34.021Z",
"updated_at": "2017-07-30T21:21:34.021Z"
}
},
"included": [
{
"id": "79",
"type": "games",
"attributes": {
"display_title": "Dark Souls"
},
"links": {
"self": "http://localhost:3000/articles/games/dark-souls"
},
"meta": {
"description": "Find Dark Souls trivia, screenshots, credits and other info at Dbljump, the video game reference.",
"keywords": "Dark Souls, 2011, PlayStation 3, Xbox 360, Windows, game, credits, screenshots, trivia, dbljump, video games, pc games, gaming",
"created_at": "2017-07-27T22:24:38.585Z",
"updated_at": "2017-07-27T22:25:00.050Z"
}
},
{
"id": "60",
"type": "platforms",
"attributes": {
"name": "Commodore 64"
},
"links": {
"self": "http://localhost:3000/platforms/commodore-international-commodore-64"
},
"meta": {
"description": "Find out about games for Commodore 64 by Commodore International at Dbljump, the video game reference.",
"keywords": "Commodore 64, C64, Commodore International, home, system, platform, dbljump, video games, pc games, gaming",
"created_at": "2017-07-27T22:24:37.796Z",
"updated_at": "2017-07-27T22:24:37.796Z"
}
}
]
}
Create a new game version. User must be an editor or admin.
- User authentication: required
- Authorization level: editor or admin
HTTP request
POST /articles/game_versions
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| status | string | Y | Must be ‘extant’, 'rumored’, 'canceled’ or 'unknown’. |
| fps_target | number | Version target refresh rate. Max 1000. | |
| fps_unlocked | boolean | True if framerate is dynamic based on hardware (usually for modern PC games) | |
| res_w | number | Native display resolution width, e.g. '720’. Max 10,000. | |
| res_h | number | Native display resolution height, e.g. '1280’. Max 10,000. | |
| res_unlocked | boolean | True if resolution is dynamic based on hardware (usually for modern PC games) |
Relationships
Check this section’s code example to see how to update these relationships.
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| game | belongs_to | Y | games | The game the version belongs to. |
| platform | belongs_to | Y | platforms | Platform this version runs on, e.g. PlayStation 4. |
Success HTTP response code
201 Created
Update a game version
Request body |
PATCH /articles/game_versions/3
{
"data": {
"type": "game_versions",
"id": "3",
"attributes": {
"status": "unknown",
"fps_target": "30",
"fps_unlocked": "false",
"res_w": "1920",
"res_h": "1080",
"res_unlocked": "false"
},
"relationships": {
"platform": {
"data": {
"id": "12",
"type": "platforms"
}
}
}
}
}
Response body |
HTTP 200
{
"data": {
"id": "3",
"type": "game_versions",
"attributes": {
"status": "unknown",
"fps_target": 30,
"fps_unlocked": false,
"res_w": 1920,
"res_h": 1080,
"res_unlocked": false
},
"relationships": {
"game": {
"data": {
"id": "95",
"type": "games"
},
"links": {
"related": "http://localhost:3000/articles/games/shadow-of-the-beast"
}
},
"platform": {
"data": {
"id": "12",
"type": "platforms"
},
"links": {
"related": "http://localhost:3000/platforms/sony-playstation-2"
}
},
"primary_image": {
"data": null
},
"images": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/game_versions/3/images"
}
}
},
"meta": {
"description": "Find facts, images and credits for the PlayStation 2 version of Shadow of the Beast at Dbljump, the video game reference.",
"keywords": "Shadow of the Beast, PlayStation 2, platform, version, dbljump, video games, pc games, gaming",
"created_at": "2017-07-27T22:24:39.018Z",
"updated_at": "2017-07-30T21:24:04.585Z"
}
},
"included": [
{
"id": "95",
"type": "games",
"attributes": {
"display_title": "Shadow of the Beast"
},
"links": {
"self": "http://localhost:3000/articles/games/shadow-of-the-beast"
},
"meta": {
"description": "Find Shadow of the Beast trivia, screenshots, credits and other info at Dbljump, the video game reference.",
"keywords": "Shadow of the Beast, 1989, Amiga, Atari ST, Commodore 64, Amstrad CPC, ZX Spectrum, Genesis, Master System, Lynx, FM Towns, TurboGrafx-CD, game, credits, screenshots, trivia, dbljump, video games, pc games, gaming",
"created_at": "2017-07-27T22:24:38.945Z",
"updated_at": "2017-07-27T22:25:24.453Z"
}
},
{
"id": "12",
"type": "platforms",
"attributes": {
"name": "PlayStation 2"
},
"links": {
"self": "http://localhost:3000/platforms/sony-playstation-2"
},
"meta": {
"description": "Find out about games for PlayStation 2 by Sony Corporation at Dbljump, the video game reference.",
"keywords": "PlayStation 2, PS2, Sony, home, system, platform, dbljump, video games, pc games, gaming",
"created_at": "2017-07-27T22:24:36.464Z",
"updated_at": "2017-07-27T22:24:36.464Z"
}
}
]
}
Update an existing game version. The user must be an editor.
- User authentication: required
- Authorization level: admin
HTTP request
PATCH /articles/game_versions/{id} (replace {id} with record ID)
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| status | string | Y | Must be ‘extant’, 'rumored’, 'canceled’ or 'unknown’. |
| fps_target | number | Version target refresh rate. Max 1000. | |
| fps_unlocked | boolean | True if framerate is dynamic based on hardware (usually for modern PC games). | |
| res_w | number | Native display resolution width, e.g. '720’. Max 10,000. | |
| res_h | number | Native display resolution height, e.g. '1280’. Max 10,000. | |
| res_unlocked | boolean | True if resolution is dynamic based on hardware (usually for modern PC games). |
Relationships
Check this section’s code example to see how to update these relationships.
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| platform | belongs_to | Y | platforms | Platform this version runs on, e.g. PlayStation 4. |
Success HTTP response code
200 OK
Delete a game version
Delete an existing game version. User must be an editor or admin.
- User authentication: required
- Authorization level: editor or admin
HTTP request
DELETE /articles/game_versions/{id} (replace {id} with record ID)
Success HTTP response code
204 No Content
Errors
Errors specific to creating and updating game version.
| HTTP code | Error code | Pointer | Title |
|---|---|---|---|
| 400 | GAME_VERSION_PLATFORM_ID_BLANK | data/relationships/platform/data/id | Platform ID is required. |
| 400 | GAME_VERSION_PLATFORM_ID_TAKEN | data/relationships/platform/data/id | There’s already a version of this game for that platform. |
| 400 | GAME_VERSION_STATUS_BLANK | status | Status is required. |
| 400 | GAME_VERSION_STATUS_INCLUSION | status | Status must be ‘extant’, 'rumored’, 'canceled’ or 'unknown’. |
| 400 | GAME_VERSION_FPS_TARGET_LESS_THAN_OR_EQUAL_TO | fps_target | Target FPS must be less than or equal to 1000. |
| 400 | GAME_VERSION_RES_W_LESS_THAN_OR_EQUAL_TO | res_w | Resolution width must be less than or equal to 10,000. |
| 400 | GAME_VERSION_RES_H_LESS_THAN_OR_EQUAL_TO | res_h | Resolution height must be less than or equal to 10,000. |
Articles: Game Version Releases
Resources related to game version releases. A release is a region- or country-specific edition of a game version, e.g. the Japanese release of the PS3 version of Bayonetta.
Request attributes
See Create a new release and Update a release.
Response attributes
See Get a single version release
Get all of a version’s releases
Response body |
HTTP 200
# GET /articles/game_version_releases
{
"data": [
{
"id": "1",
"type": "version_releases",
"attributes": {
"date": "2013-08-23",
"year": 2013,
"physical": true,
"digital": true
},
"relationships": {
"version": {
"data": {
"id": "1",
"type": "game_versions"
},
"links": {
"related": "http://localhost:3000/articles/game_versions/1"
}
},
"place": {
"data": {
"id": "234",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/europe"
}
}
}
},
{
"id": "2",
"type": "version_releases",
"attributes": {
"date": "2013-09-15",
"year": 2013,
"physical": true,
"digital": true
},
"relationships": {
"version": {
"data": {
"id": "1",
"type": "game_versions"
},
"links": {
"related": "http://localhost:3000/articles/game_versions/1"
}
},
"place": {
"data": {
"id": "233",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/north-america"
}
}
}
},
{
"id": "3",
"type": "version_releases",
"attributes": {
"date": "2013-08-24",
"year": 2013,
"physical": true,
"digital": true
},
"relationships": {
"version": {
"data": {
"id": "1",
"type": "game_versions"
},
"links": {
"related": "http://localhost:3000/articles/game_versions/1"
}
},
"place": {
"data": {
"id": "102",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/japan"
}
}
}
}
],
"links": {},
"meta": {
"total_items": 3
}
}
Retrieve all game version releases. Automatically paginated.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /articles/game_version_releases
URL query parameters
| Parameter | Default | Description |
|---|---|---|
| fields[{record-type}] | All fields | Return only specified fields, e.g. ?fields[version_releases]=date,year |
| filter[{field}] | All records | Filter search by field, e.g. ?filter[year]=2013 |
| page[number] | 1 | Select the page number, e.g. ?page[number]=3 |
| page[size] | 30 | Select the number of records per page, e.g. ?page[size]=20 |
Success HTTP response code
200 OK
Get a single game version release
Response body |
HTTP 200
# GET /articles/game_version_releases/1
{
"data": {
"id": "1",
"type": "version_releases",
"attributes": {
"date": "2013-08-23",
"year": 2013,
"physical": true,
"digital": true
},
"relationships": {
"version": {
"data": {
"id": "1",
"type": "game_versions"
},
"links": {
"related": "http://localhost:3000/articles/game_versions/1"
}
},
"place": {
"data": {
"id": "234",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/europe"
}
}
}
},
"included": [
{
"id": "234",
"type": "places",
"attributes": {
"formatted": "Europe"
},
"links": {
"self": "http://localhost:3000/places/europe"
}
}
],
"meta": {
"keywords": "The Wonderful 101, Wii U, Europe, release, dbljump, video games, pc games, gaming",
"description": "",
"created_at": "2017-06-22T13:51:23.959Z",
"updated_at": "2017-06-22T13:51:23.959Z"
}
}
Retrieve a single game version release. Releases are publicly available. No sign-in is required.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /articles/game_version_releases/{id} (replace {id} with record ID)
Success HTTP response code
200 OK
Response attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| date | date | Release date, e.g. ‘2013-08-24’ for 24 August 2013. | |
| year | number | Release year. Auto-filled if date present. | |
| physical | boolean | True if release included physical format (e.g. disc or cartridge) | |
| digital | boolean | True if release included digital format (i.e. download) |
Relationships
| Association | Record type | Relationship type |
|---|---|---|
| place | places | belongs_to |
| version | game_versions | belongs_to |
Meta
The meta section of the JSON response includes keywords, description, created_at and updated_at attributes.
Create a new game version release
Request body |
POST /articles/game_version_releases
{
"data": {
"type": "version_releases",
"attributes": {
"date": "2013-08-01",
"year": "",
"physical": "false",
"digital": "true"
},
"relationships": {
"version": {
"data": {
"id": "1",
"type": "game_versions"
}
},
"place": {
"data": {
"id": "102",
"type": "places"
}
}
}
}
}
Response body |
HTTP 201
{
"data": {
"id": "13",
"type": "version_releases",
"attributes": {
"date": "2013-08-01",
"year": 2013,
"physical": false,
"digital": true
},
"relationships": {
"version": {
"data": {
"id": "1",
"type": "game_versions"
},
"links": {
"related": "http://localhost:3000/articles/game_versions/1"
}
},
"place": {
"data": {
"id": "1",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/afghanistan"
}
}
}
},
"included": [
{
"id": "1",
"type": "places",
"attributes": {
"formatted": "Afghanistan"
},
"links": {
"self": "http://localhost:3000/places/afghanistan"
}
}
],
"meta": {
"keywords": "The Wonderful 101, Wii U, Afghanistan, release, dbljump, video games, pc games, gaming",
"description": "",
"created_at": "2017-06-27T20:48:15.095Z",
"updated_at": "2017-06-27T20:48:15.095Z"
}
}
Create a new game version release. User must be an editor or admin.
- User authentication: required
- Authorization level: editor or admin
HTTP request
POST /articles/game_version_releases
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| date | date | Release date, e.g. ‘2013-08-24’ for 24 August 2013. | |
| year | number | Release year. Auto-filled if date present. | |
| physical | boolean | True if release included physical format (e.g. disc or cartridge) | |
| digital | boolean | True if release included digital format (i.e. download) |
Relationships
Check this section’s code example to see how to update these relationships.
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| version | belongs_to | Y | game_versions | The version the release belongs to. |
| place | belongs_to | Y | places | Release country or region. There can be one game version release per place. |
Success HTTP response code
201 Created
Update a game version release
Request body |
PATCH /articles/game_version_releases/1
{
"data": {
"type": "version_releases",
"id": "1",
"attributes": {
"date": "2016-08-14",
"year": "",
"physical": "true",
"digital": "false"
},
"relationships": {
"place": {
"data": {
"id": "90",
"type": "places"
}
}
}
}
}
Response body |
HTTP 200
{
"data": {
"id": "1",
"type": "version_releases",
"attributes": {
"date": "2016-08-14",
"year": 2016,
"physical": true,
"digital": false
},
"relationships": {
"version": {
"data": {
"id": "1",
"type": "game_versions"
},
"links": {
"related": "http://localhost:3000/articles/game_versions/1"
}
},
"place": {
"data": {
"id": "90",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/hong-kong"
}
}
}
},
"included": [
{
"id": "90",
"type": "places",
"attributes": {
"formatted": "Hong Kong"
},
"links": {
"self": "http://localhost:3000/places/hong-kong"
}
}
],
"meta": {
"keywords": "The Wonderful 101, Wii U, Hong Kong, release, dbljump, video games, pc games, gaming",
"description": "",
"created_at": "2017-06-22T13:51:23.959Z",
"updated_at": "2017-06-27T21:03:09.428Z"
}
}
Update an existing game version release. The user must be an editor.
- User authentication: required
- Authorization level: admin
HTTP request
PATCH /articles/game_version_releases/{id} (replace {id} with record ID)
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| date | date | Release date, e.g. ‘2013-08-24’ for 24 August 2013. | |
| year | number | Release year. Auto-filled if date present. | |
| physical | boolean | True if release included physical format (e.g. disc or cartridge) | |
| digital | boolean | True if release included digital format (i.e. download) |
Relationships
Check this section’s code example to see how to update these relationships.
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| place | belongs_to | Y | places | Release country or region. There can be one game version release per place. |
Success HTTP response code
200 OK
Delete a game version release
Delete an existing game version release. User must be an editor or admin.
- User authentication: required
- Authorization level: editor or admin
HTTP request
DELETE /articles/game_version_releases/{id} (replace {id} with record ID)
Success HTTP response code
204 No Content
Errors
Errors specific to creating and updating game version releaes.
| HTTP code | Error code | Pointer | Title |
|---|---|---|---|
| 400 | VERSION_RELEASE_PLACE_ID_BLANK | data/relationships/place/data/id | Place is required. |
| 400 | VERSION_RELEASE_PLACE_ID_TAKEN | data/relationships/place/data/id | There’s already a release of this version for that place. |
| 400 | VERSION_RELEASE_PLACE_ID_INVALID | data/relationships/place/data/id | Status is required. |
| 400 | VERSION_RELEASE_DATE_INCLUSION | date | Date must be after 1799 and not more than 3 years in the future. |
| 400 | VERSION_RELEASE_YEAR_INCLUSION | year | Year must be after 1799 and not more than 3 years in the future. |
Articles: Game Aliases
Resources related to game aliases. An alias is another title the game is known by. The JSON:API type is game_aliases.
Mutable attributes
display_text (string, required)
The alias. 1-250 chars.
kind (string, required)
Name classification. Must be title, working or translated.
writing_system (string, required)
Must be Latin, Japanese, Cyrillic, Chinese or Arabic.
Relationships
| Name | JSON:API type | Relationship type | Required? |
|---|---|---|---|
game |
games |
belongs_to |
Y |
version |
game_versions |
belongs_to |
|
place |
places |
belongs_to |
Get a collection of game aliases
Response body |
HTTP 200
# GET /articles/game_aliases?page[size]=2
{
"data": [
{
"id": "58",
"type": "game_aliases",
"attributes": {
"display_text": "Project P-100",
"kind": "working",
"writing_system": "Latin"
},
"relationships": {
"game": {
"data": {
"id": "46",
"type": "games"
},
"links": {
"related": "http://localhost:3000/articles/games/the-wonderful-101"
}
},
"place": {
"data": null
},
"version": {
"data": null
}
}
},
{
"id": "59",
"type": "game_aliases",
"attributes": {
"display_text": "Za Wandafuru Wan Ō Wan",
"kind": "title",
"writing_system": "Latin"
},
"relationships": {
"game": {
"data": {
"id": "46",
"type": "games"
},
"links": {
"related": "http://localhost:3000/articles/games/the-wonderful-101"
}
},
"place": {
"data": {
"id": "102",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/japan"
}
},
"version": {
"data": null
}
}
}
],
"links": {
"self": "http://localhost:3000/articles/games/the-wonderful-101/titles?page%5Bnumber%5D=1&page%5Bsize%5D=2",
"next": "http://localhost:3000/articles/games/the-wonderful-101/titles?page%5Bnumber%5D=2&page%5Bsize%5D=2",
"last": "http://localhost:3000/articles/games/the-wonderful-101/titles?page%5Bnumber%5D=2&page%5Bsize%5D=2"
},
"meta": {
"total_items": 3
}
}
Retrieve a collection of game aliases.
HTTP request
GET /articles/game_aliases
Success HTTP response code
200 OK
Get a single game alias
Response body |
HTTP 200
# GET /articles/game_aliases/58
{
"data": {
"id": "58",
"type": "game_aliases",
"attributes": {
"title": "Project P-100",
"kind": "working",
"writing_system": "Latin"
},
"relationships": {
"game": {
"data": {
"id": "46",
"type": "games"
},
"links": {
"related": "http://localhost:3000/articles/games/the-wonderful-101"
}
},
"place": {
"data": null,
"links": {
"related": "http://localhost:3000/places/bangladesh"
}
},
"version": {
"data": null,
"links": {
"related": "http://localhost:3000/articles/game_versions/2"
}
}
}
},
"included": [
{
"id": "46",
"type": "games",
"attributes": {
"display_title": "The Wonderful 101"
},
"links": {
"self": "http://localhost:3000/articles/games/the-wonderful-101"
}
}
],
"meta": {
"keywords": "project p-100, the wonderful 101, name, title, alias, dbljump, video games, pc games, gaming",
"description": "Project P-100 is an alternate name or title for The Wonderful 101. Learn more at Dbljump, the video game reference.",
"created_at": "2017-04-24T09:09:19.450Z",
"updated_at": "2017-04-24T09:09:19.450Z"
}
}
Retrieve a single game alias.
HTTP request
GET /articles/game_aliases/{id} (replace {id} with record ID)
Success HTTP response code
200 OK
Create a new game alias
Request body |
POST /articles/game_aliases
{
"data": {
"type": "game_aliases",
"attributes": {
"display_text": "New Title",
"kind": "title",
"writing_system": "Latin"
},
"relationships": {
"game": {
"data": {
"id": "47",
"type": "games"
}
},
"place": {
"data": {
"id": "17",
"type": "places"
}
},
"version": {
"data": {
"id": "2",
"type": "game_versions"
}
}
}
}
}
Response body |
HTTP 201
{
"data": {
"id": "62",
"type": "game_aliases",
"attributes": {
"display_text": "New Title",
"kind": "title",
"writing_system": "Latin"
},
"relationships": {
"game": {
"data": {
"id": "47",
"type": "games"
},
"links": {
"related": "http://localhost:3000/articles/games/dark-souls"
}
},
"place": {
"data": {
"id": "17",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/bangladesh"
}
},
"version": {
"data": {
"id": "2",
"type": "versions"
},
"links": {
"related": "http://localhost:3000/articles/game_versions/2"
}
}
}
},
"included": [
{
"id": "47",
"type": "games",
"attributes": {
"display_title": "Dark Souls"
},
"links": {
"self": "http://localhost:3000/articles/games/dark-souls"
}
},
{
"id": "17",
"type": "places",
"attributes": {
"name": "Bangladesh"
},
"links": {
"self": "http://localhost:3000/places/bangladesh"
}
}
],
"meta": {
"keywords": "new title, dark souls, bangladesh, name, title, alias, dbljump, video games, pc games, gaming",
"description": "New Title is an alternate name or title for Dark Souls. Learn more at Dbljump, the video game reference.",
"created_at": "2017-05-13T12:43:38.980Z",
"updated_at": "2017-05-13T12:43:38.980Z"
}
}
Create a new game alias record. User must be an editor or admin.
HTTP request
POST /articles/game_aliases
Success HTTP response code
201 Created
Update a game alias
Request body |
PATCH /articles/game_aliases/58
{
"data": {
"type": "game_aliases",
"id": "58",
"attributes": {
"title": "アップデート",
"kind": "title",
"writing_system": "Japanese"
},
"relationships": {
"place": {
"data": {
"id": "102",
"type": "places"
}
},
"version": {
"data": {
"id": "1",
"type": "game_versions"
}
}
}
}
}
Response body |
HTTP 200
{
"data": {
"id": "58",
"type": "game_aliases",
"attributes": {
"title": "アップデート",
"kind": "title",
"writing_system": "Japanese"
},
"relationships": {
"game": {
"data": {
"id": "46",
"type": "games"
},
"links": {
"related": "http://localhost:3000/articles/games/the-wonderful-101"
}
},
"place": {
"data": {
"id": "102",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/japan"
}
},
"version": {
"data": {
"id": "1",
"type": "versions"
},
"links": {
"related": "http://localhost:3000/articles/game_versions/1"
}
}
}
},
"included": [
{
"id": "46",
"type": "games",
"attributes": {
"display_title": "The Wonderful 101"
},
"links": {
"self": "http://localhost:3000/articles/games/the-wonderful-101"
}
},
{
"id": "102",
"type": "places",
"attributes": {
"name": "Japan"
},
"links": {
"self": "http://localhost:3000/places/japan"
}
}
],
"meta": {
"keywords": "アップデート, the wonderful 101, japan, name, title, alias, dbljump, video games, pc games, gaming",
"description": "アップデート is an alternate name or title for The Wonderful 101. Learn more at Dbljump, the video game reference.",
"created_at": "2017-04-24T09:09:19.450Z",
"updated_at": "2017-05-13T12:58:30.190Z"
}
}
Update an existing game alias. The user must be an editor or admin.
HTTP request
PATCH /articles/game_aliases/{id} (replace {id} with record ID)
Success HTTP response code
200 OK
Delete a game alias
Delete an existing game alias. User must be an editor or admin.
HTTP request
DELETE /articles/game_aliases/{id} (replace {id} with record ID)
Success HTTP response code
204 No Content
Errors
Errors specific to creating and updating game aliases.
| HTTP code | Error code | Pointer | Title |
|---|---|---|---|
| 400 | GAME_ALIAS_DISPLAY_TEXT_BLANK | title | Display text is required. |
| 400 | GAME_ALIAS_DISPLAY_TEXT_TOO_LONG | title | Display text cannot be more than 250 characters. |
| 400 | GAME_ALIAS_DISPLAY_TEXT_TAKEN | title | Display text must be unique to its parent company. |
| 400 | GAME_ALIAS_KIND_BLANK | kind | Kind is required. |
| 400 | GAME_ALIAS_KIND_INCLUSION | kind | Kind must be an accepted value. |
| 400 | GAME_ALIAS_WRITING_SYSTEM_BLANK | writing_system | Writing system is required. |
| 400 | GAME_ALIAS_WRITING_SYSTEM_INCLUSION | writing_system | Writing system must be an accepted value. |
| 400 | GAME_ALIAS_PLACE_ID_INVALID | data/relationships/place/data/id | Place ID must be a valid country or region ID. |
| 400 | GAME_ALIAS_VERSION_ID_INVALID | data/relationships/version/data/id | Version ID must belong to the parent game. |
Articles: Game Notes
Resources related to game notes. Notes are trivia, stories or facts about a game.
Request attributes
See Create a new game note and Update a game note.
Response attributes
Get all game notes
Response body |
HTTP 200
# GET /articles/game_notes?page[size]=2
{
"data": [
{
"id": "12",
"type": "game_notes",
"attributes": {
"category": "Development",
"body": "Was originally intended to feature an all-star cast of Nintendo characters.",
"cite_url": "https://www.unseen64.net/2014/10/24/wiiu-the-wonderful-101-beta-development",
"cite_title": "The Wonderful 101 [Beta / Concept – Wii U]",
"cite_website": "Unseen64"
},
"relationships": {
"game": {
"data": {
"id": "46",
"type": "games"
},
"links": {
"related": "http://localhost:3000/articles/games/the-wonderful-101"
}
},
"version": {
"data": null,
"links": {
"related": "http://localhost:3000/articles/game_versions/2"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/1"
}
}
}
}
],
"links": {},
"meta": {
"total_items": 1
}
}
Retrieve all game notes. Automatically paginated.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /articles/game_notes
URL query parameters
| Parameter | Default | Description |
|---|---|---|
| fields[{record-type}] | All fields | Return only specified fields, e.g. ?fields[game_notes]=body |
| filter[{field}] | All records | Filter search by field, e.g. ?filter[category]=Development |
| page[number] | 1 | Select the page number, e.g. ?page[number]=3 |
| page[size] | 30 | Select the number of records per page, e.g. ?page[size]=20 |
Success HTTP response code
200 OK
Get a single game note
Response body |
HTTP 200
# GET /articles/game_notes/12
{
"data": {
"id": "12",
"type": "game_notes",
"attributes": {
"category": "Development",
"body": "Was originally intended to feature an all-star cast of Nintendo characters.",
"cite_url": "https://www.unseen64.net/2014/10/24/wiiu-the-wonderful-101-beta-development",
"cite_title": "The Wonderful 101 [Beta / Concept – Wii U]",
"cite_website": "Unseen64"
},
"relationships": {
"game": {
"data": {
"id": "46",
"type": "games"
},
"links": {
"related": "http://localhost:3000/articles/games/the-wonderful-101"
}
},
"version": {
"data": null,
"links": {
"related": "http://localhost:3000/articles/game_versions/2"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/1"
}
}
}
},
"meta": {
"keywords": "the wonderful 101, notes, trivia, facts, dbljump, video games, pc games, gaming",
"description": "Was originally intended to feature an all-star cast of Nintendo characters.",
"created_at": "2017-05-17T21:40:11.512Z",
"updated_at": "2017-05-17T21:40:11.512Z"
}
}
Retrieve a single game note. Game notes are publicly available. No sign-in is required.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /articles/game_notes/{id} (replace {id} with record ID)
Success HTTP response code
200 OK
Response attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| category | string | Y | See Category. |
| body | string | Y | The note text. 5-2000 chars. |
| cite_url | string | The URL of the source web page. 5-250 chars. | |
| cite_title | string | The title of the source web page. 5-250 chars. | |
| cite_website | string | The name of the source website. 1-100 chars. |
Relationships
| Association | Record type | Relationship type |
|---|---|---|
| game | games | belongs_to |
| version | game_versions | belongs_to |
| created_by | users | belongs_to |
Meta
The meta section of the JSON response includes keywords, description, created_at and updated_at attributes.
Create a new game note
Request body |
POST /articles/game_notes
{
"data": {
"type": "game_notes",
"attributes": {
"category": "Development",
"body": "The note text.",
"cite_url": "http://ign.com/article",
"cite_title": "The Article Title",
"cite_website": "IGN"
},
"relationships": {
"game": {
"data": {
"id": "47",
"type": "games"
}
},
"version": {
"data": {
"id": "2",
"type": "game_versions"
}
}
}
}
}
Response body |
HTTP 201
{
"data": {
"id": "13",
"type": "game_notes",
"attributes": {
"category": "Development",
"body": "The note text.",
"cite_url": "http://ign.com/article",
"cite_title": "The Article Title",
"cite_website": "IGN"
},
"relationships": {
"game": {
"data": {
"id": "47",
"type": "games"
},
"links": {
"related": "http://localhost:3000/articles/games/dark-souls"
}
},
"version": {
"data": {
"id": "2",
"type": "versions"
},
"links": {
"related": "http://localhost:3000/articles/game_versions/2"
}
},
"created_by": {
"data": {
"id": "2",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/2"
}
}
}
},
"meta": {
"keywords": "dark souls, notes, trivia, facts, dbljump, video games, pc games, gaming",
"description": "The note text.",
"created_at": "2017-05-17T21:44:11.984Z",
"updated_at": "2017-05-17T21:44:11.984Z"
}
}
Create a new game note. A note is a fact, story or piece of trivia about a game. User must be an editor or admin.
- User authentication: required
- Authorization level: editor or admin
HTTP request
POST /articles/game_notes
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| category | string | Y | See Category. |
| body | string | Y | The note text. 5-2000 chars. |
| cite_url | string | The URL of the source web page. 5-250 chars. | |
| cite_title | string | The title of the source web page. 5-250 chars. | |
| cite_website | string | The name of the source website. 1-100 chars. |
Category
The category attribute accepts the following values.
| Value | Description |
|---|---|
| development | Notes related to the creation of the game software. |
| publishing | Notes related to publishing and release of the game. |
| tech | Notes related to the technologies used in the game, including graphics. |
| sound | Notes related to music and sound in the game. |
| game | Notes related to the game’s content and how it plays. |
| story | Notes related to the game’s story. |
| impact | Notes related to the game’s achievements and impact on the wider world. |
Relationships
Check this section’s code example to see how to update these relationships.
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| game | belongs_to | Y | games | The game the note belongs to. |
| version | belongs_to | game_versions | Version must belong to same game as note. |
Success HTTP response code
201 Created
Update a game note
Request body |
PATCH /articles/game_notes/12
{
"data": {
"id": "12",
"type": "game_notes",
"attributes": {
"category": "Development",
"body": "Updated note text.",
"cite_url": "http://ign.com/article",
"cite_title": "The Article Title",
"cite_website": "IGN"
},
"relationships": {
"game": {
"data": {
"id": "46",
"type": "games"
},
"links": {
"related": "http://localhost:3000/articles/games/the-wonderful-101"
}
},
"version": {
"data": {
"id": "1",
"type": "versions"
},
"links": {
"related": "http://localhost:3000/articles/game_versions/1"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/1"
}
}
}
},
"meta": {
"keywords": "the wonderful 101, notes, trivia, facts, dbljump, video games, pc games, gaming",
"description": "Updated note text.",
"created_at": "2017-05-17T21:40:11.512Z",
"updated_at": "2017-05-17T22:36:47.774Z"
}
}
Response body |
HTTP 200
{
"data": {
"id": "12",
"type": "game_notes",
"attributes": {
"category": "Development",
"body": "Updated note text.",
"cite_url": "http://ign.com/article",
"cite_title": "The Article Title",
"cite_website": "IGN"
},
"relationships": {
"game": {
"data": {
"id": "46",
"type": "games"
},
"links": {
"related": "http://localhost:3000/articles/games/the-wonderful-101"
}
},
"version": {
"data": {
"id": "1",
"type": "versions"
},
"links": {
"related": "http://localhost:3000/articles/game_versions/1"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/1"
}
}
}
},
"meta": {
"keywords": "the wonderful 101, notes, trivia, facts, dbljump, video games, pc games, gaming",
"description": "Updated note text.",
"created_at": "2017-05-17T21:40:11.512Z",
"updated_at": "2017-05-17T22:36:47.774Z"
}
}
Update an existing game note. The user must be an editor.
- User authentication: required
- Authorization level: admin
HTTP request
PATCH /articles/game_notes/{id} (replace {id} with record ID)
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| category | string | Y | See Category. |
| body | string | Y | The note text. 5-2000 chars. |
| cite_url | string | The URL of the source web page. 5-250 chars. | |
| cite_title | string | The title of the source web page. 5-250 chars. | |
| cite_website | string | The name of the source website. 1-100 chars. |
Relationships
Check this section’s code example to see how to update these relationships.
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| version | belongs_to | game_versions | Version must belong to same game as title. |
Success HTTP response code
200 OK
Delete a game note
Delete an existing game note. User must be an editor or admin.
- User authentication: required
- Authorization level: editor or admin
HTTP request
DELETE /articles/game_notes/{id} (replace {id} with record ID)
Success HTTP response code
204 No Content
Errors
Errors specific to creating and updating game notes.
| HTTP code | Error code | Pointer | Title |
|---|---|---|---|
| 400 | GAME_NOTE_VERSION_ID_INVALID | data/relationships/version/data/id | Version ID must belong to the parent game. |
| 400 | GAME_NOTE_CATEGORY_BLANK | category | Category is required. |
| 400 | GAME_NOTE_CATEGORY_INCLUSION | category | Category must be an accepted value. |
| 400 | GAME_NOTE_BODY_BLANK | body | Body is required. |
| 400 | GAME_NOTE_BODY_TOO_SHORT | body | Body cannot be less than 5 characters. |
| 400 | GAME_NOTE_BODY_TOO_LONG | body | Body cannot be more than 8000 characters. |
| 400 | GAME_NOTE_CITE_URL_TOO_SHORT | cite_url | Cite URL cannot be less than 5 characters. |
| 400 | GAME_NOTE_CITE_URL_TOO_LONG | cite_url | Cite URL cannot be more than 250 characters. |
| 400 | GAME_NOTE_CITE_TITLE_TOO_LONG | cite_title | Cite title cannot be more than 250 characters. |
| 400 | GAME_NOTE_CITE_WEBSITE_TOO_LONG | cite_website | Cite website cannot be more than 100 characters. |
Articles: People
Resources related to people articles.
Request attributes
See Create a new person and Update a person.
Response attributes
Get all people
Response body |
HTTP 200
# GET /articles/people?page[size]=3
{
"data": [
{
"id": "44",
"type": "people",
"attributes": {
"display_title": "Hideki Kamiya",
"description": "Hideki Kamiya is a game designer and director known for his work with Capcom and as a co-founder of PlatinumGames.",
"gender": "male",
"origin_date": "1970-12-19",
"origin_year": 1970,
"ended": null,
"end_date": null,
"end_year": null,
"slug": "hideki-kamiya"
},
"relationships": {
"origin_place": {
"data": {
"id": "2936",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/matsumoto-nagano-prefecture-japan"
}
},
"latest_place": {
"data": null
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/1"
}
}
},
"links": {
"self": "http://localhost:3000/articles/people/hideki-kamiya"
}
},
{
"id": "43",
"type": "people",
"attributes": {
"display_title": "Corrinne Yu",
"description": "Corrinne Yu is an American game programmer known for her work on the Halo series, with Sony development studio Naughty Dog, and with Amazon.",
"gender": "female",
"origin_date": null,
"origin_year": null,
"ended": null,
"end_date": null,
"end_year": null,
"slug": "corrinne-yu"
},
"relationships": {
"origin_place": {
"data": {
"id": "90",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/hong-kong"
}
},
"latest_place": {
"data": null
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/1"
}
}
},
"links": {
"self": "http://localhost:3000/articles/people/corrinne-yu"
}
},
{
"id": "42",
"type": "people",
"attributes": {
"display_title": "Tim Sweeney",
"description": "Tim Sweeney is an American game programmer and the founder of Epic Games. He is best known for his work on the Unreal Engine.",
"gender": "male",
"origin_date": null,
"origin_year": 1970,
"ended": null,
"end_date": null,
"end_year": null,
"slug": "tim-sweeney"
},
"relationships": {
"origin_place": {
"data": {
"id": "2890",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/potomac-maryland-united-states"
}
},
"latest_place": {
"data": null
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/1"
}
}
},
"links": {
"self": "http://localhost:3000/articles/people/tim-sweeney"
}
}
],
"links": {
"self": "http://localhost:3000/articles/people?page%5Bnumber%5D=1&page%5Bsize%5D=3",
"next": "http://localhost:3000/articles/people?page%5Bnumber%5D=2&page%5Bsize%5D=3",
"last": "http://localhost:3000/articles/people?page%5Bnumber%5D=8&page%5Bsize%5D=3"
},
"meta": {
"total_items": 24
}
}
Retrieve all people articles. Automatically paginated.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /articles/people
URL query parameters
| Parameter | Default | Description |
|---|---|---|
| fields[{record-type}] | All fields | Return only specified fields, e.g. ?fields[people]=display_title,description |
| filter[{field}] | All records | Filter search by field, e.g. ?filter[gender]=female |
| page[number] | 1 | Select the page number, e.g. ?page[number]=3 |
| page[size] | 30 | Select the number of records per page, e.g. ?page[size]=20 |
Success HTTP response code
200 OK
Get a single person
Response body |
HTTP 200
# GET /articles/people/hideki-kamiya
{
"data": {
"id": "44",
"type": "people",
"attributes": {
"display_title": "Hideki Kamiya",
"description": "Hideki Kamiya is a game designer and director known for his work with Capcom and as a co-founder of PlatinumGames.",
"slug": "hideki-kamiya",
"last_submitted_at": null,
"last_reviewed_at": null,
"last_review_outcome": null,
"last_review_comments": null,
"published_at": "2017-06-28T17:04:26.704Z",
"status": "published",
"gender": "male",
"origin_date": "1970-12-19",
"origin_year": 1970,
"ended": null,
"end_date": null,
"end_year": null
},
"relationships": {
"primary_image": {
"data": null,
"links": {
"related": "http://localhost:3000/media/images/nintendo-office-photo"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/1"
}
},
"last_reviewed_by": {
"data": null
},
"origin_place": {
"data": {
"id": "2936",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/matsumoto-nagano-prefecture-japan"
}
},
"latest_place": {
"data": null,
"links": {
"related": "http://localhost:3000/places/kyoto-kyoto-prefecture-japan"
}
},
"names": {
"data": [
{
"id": "57",
"type": "person_names"
}
],
"links": {
"related": "http://localhost:3000/articles/people/hideki-kamiya/names"
}
},
"notes": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/people/hideki-kamiya/notes"
}
},
"images": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/people/hideki-kamiya/images"
}
},
"credits": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/people/hideki-kamiya/credits"
}
}
},
"links": {
"self": "http://localhost:3000/articles/people/hideki-kamiya"
}
},
"included": [
{
"id": "1",
"type": "users",
"attributes": {
"username": "tikithekiwi",
"avatar": null
},
"links": {
"self": "http://localhost:3000/users/1"
}
},
{
"id": "2936",
"type": "places",
"attributes": {
"name": "Matsumoto",
"formatted": "Matsumoto, Nagano Prefecture, Japan"
},
"links": {
"self": "http://localhost:3000/places/matsumoto-nagano-prefecture-japan"
}
}
],
"meta": {
"keywords": "Hideki Kamiya, 1970, Matsumoto, Nagano Prefecture, Japan, person, profile, biography, games, dbljump, video games, pc games, gaming",
"description": "Find Hideki Kamiya's game credits, biography, images and facts at Dbljump, the video game reference.",
"created_at": "2017-06-28T17:04:26.729Z",
"updated_at": "2017-06-28T17:04:26.729Z"
}
}
Retrieve a single person article. People are publicly available. No sign-in is required.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /articles/people/{slug} (replace {slug} with record slug)
Success HTTP response code
200 OK
Response attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| display_title | string | Y | The article title, usually the person’s name. |
| description | text | A short biography up to 800 chars. | |
| gender | string | Must be ‘male’, 'female’, 'transman’ or 'transwoman’. | |
| origin_date | date | Between 1st Jan 1800 and the present. | |
| origin_year | integer | Between 1800 and the present year. | |
| ended | boolean | True if the person is dead. | |
| end_date | date | Between 1st Jan 1800 and the present. | |
| end_year | integer | Between 1800 and the present year. | |
| slug | string | Y | A record ID based on the display_title. |
Relationships
| Association | Record type | Relationship type |
|---|---|---|
| origin_place | places | belongs_to |
| latest_place | places | belongs_to |
| created_by | users | belongs_to |
| primary_image | images | belongs_to |
Meta
The meta section of the JSON response includes keywords, description, created_at and updated_at attributes.
Create a new person
Request body |
POST /articles/people
{
"data": {
"type": "people",
"attributes": {
"given_names": "New",
"family_name": "Person",
"description": "New Person is a new person, and this describes them.",
"gender": "female",
"origin_date": "1965-09-12",
"origin_year": "",
"ended": "",
"end_date": "2012-05-18",
"end_year": ""
},
"relationships": {
"primary_image": {
"data": {
"id": "1",
"type": "images"
}
},
"origin_place": {
"data": {
"id": "2883",
"type": "places"
}
},
"latest_place": {
"data": {
"id": "2932",
"type": "places"
}
}
}
}
}
Response body |
HTTP 201
{
"data": {
"id": "140",
"type": "people",
"attributes": {
"display_title": "New Person",
"description": "New Person is a new person, and this describes them.",
"slug": "new-person",
"last_submitted_at": null,
"last_reviewed_at": null,
"last_review_outcome": null,
"last_review_comments": null,
"published_at": null,
"status": "draft",
"gender": "female",
"origin_date": "1965-09-12",
"origin_year": 1965,
"ended": true,
"end_date": "2012-05-18",
"end_year": 2012
},
"relationships": {
"primary_image": {
"data": {
"id": "1",
"type": "images"
},
"links": {
"related": "http://localhost:3000/media/images/nintendo-office"
}
},
"created_by": {
"data": {
"id": "2",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/2"
}
},
"last_reviewed_by": {
"data": null
},
"origin_place": {
"data": {
"id": "2883",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/all-guernsey"
}
},
"latest_place": {
"data": {
"id": "2932",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/glasgow-scotland-united-kingdom"
}
},
"names": {
"data": [
{
"id": "191",
"type": "person_names"
}
],
"links": {
"related": "http://localhost:3000/articles/people/new-person/names"
}
},
"notes": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/people/new-person/notes"
}
},
"images": {
"data": [
{
"id": "1",
"type": "images"
}
],
"links": {
"related": "http://localhost:3000/articles/people/new-person/images"
}
},
"credits": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/people/new-person/credits"
}
}
},
"links": {
"self": "http://localhost:3000/articles/people/new-person"
},
"meta": {
"description": "Find New Person's game credits, biography, images and facts at Dbljump, the video game reference.",
"keywords": "New Person, 1965, All, Guernsey, New Person, person, profile, biography, games, dbljump, video games, pc games, gaming",
"created_at": "2017-08-03T09:18:15.694Z",
"updated_at": "2017-08-03T09:18:15.788Z"
}
},
"included": [
{
"id": "1",
"type": "images",
"attributes": {
"title": "Nintendo office"
},
"links": {
"self": "http://localhost:3000/media/images/nintendo-office"
},
"meta": {
"description": "'Nintendo office' is a video game image at Dbljump.",
"keywords": "Nintendo office, photo, 2006, 2006-02-18, Moja~commonswiki, image, picture, media, dbljump, video games, pc games, gaming",
"created_at": "2017-08-03T09:13:25.111Z",
"updated_at": "2017-08-03T09:13:25.111Z"
}
},
{
"id": "2",
"type": "users",
"attributes": {
"username": "neil",
"avatar": "http://localhost:3000/uploads/user_avatar/2/neil-1708031013.jpg"
},
"links": {
"self": "http://localhost:3000/users/2"
},
"meta": {
"description": "Neil Wheatley is a member at Dbljump, the video game reference.",
"keywords": "neil, Neil Wheatley, user, dbljump, video games, pc games, gaming",
"last_signed_in_at": null,
"last_sign_in_ip": null,
"sign_in_count": 0,
"activated_at": "2017-08-03T09:13:20.434Z",
"created_at": "2017-08-03T09:13:20.947Z",
"updated_at": "2017-08-03T09:13:20.947Z"
}
},
{
"id": "2883",
"type": "places",
"attributes": {
"name": "All",
"formatted": "All, Guernsey"
},
"links": {
"self": "http://localhost:3000/places/all-guernsey"
},
"meta": {
"description": "Find video game companies and games industry professionals from All, Guernsey at Dbljump.",
"keywords": "All, Guernsey, state, county, place, dbljump, video games, pc games, gaming",
"created_at": "2017-08-03T09:13:18.139Z",
"updated_at": "2017-08-03T09:13:18.139Z"
}
},
{
"id": "2932",
"type": "places",
"attributes": {
"name": "Glasgow",
"formatted": "Glasgow, Scotland, United Kingdom"
},
"links": {
"self": "http://localhost:3000/places/glasgow-scotland-united-kingdom"
},
"meta": {
"description": "Find video game companies and games industry professionals from Glasgow, Scotland, United Kingdom at Dbljump.",
"keywords": "Glasgow, Scotland, United Kingdom, city, town, place, dbljump, video games, pc games, gaming",
"created_at": "2017-08-03T09:13:19.411Z",
"updated_at": "2017-08-03T09:13:19.411Z"
}
}
]
}
Create a new person article. User must be an editor or admin.
- User authentication: required
- Authorization level: editor or admin
HTTP request
POST /articles/people
Request attributes
Note that the given_names and family_name attributes are only used for creating records. Their values are used to set display_title and sort_title.
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| given_names | string | Y | Max 50 characters. Only used when creating a record. |
| family_name | string | Max 50 characters. Only used when creating a record. | |
| description | text | 1-800 characters. | |
| gender | string | Must be ‘male’, 'female’, 'transman’ or 'transwoman’. | |
| origin_date | date | Between 1st Jan 1800 and the present. | |
| origin_year | integer | Between 1800 and the present year. | |
| ended | boolean | True if the person is dead. | |
| end_date | date | Between 1st Jan 1800 and the present. | |
| end_year | integer | Between 1800 and the present year. |
Relationships
Check this section’s code example to see how to update these relationships.
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| primary_image | belongs_to | images | The main article image, usually a game poster. | |
| origin_place | belongs_to | places | Can be a country, subdivision, or locality. | |
| latest_place | belongs_to | places | Can be a country, subdivision, or locality. |
Success HTTP response code
201 Created
Update a person
Request body |
PATCH /articles/people/hideki-kamiya
{
"data": {
"type": "people",
"id": "hideki-kamiya",
"attributes": {
"display_title": "Changed Name",
"description": "Updated description for an updated article.",
"gender": "transwoman",
"origin_date": "1960-09-12",
"origin_year": "",
"ended": "",
"end_date": "",
"end_year": "2015"
},
"relationships": {
"primary_image": {
"data": {
"id": "1",
"type": "images"
}
},
"origin_place": {
"data": {
"id": "25",
"type": "places"
}
},
"latest_place": {
"data": {
"id": "2933",
"type": "places"
}
}
}
}
}
Response body |
HTTP 200
{
"data": {
"id": "44",
"type": "people",
"attributes": {
"display_title": "Changed Name",
"description": "Updated description for an updated article.",
"slug": "changed-name-c7bbffd2-15e1-4008-98b3-96268e466d0f",
"last_submitted_at": null,
"last_reviewed_at": null,
"last_review_outcome": null,
"last_review_comments": null,
"published_at": "2017-06-28T17:04:26.704Z",
"status": "published",
"gender": "transwoman",
"origin_date": "1960-09-12",
"origin_year": 1960,
"ended": true,
"end_date": null,
"end_year": 2015
},
"relationships": {
"primary_image": {
"data": {
"id": "1",
"type": "images"
},
"links": {
"related": "http://localhost:3000/media/images/nintendo-office-photo"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/1"
}
},
"last_reviewed_by": {
"data": null
},
"origin_place": {
"data": {
"id": "25",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/bolivia"
}
},
"latest_place": {
"data": {
"id": "2933",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/sonobe-kyoto-prefecture-japan"
}
},
"names": {
"data": [
{
"id": "57",
"type": "person_names"
}
],
"links": {
"related": "http://localhost:3000/articles/people/changed-name-c7bbffd2-15e1-4008-98b3-96268e466d0f/names"
}
},
"notes": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/people/changed-name-c7bbffd2-15e1-4008-98b3-96268e466d0f/notes"
}
},
"images": {
"data": [
{
"id": "1",
"type": "images"
}
],
"links": {
"related": "http://localhost:3000/articles/people/changed-name-c7bbffd2-15e1-4008-98b3-96268e466d0f/images"
}
},
"credits": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/people/changed-name-c7bbffd2-15e1-4008-98b3-96268e466d0f/credits"
}
}
},
"links": {
"self": "http://localhost:3000/articles/people/changed-name-c7bbffd2-15e1-4008-98b3-96268e466d0f"
}
},
"included": [
{
"id": "1",
"type": "images",
"attributes": {
"file": "http://localhost:3000/uploads/images/1/nintendo-hq-kyoto-2006.jpg",
"title": "Nintendo office"
},
"links": {
"self": "http://localhost:3000/media/images/nintendo-office-photo"
}
},
{
"id": "1",
"type": "users",
"attributes": {
"username": "tikithekiwi",
"avatar": null
},
"links": {
"self": "http://localhost:3000/users/1"
}
},
{
"id": "25",
"type": "places",
"attributes": {
"name": "Bolivia",
"formatted": "Bolivia"
},
"links": {
"self": "http://localhost:3000/places/bolivia"
}
},
{
"id": "2933",
"type": "places",
"attributes": {
"name": "Sonobe",
"formatted": "Sonobe, Kyoto Prefecture, Japan"
},
"links": {
"self": "http://localhost:3000/places/sonobe-kyoto-prefecture-japan"
}
}
],
"meta": {
"keywords": "Changed Name, 1960, Bolivia, 神谷 英樹, person, profile, biography, games, dbljump, video games, pc games, gaming",
"description": "Find Changed Name's game credits, biography, images and facts at Dbljump, the video game reference.",
"created_at": "2017-06-28T17:04:26.729Z",
"updated_at": "2017-06-28T17:13:03.539Z"
}
}
Update an existing person article. The user must be an editor.
- User authentication: required
- Authorization level: admin
HTTP request
PATCH /articles/people/{slug} (replace {slug} with record slug)
Request attributes
Note that the display_title attribute can only be directly set when updating (not creating) a record.
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| display_title | string | Y | 1-250 characters. |
| description | text | 1-800 characters. | |
| gender | string | Must be ‘male’, 'female’, 'transman’ or 'transwoman’. | |
| origin_date | date | Between 1st Jan 1800 and the present. | |
| origin_year | integer | Between 1800 and the present year. | |
| ended | boolean | True if the person is dead. | |
| end_date | date | Between 1st Jan 1800 and the present. | |
| end_year | integer | Between 1800 and the present year. |
Relationships
Check this section’s code example to see how to update these relationships.
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| primary_image | belongs_to | images | The main article image, usually a likeness of the person. | |
| origin_place | belongs_to | places | Can be a country, subdivision, or locality. | |
| latest_place | belongs_to | places | Can be a country, subdivision, or locality. |
Success HTTP response code
200 OK
Delete a person
Delete an existing person article. User must be an editor or admin.
- User authentication: required
- Authorization level: editor or admin
HTTP request
DELETE /articles/people/{slug} (replace {slug} with record slug)
Success HTTP response code
204 No Content
Errors
Errors specific to creating person articles.
| HTTP code | Error code | Pointer | Title |
|---|---|---|---|
| 400 | PERSON_GIVEN_NAMES_BLANK | given_names | ‘Given names’ is required when creating a person record. |
| 400 | PERSON_GIVEN_NAMES_TOO_LONG | given_names | Given names cannot be more than 50 characters. |
| 400 | PERSON_FAMILY_NAME_TOO_LONG | family_name | Family name cannot be more than 50 characters. |
Errors specific to creating person articles.
| HTTP code | Error code | Pointer | Title |
|---|---|---|---|
| 400 | PERSON_DISPLAY_TITLE_BLANK | display_title | Display title is required. |
| 400 | PERSON_DISPLAY_TITLE_TOO_LONG | display_title | Display title cannot be more than 250 characters. |
Errors that apply to creating and updating person articles.
| HTTP code | Error code | Pointer | Title |
|---|---|---|---|
| 400 | PERSON_DESCRIPTION_TOO_LONG | description | Description cannot be more than 800 characters. |
| 400 | PERSON_GENDER_INCLUSION | gender | Gender must be 'male’, 'female’, 'transman’ or 'transwoman’. |
| 400 | PERSON_ORIGIN_DATE_INCLUSION | origin_date | Birth date must be a past date not before 1800. |
| 400 | PERSON_ORIGIN_YEAR_INCLUSION | origin_year | Birth year must be a past year not before 1800. |
| 400 | PERSON_END_DATE_INCLUSION | end_date | Death date must be a past date not before 1800. |
| 400 | PERSON_END_DATE_INVALID | end_date | Death date must not be eariler than birth date. |
| 400 | PERSON_END_YEAR_INCLUSION | end_year | Death year must be a past year not before 1800. |
| 400 | PERSON_END_YEAR_INVALID | end_year | Death year must not be eariler than birth year. |
Articles: Person Aliases
Resources related to person aliases. Aliases can include full names, nicknames and local names.
Get all person aliases
Response body |
HTTP 200
# GET /articles/person_aliases?page[size]=2
{
"data": [
{
"id": "41",
"type": "person_aliases",
"attributes": {
"display_text": "岩田 聡",
"given_names": "聡",
"family_name": "岩田",
"kind": "name",
"writing_system": "Japanese",
"year_adopted": null,
"dropped": null,
"year_dropped": null
},
"relationships": {
"person": {
"data": {
"id": "26",
"type": "people"
},
"links": {
"related": "http://localhost:3000/articles/people/satoru-iwata"
}
},
"place": {
"data": null
}
}
}
],
"links": {},
"meta": {
"total_items": 1
}
}
Retrieve all person aliases. Automatically paginated.
HTTP request
GET /articles/person_aliases
Success HTTP response code
200 OK
Get a single person alias
Response body |
HTTP 200
# GET /articles/person_aliases/41
{
"data": {
"id": "41",
"type": "person_aliases",
"attributes": {
"display_text": "岩田 聡",
"given_names": "聡",
"family_name": "岩田",
"kind": "name",
"writing_system": "Japanese",
"year_adopted": null,
"dropped": null,
"year_dropped": null
},
"relationships": {
"person": {
"data": {
"id": "26",
"type": "people"
},
"links": {
"related": "http://localhost:3000/articles/people/satoru-iwata"
}
},
"place": {
"data": null
}
}
},
"included": [
{
"id": "26",
"type": "people",
"attributes": {
"display_title": "Satoru Iwata"
},
"links": {
"self": "http://localhost:3000/articles/people/satoru-iwata"
}
}
],
"meta": {
"keywords": "岩田 聡, satoru iwata, name, title, alias, dbljump, video games, pc games, gaming",
"description": "岩田 聡 is an alternate name or title for Satoru Iwata. Learn more at Dbljump, the video game reference.",
"created_at": "2017-04-24T09:09:17.343Z",
"updated_at": "2017-04-24T09:09:17.343Z"
}
}
Retrieve a single person alias. Person aliases are publicly available. No sign-in is required.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /articles/person_aliases/{id} (replace {id} with record ID)
Success HTTP response code
200 OK
Response attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| display_text | string | Y | The alias. |
| given_names | string | Y | 1-50 characters. |
| family_name | string | 1-50 characters. | |
| kind | string | Y | The alias classification. Must be ‘name’, 'fullname’ or 'nickname’. |
| writing_system | string | Y | Must be an accepted value, e.g. 'Latin’, 'Japanese’ etc. |
| year_adopted | integer | Between 1800 and the present year. | |
| dropped | boolean | True if the alias has been dropped. Auto-sets true if year_dropped present. |
|
| year_dropped | integer | Between 1800 and the present year. |
Relationships
| Association | Record type | Relationship type |
|---|---|---|
| place | places | belongs_to |
| person | people | belongs_to |
Create a new person alias
Request body |
POST /articles/person_aliases
{
"data": {
"type": "person_aliases",
"attributes": {
"given_names": "Shiggy",
"family_name": "Shaboo",
"kind": "nickname",
"writing_system": "Latin",
"year_adopted": "1968",
"dropped": "",
"year_dropped": "1972"
},
"relationships": {
"person": {
"data": {
"id": "21",
"type": "people"
}
},
"place": {
"data": {
"id": "102",
"type": "places"
}
}
}
}
}
Response body |
HTTP 201
{
"data": {
"id": "63",
"type": "person_aliases",
"attributes": {
"display_text": "Shiggy Shaboo",
"given_names": "Shiggy",
"family_name": "Shaboo",
"kind": "nickname",
"writing_system": "Latin",
"year_adopted": 1968,
"dropped": true,
"year_dropped": 1972
},
"relationships": {
"person": {
"data": {
"id": "21",
"type": "people"
},
"links": {
"related": "http://localhost:3000/articles/people/shigeru-miyamoto"
}
},
"place": {
"data": {
"id": "102",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/japan"
}
}
}
},
"included": [
{
"id": "21",
"type": "people",
"attributes": {
"display_title": "Shigeru Miyamoto"
},
"links": {
"self": "http://localhost:3000/articles/people/shigeru-miyamoto"
}
},
{
"id": "102",
"type": "places",
"attributes": {
"name": "Japan"
},
"links": {
"self": "http://localhost:3000/places/japan"
}
}
],
"meta": {
"keywords": "shiggy shaboo, shigeru miyamoto, japan, name, title, alias, dbljump, video games, pc games, gaming",
"description": "Shiggy Shaboo is an alternate name or title for Shigeru Miyamoto. Learn more at Dbljump, the video game reference.",
"created_at": "2017-05-13T13:08:28.650Z",
"updated_at": "2017-05-13T13:08:28.650Z"
}
}
Create a new person alias record. User must be an editor or admin.
- User authentication: required
- Authorization level: editor or admin
HTTP request
POST /articles/person_aliases
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| given_names | string | Y | 1-50 characters. |
| family_name | string | 1-50 characters. | |
| kind | string | Y | The alias classification. Must be ‘name’, 'fullname’ or 'nickname’. |
| writing_system | string | Y | Must be an accepted value. |
| year_adopted | integer | Between 1800 and the present year. | |
| dropped | boolean | True if the alias has been dropped. Auto-sets true if year_dropped present. |
|
| year_dropped | integer | Between 1800 and the present year. |
Relationships
Check this section’s code example to see how to update these relationships.
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| person | belongs_to | Y | people | The person the alias belongs to. |
| place | belongs_to | places | Can be a country or region. |
Success HTTP response code
201 Created
Update a person alias
Request body |
PATCH /articles/person_aliases/41
{
"data": {
"type": "person_aliases",
"id": "41",
"attributes": {
"given_names": "アップデート",
"family_name": "カタカナ",
"kind": "fullname",
"writing_system": "Japanese",
"year_adopted": "1995",
"dropped": "true",
"year_dropped": ""
},
"relationships": {
"place": {
"data": {
"id": "102",
"type": "places"
}
}
}
}
}
Response body |
HTTP 200
{
"data": {
"id": "41",
"type": "person_aliases",
"attributes": {
"display_text": "カタカナ アップデート",
"given_names": "アップデート",
"family_name": "カタカナ",
"kind": "fullname",
"writing_system": "Japanese",
"year_adopted": 1995,
"dropped": true,
"year_dropped": null
},
"relationships": {
"person": {
"data": {
"id": "26",
"type": "people"
},
"links": {
"related": "http://localhost:3000/articles/people/satoru-iwata"
}
},
"place": {
"data": {
"id": "102",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/japan"
}
}
}
},
"included": [
{
"id": "26",
"type": "people",
"attributes": {
"display_title": "Satoru Iwata"
},
"links": {
"self": "http://localhost:3000/articles/people/satoru-iwata"
}
},
{
"id": "102",
"type": "places",
"attributes": {
"name": "Japan"
},
"links": {
"self": "http://localhost:3000/places/japan"
}
}
],
"meta": {
"keywords": "カタカナ アップデート, satoru iwata, japan, name, title, alias, dbljump, video games, pc games, gaming",
"description": "カタカナ アップデート is an alternate name or title for Satoru Iwata. Learn more at Dbljump, the video game reference.",
"created_at": "2017-04-24T09:09:17.343Z",
"updated_at": "2017-05-13T13:21:47.547Z"
}
}
Update an existing person alias. The user must be an editor.
- User authentication: required
- Authorization level: admin
HTTP request
PATCH /articles/person_aliases/{id} (replace {id} with record ID)
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| given_names | string | Y | 1-50 characters. |
| family_name | string | 1-50 characters. | |
| kind | string | Y | The alias classification. Must be ‘name’, 'fullname’ or 'nickname’. |
| writing_system | string | Y | Must be an accepted value. |
| year_adopted | integer | Between 1800 and the present year. | |
| dropped | boolean | True if the alias has been dropped. Auto-sets true if year_dropped present. |
|
| year_dropped | integer | Between 1800 and the present year. |
Relationships
Check this section’s code example to see how to update these relationships.
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| place | belongs_to | places | Can be a country or region. |
Success HTTP response code
200 OK
Delete a person alias
Delete an existing person alias. User must be an editor or admin.
HTTP request
DELETE /articles/person_aliases/{id} (replace {id} with record ID)
Success HTTP response code
204 No Content
Errors
Errors specific to creating and updating person aliases.
| HTTP code | Error code | Pointer | Title |
|---|---|---|---|
| 400 | PERSON_ALIAS_GIVEN_NAMES_BLANK | name | Given names is required. |
| 400 | PERSON_ALIAS_GIVEN_NAMES_TOO_LONG | name | Given names cannot be more than 50 characters. |
| 400 | PERSON_ALIAS_FAMILY_NAME_BLANK | name | Family name is required. |
| 400 | PERSON_ALIAS_FAMILY_NAME_TOO_LONG | name | Family name cannot be more than 50 characters. |
| 400 | PERSON_ALIAS_DISPLAY_TEXT_TAKEN | name | This person already has a name record with that given names and family name combination. |
| 400 | PERSON_ALIAS_KIND_BLANK | kind | Kind is required. |
| 400 | PERSON_ALIAS_KIND_INCLUSION | kind | Kind must be an accepted value. |
| 400 | PERSON_ALIAS_WRITING_SYSTEM_BLANK | writing_system | Writing system is required. |
| 400 | PERSON_ALIAS_WRITING_SYSTEM_INCLUSION | writing_system | Writing system must be an accepted value. |
| 400 | PERSON_ALIAS_YEAR_ADOPTED_INCLUSION | year_adopted | Year adopted must be a past year not before 1800. |
| 400 | PERSON_ALIAS_YEAR_DROPPED_INCLUSION | year_dropped | Year dropped must be a past year not before 1800. |
| 400 | PERSON_ALIAS_YEAR_DROPPED_INVALID | year_dropped | Year dropped must not be earlier than year adopted. |
| 400 | PERSON_ALIAS_PLACE_ID_INVALID | data/relationships/place/data/id | Place ID must be a valid country or region ID. |
Articles: Person Notes
Resources related to person notes. Notes are trivia, stories or facts about a person.
Request attributes
See Create a new person note and Update a person note.
Response attributes
Get all person titles
Response body |
HTTP 200
# GET /articles/person_notes?page[size]=2
{
"data": [
{
"id": "6",
"type": "person_notes",
"attributes": {
"category": "Education",
"body": "Studied industrial design at Kanazawa Municipal College of Industrial Arts.",
"cite_url": "",
"cite_title": "",
"cite_website": ""
},
"relationships": {
"person": {
"data": {
"id": "21",
"type": "people"
},
"links": {
"related": "http://localhost:3000/articles/people/shigeru-miyamoto"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/1"
}
}
}
}
],
"links": {},
"meta": {
"total_items": 1
}
}
Retrieve all person notes. Automatically paginated.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /articles/person_notes
URL query parameters
| Parameter | Default | Description |
|---|---|---|
| fields[{record-type}] | All fields | Return only specified fields, e.g. ?fields[person_notes]=body |
| filter[{field}] | All records | Filter search by field, e.g. ?filter[category]=Personal |
| page[number] | 1 | Select the page number, e.g. ?page[number]=3 |
| page[size] | 30 | Select the number of records per page, e.g. ?page[size]=20 |
Success HTTP response code
200 OK
Get a single person note
Response body |
HTTP 200
# GET /articles/person_notes/6
{
"data": {
"id": "6",
"type": "person_notes",
"attributes": {
"category": "Education",
"body": "Studied industrial design at Kanazawa Municipal College of Industrial Arts.",
"cite_url": "",
"cite_title": "",
"cite_website": ""
},
"relationships": {
"person": {
"data": {
"id": "21",
"type": "people"
},
"links": {
"related": "http://localhost:3000/articles/people/shigeru-miyamoto"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/1"
}
}
}
},
"meta": {
"keywords": "shigeru miyamoto, notes, trivia, facts, dbljump, video games, pc games, gaming",
"description": "Studied industrial design at Kanazawa Municipal College of Industrial Arts.",
"created_at": "2017-05-17T21:40:09.742Z",
"updated_at": "2017-05-17T21:40:09.742Z"
}
}
Retrieve a single person note. Game notes are publicly available. No sign-in is required.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /articles/person_notes/{id} (replace {id} with record ID)
Success HTTP response code
200 OK
Response attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| category | string | Y | See Category. |
| body | string | Y | The note text. 5-2000 chars. |
| cite_url | string | The URL of the source web page. 5-250 chars. | |
| cite_title | string | The title of the source web page. 5-250 chars. | |
| cite_website | string | The name of the source website. 1-100 chars. |
Relationships
| Association | Record type | Relationship type |
|---|---|---|
| person | people | belongs_to |
| created_by | users | belongs_to |
Meta
The meta section of the JSON response includes keywords, description, created_at and updated_at attributes.
Create a new person note
Request body |
POST /articles/person_notes
{
"data": {
"type": "person_notes",
"attributes": {
"category": "Career",
"body": "The note text.",
"cite_url": "http://ign.com/article",
"cite_title": "The Article Title",
"cite_website": "IGN"
},
"relationships": {
"person": {
"data": {
"id": "21",
"type": "people"
}
}
}
}
}
Response body |
HTTP 201
{
"data": {
"id": "15",
"type": "person_notes",
"attributes": {
"category": "Career",
"body": "The note text.",
"cite_url": "http://ign.com/article",
"cite_title": "The Article Title",
"cite_website": "IGN"
},
"relationships": {
"person": {
"data": {
"id": "21",
"type": "people"
},
"links": {
"related": "http://localhost:3000/articles/people/shigeru-miyamoto"
}
},
"created_by": {
"data": {
"id": "2",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/2"
}
}
}
},
"meta": {
"keywords": "shigeru miyamoto, notes, trivia, facts, dbljump, video games, pc games, gaming",
"description": "The note text.",
"created_at": "2017-05-18T22:09:16.930Z",
"updated_at": "2017-05-18T22:09:16.930Z"
}
}
Create a new person note record. A note is a fact, story or piece of trivia about a person. User must be an editor or admin.
- User authentication: required
- Authorization level: editor or admin
HTTP request
POST /articles/person_notes
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| category | string | Y | See Category. |
| body | string | Y | The note text. 5-2000 chars. |
| cite_url | string | The URL of the source web page. 5-250 chars. | |
| cite_title | string | The title of the source web page. 5-250 chars. | |
| cite_website | string | The name of the source website. 1-100 chars. |
Relationships
Check this section’s code example to see how to update these relationships.
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| person | belongs_to | Y | people | The person the note belongs to. |
Category
The category attribute accepts the following values.
| Value | Description |
|---|---|
| bio | Notes related to the person’s personal life or biography. |
| education | Notes related to the person’s education and academic achievements. |
| career | Notes related to the person’s professional life and achievements. |
| impact | Notes related to the person’s impact on the wider world. |
Success HTTP response code
201 Created
Update a person note
Request body |
PATCH /articles/person_notes/6
{
"data": {
"type": "person_notes",
"id": "6",
"attributes": {
"category": "Career",
"body": "The updated note text.",
"cite_url": "http://ign.com/updated",
"cite_title": "The Updated Title",
"cite_website": "IGN"
}
}
}
Response body |
HTTP 200
{
"data": {
"id": "6",
"type": "person_notes",
"attributes": {
"category": "Career",
"body": "The updated note text.",
"cite_url": "http://ign.com/updated",
"cite_title": "The Updated Title",
"cite_website": "IGN"
},
"relationships": {
"person": {
"data": {
"id": "21",
"type": "people"
},
"links": {
"related": "http://localhost:3000/articles/people/shigeru-miyamoto"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/1"
}
}
}
},
"meta": {
"keywords": "shigeru miyamoto, notes, trivia, facts, dbljump, video games, pc games, gaming",
"description": "The updated note text.",
"created_at": "2017-05-17T21:40:09.742Z",
"updated_at": "2017-05-18T22:15:04.883Z"
}
}
Update an existing person note. The user must be an editor.
- User authentication: required
- Authorization level: admin
HTTP request
PATCH /articles/person_notes/{id} (replace {id} with record ID)
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| category | string | Y | See Category. |
| body | string | Y | The note text. 5-2000 chars. |
| cite_url | string | The URL of the source web page. 5-250 chars. | |
| cite_title | string | The title of the source web page. 5-250 chars. | |
| cite_website | string | The name of the source website. 1-100 chars. |
Success HTTP response code
200 OK
Delete a person note
Delete an existing person note. User must be an editor or admin.
- User authentication: required
- Authorization level: editor or admin
HTTP request
DELETE /articles/person_notes/{id} (replace {id} with record ID)
Success HTTP response code
204 No Content
Errors
Errors specific to creating and updating person notes.
| HTTP code | Error code | Pointer | Title |
|---|---|---|---|
| 400 | PERSON_NOTE_CATEGORY_BLANK | category | Category is required. |
| 400 | PERSON_NOTE_CATEGORY_INCLUSION | category | Category must be an accepted value. |
| 400 | PERSON_NOTE_BODY_BLANK | body | Body is required. |
| 400 | PERSON_NOTE_BODY_TOO_SHORT | body | Body cannot be less than 5 characters. |
| 400 | PERSON_NOTE_BODY_TOO_LONG | body | Body cannot be more than 8000 characters. |
| 400 | PERSON_NOTE_CITE_URL_TOO_SHORT | cite_url | Cite URL cannot be less than 5 characters. |
| 400 | PERSON_NOTE_CITE_URL_TOO_LONG | cite_url | Cite URL cannot be more than 250 characters. |
| 400 | PERSON_NOTE_CITE_TITLE_TOO_LONG | cite_title | Cite title cannot be more than 250 characters. |
| 400 | PERSON_NOTE_CITE_WEBSITE_TOO_LONG | cite_website | Cite website cannot be more than 100 characters. |
Articles: Person Credits
Resources related to person credits.
Request attributes
See Create a new person credit and Update a person credit.
Response attributes
Get all person credits
Response body |
HTTP 200
# GET /articles/person_credits
{
"data": [
{
"id": "1",
"type": "person_credits",
"attributes": {
"category": "creative",
"role": "Executive Producer"
},
"relationships": {
"credited": {
"data": {
"id": "26",
"type": "people"
},
"links": {
"related": "http://localhost:3000/articles/people/satoru-iwata"
}
},
"game": {
"data": {
"id": "46",
"type": "games"
},
"links": {
"related": "http://localhost:3000/articles/games/the-wonderful-101"
}
},
"version": {
"data": {
"id": "1",
"type": "game_versions"
},
"links": {
"related": "http://localhost:3000/articles/game_versions/1"
}
},
"place": {
"data": null
}
}
}
],
"links": {},
"meta": {
"total_items": 1
}
}
Retrieve all person-game credits. Automatically paginated.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /articles/person_credits
URL query parameters
| Parameter | Default | Description |
|---|---|---|
| fields[{record-type}] | All fields | Return only specified fields, e.g. ?fields[person_credits]=role |
| filter[{field}] | All records | Filter search by field, e.g. ?filter[category]=creative |
| page[number] | 1 | Select the page number, e.g. ?page[number]=3 |
| page[size] | 30 | Select the number of records per page, e.g. ?page[size]=20 |
Success HTTP response code
200 OK
Get a single person credit
Response body |
HTTP 200
# GET /articles/person_credits/1
{
"data": {
"id": "1",
"type": "person_credits",
"attributes": {
"category": "special",
"role": "Special Thanks"
},
"relationships": {
"credited": {
"data": {
"id": "26",
"type": "people"
},
"links": {
"related": "http://localhost:3000/articles/people/satoru-iwata"
}
},
"game": {
"data": {
"id": "46",
"type": "games"
},
"links": {
"related": "http://localhost:3000/articles/games/the-wonderful-101"
}
},
"version": {
"data": {
"id": "1",
"type": "game_versions"
},
"links": {
"related": "http://localhost:3000/articles/game_versions/1"
}
},
"place": {
"data": {
"id": "55",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/czechia"
}
}
}
},
"included": [
{
"id": "26",
"type": "people",
"attributes": {
"display_title": "Satoru Iwata"
},
"links": {
"self": "http://localhost:3000/articles/people/satoru-iwata"
}
},
{
"id": "46",
"type": "games",
"attributes": {
"display_title": "The Wonderful 101"
},
"links": {
"self": "http://localhost:3000/articles/games/the-wonderful-101"
}
},
{
"id": "55",
"type": "places",
"attributes": {
"formatted": "Czechia"
},
"links": {
"self": "http://localhost:3000/places/czechia"
}
}
],
"meta": {
"keywords": "The Wonderful 101, Satoru Iwata, Special Thanks, Czechia, person, credit, dbljump, video games, pc games, gaming",
"description": "Find staff and company credits for The Wonderful 101 at Dbljump, the video game reference.",
"created_at": "2017-06-29T15:25:57.428Z",
"updated_at": "2017-06-29T15:42:21.047Z"
}
}
Retrieve a single person credit. Game credits are publicly available. No sign-in is required.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /articles/person_credits/{id} (replace {id} with record ID)
Success HTTP response code
200 OK
Response attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| category | string | Y | The credit category. |
| role | string | Y | The credit, e.g. ‘Director’ or 'Lead Programmer’. |
Relationships
| Association | Record type | Relationship type |
|---|---|---|
| credited | people | belongs_to |
| game | games | belongs_to |
| version | game_versions | belongs_to |
| place | places | belongs_to |
Meta
The meta section of the JSON response includes keywords, description, created_at and updated_at attributes.
Create a new person credit
Request body |
POST /articles/person_credits
{
"data": {
"type": "person_credits",
"attributes": {
"category": "creative",
"role": "Executive Producer"
},
"relationships": {
"credited": {
"data": {
"id": "26",
"type": "people"
}
},
"game": {
"data": {
"id": "46",
"type": "games"
}
},
"version": {
"data": {
"id": "1",
"type": "game_versions"
}
},
"place": {
"data": {
"id": "",
"type": "places"
}
}
}
}
}
Response body |
HTTP 201
{
"data": {
"id": "1",
"type": "person_credits",
"attributes": {
"category": "creative",
"role": "Executive Producer"
},
"relationships": {
"credited": {
"data": {
"id": "26",
"type": "people"
},
"links": {
"related": "http://localhost:3000/articles/people/satoru-iwata"
}
},
"game": {
"data": {
"id": "46",
"type": "games"
},
"links": {
"related": "http://localhost:3000/articles/games/the-wonderful-101"
}
},
"version": {
"data": {
"id": "1",
"type": "game_versions"
},
"links": {
"related": "http://localhost:3000/articles/game_versions/1"
}
},
"place": {
"data": null
}
}
},
"included": [
{
"id": "26",
"type": "people",
"attributes": {
"display_title": "Satoru Iwata"
},
"links": {
"self": "http://localhost:3000/articles/people/satoru-iwata"
}
},
{
"id": "46",
"type": "games",
"attributes": {
"display_title": "The Wonderful 101"
},
"links": {
"self": "http://localhost:3000/articles/games/the-wonderful-101"
}
}
],
"meta": {
"keywords": "The Wonderful 101, Satoru Iwata, Executive Producer, person, credit, dbljump, video games, pc games, gaming",
"description": "Find staff and company credits for The Wonderful 101 at Dbljump, the video game reference.",
"created_at": "2017-06-29T15:25:57.428Z",
"updated_at": "2017-06-29T15:25:57.428Z"
}
}
Create a new person-game credit. User must be an editor or admin.
- User authentication: required
- Authorization level: editor or admin
HTTP request
POST /articles/person_credits
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| category | string | Y | The credit category. Must be an accepted value. |
| role | string | Y | The credit, e.g. ‘Director’ or 'Lead Programmer’. Max 100 chars. |
Relationships
Check this section’s code example to see how to update these relationships.
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| credited | belongs_to | Y | people | The person credited. |
| game | belongs_to | Y | games | The game the credit relates to. |
| version | belongs_to | game_versions | The game version the credit relates to (optional). | |
| place | belongs_to | places | The place the credit relates to (optional). |
Person credit categories
The following are accepted value for the categories attribute:
- creative
- development
- technology
- visuals
- sound
- language
- special
- misc
Success HTTP response code
201 Created
Update a person credit
Request body |
PATCH /articles/person_credits/1
{
"data": {
"type": "person_credits",
"id": "1",
"attributes": {
"category": "special",
"role": "Special Thanks"
},
"relationships": {
"version": {
"data": {
"id": "1",
"type": "game_versions"
}
},
"place": {
"data": {
"id": "55",
"type": "places"
}
}
}
}
}
Response body |
HTTP 200
{
"data": {
"id": "1",
"type": "person_credits",
"attributes": {
"category": "special",
"role": "Special Thanks"
},
"relationships": {
"credited": {
"data": {
"id": "26",
"type": "people"
},
"links": {
"related": "http://localhost:3000/articles/people/satoru-iwata"
}
},
"game": {
"data": {
"id": "46",
"type": "games"
},
"links": {
"related": "http://localhost:3000/articles/games/the-wonderful-101"
}
},
"version": {
"data": {
"id": "1",
"type": "game_versions"
},
"links": {
"related": "http://localhost:3000/articles/game_versions/1"
}
},
"place": {
"data": {
"id": "55",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/czechia"
}
}
}
},
"included": [
{
"id": "26",
"type": "people",
"attributes": {
"display_title": "Satoru Iwata"
},
"links": {
"self": "http://localhost:3000/articles/people/satoru-iwata"
}
},
{
"id": "46",
"type": "games",
"attributes": {
"display_title": "The Wonderful 101"
},
"links": {
"self": "http://localhost:3000/articles/games/the-wonderful-101"
}
},
{
"id": "55",
"type": "places",
"attributes": {
"formatted": "Czechia"
},
"links": {
"self": "http://localhost:3000/places/czechia"
}
}
],
"meta": {
"keywords": "The Wonderful 101, Satoru Iwata, Special Thanks, Czechia, person, credit, dbljump, video games, pc games, gaming",
"description": "Find staff and company credits for The Wonderful 101 at Dbljump, the video game reference.",
"created_at": "2017-06-29T15:25:57.428Z",
"updated_at": "2017-06-29T15:42:21.047Z"
}
}
Update an existing person credit. The user must be an editor.
- User authentication: required
- Authorization level: admin
HTTP request
PATCH /articles/person_notes/{id} (replace {id} with record ID)
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| category | string | Y | The credit category. Must be an accepted value. |
| role | string | Y | The credit, e.g. ‘Director’ or 'Lead Programmer’. |
Relationships
Check this section’s code example to see how to update these relationships.
NOTE - The game and credited relationships cannot be updated.
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| version | belongs_to | game_versions | The game version the credit relates to (optional). | |
| place | belongs_to | places | The place the credit relates to (optional). |
Person credit categories
The following are accepted value for the categories attribute:
- creative
- development
- technology
- visuals
- sound
- language
- special
- misc
Success HTTP response code
200 OK
Delete a person credit
Delete an existing person credit. User must be an editor or admin.
- User authentication: required
- Authorization level: editor or admin
HTTP request
DELETE /articles/person_credits/{id} (replace {id} with record ID)
Success HTTP response code
204 No Content
Errors
Errors specific to creating and updating person credits.
| HTTP code | Error code | Pointer | Title |
|---|---|---|---|
| 400 | PERSON_CREDIT_CREDITED_ID_BLANK | data/relationships/credited/data/id | Credited is required. |
| 400 | PERSON_CREDIT_GAME_ID_BLANK | data/relationships/game/data/id | Game is required. |
| 400 | PERSON_CREDIT_VERSION_ID_INVALID | data/relationships/version/data/id | Version ID must be a version of credit game. |
| 400 | PERSON_CREDIT_PLACE_ID_INVALID | data/relationships/place/data/id | Place ID must be a valid country or region ID. |
| 400 | PERSON_CREDIT_ROLE_BLANK | role | Role is required. |
| 400 | PERSON_CREDIT_ROLE_TOO_LONG | role | Role cannot be more than 100 characters. |
| 400 | PERSON_CREDIT_CATEGORY_BLANK | category | Category is required. |
| 400 | PERSON_CREDIT_CATEGORY_INCLUSION | category | Category must be an accepted value. |
Articles: Companies
Resources related to company articles.
Request attributes
See Create a new company and Update a company.
Response attributes
Get all companies
Response body |
HTTP 200
# GET /articles/companies?page[size]=2
{
"data": [
{
"id": "1",
"type": "companies",
"attributes": {
"display_title": "Amstrad",
"sort_title": "Amstrad",
"slug": "amstrad",
"description": "Amstrad is a British electronics company best known within gaming as creator of the Amstrad 464 and CPC home computers of the 1980s.",
"last_review_outcome": null,
"last_review_comments": null,
"origin_date": null,
"origin_year": 1968,
"ended": null,
"end_date": null,
"end_year": null
},
"relationships": {
"primary_image": {
"data": null,
"links": {
"related": "http://localhost:3000/media/images/23"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/1"
}
},
"last_reviewed_by": {
"data": null
},
"origin_place": {
"data": {
"id": "1031",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/1031"
}
},
"latest_place": {
"data": null,
"links": {
"related": "http://localhost:3000/places/2937"
}
},
"names": {
"data": [
{
"id": "1",
"type": "company_names"
}
],
"links": {
"related": "http://localhost:3000/articles/companies/1/names"
},
"meta": {
"total": 1
}
},
"notes": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/companies/1/notes"
},
"meta": {
"total": 0
}
},
"images": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/companies/1/images"
},
"meta": {
"total": 0
}
},
"credits": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/companies/1/credits"
},
"meta": {
"total": 0
}
},
"parents": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/companies/1/parents"
},
"meta": {
"total": 0
}
},
"children": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/companies/1/children"
},
"meta": {
"total": 0
}
},
"platforms": {
"data": [
{
"id": "1",
"type": "platforms"
},
{
"id": "2",
"type": "platforms"
}
],
"links": {
"related": "http://localhost:3000/platforms?filter%5Bholder_id%5D=1"
},
"meta": {
"total": 2
}
}
},
"links": {
"self": "http://localhost:3000/articles/companies/1"
},
"meta": {
"created_at": "2017-08-25T08:32:15.415Z",
"updated_at": "2017-08-25T08:32:15.415Z",
"meta_description": "Find Amstrad's game credits, profile, images and facts at Dbljump, the video game reference.",
"meta_keywords": "Amstrad, 1968, London, United Kingdom, company, profile, biography, trivia, dbljump, video games, pc games, gaming",
"status": "published",
"last_submitted_at": null,
"last_reviewed_at": null,
"published_at": "2017-08-25T08:32:15.329Z",
"total_names": 1,
"total_notes": 0,
"total_images": 0,
"total_credits": 0,
"total_parents": 0,
"total_children": 0
}
},
{
"id": "2",
"type": "companies",
"attributes": {
"display_title": "Sinclair Research Ltd",
"sort_title": "Sinclair Research Ltd",
"slug": "sinclair-research-ltd",
"description": "Sinclair Research is a British electronics company best known within gaming as creator of the ZX Spectrum series of home computers.",
"last_review_outcome": null,
"last_review_comments": null,
"origin_date": null,
"origin_year": 1973,
"ended": null,
"end_date": null,
"end_year": null
},
"relationships": {
"primary_image": {
"data": null,
"links": {
"related": "http://localhost:3000/media/images/23"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/1"
}
},
"last_reviewed_by": {
"data": null
},
"origin_place": {
"data": {
"id": "2925",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/2925"
}
},
"latest_place": {
"data": {
"id": "1031",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/1031"
}
},
"names": {
"data": [
{
"id": "2",
"type": "company_names"
}
],
"links": {
"related": "http://localhost:3000/articles/companies/2/names"
},
"meta": {
"total": 1
}
},
"notes": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/companies/2/notes"
},
"meta": {
"total": 0
}
},
"images": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/companies/2/images"
},
"meta": {
"total": 0
}
},
"credits": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/companies/2/credits"
},
"meta": {
"total": 0
}
},
"parents": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/companies/2/parents"
},
"meta": {
"total": 0
}
},
"children": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/companies/2/children"
},
"meta": {
"total": 0
}
},
"platforms": {
"data": [
{
"id": "3",
"type": "platforms"
}
],
"links": {
"related": "http://localhost:3000/platforms?filter%5Bholder_id%5D=2"
},
"meta": {
"total": 1
}
}
},
"links": {
"self": "http://localhost:3000/articles/companies/2"
},
"meta": {
"created_at": "2017-08-25T08:32:15.514Z",
"updated_at": "2017-08-25T08:32:15.514Z",
"meta_description": "Find Sinclair Research Ltd's game credits, profile, images and facts at Dbljump, the video game reference.",
"meta_keywords": "Sinclair Research Ltd, 1973, Cambridge, East of England, United Kingdom, London, United Kingdom, company, profile, biography, trivia, dbljump, video games, pc games, gaming",
"status": "published",
"last_submitted_at": null,
"last_reviewed_at": null,
"published_at": "2017-08-25T08:32:15.460Z",
"total_names": 1,
"total_notes": 0,
"total_images": 0,
"total_credits": 0,
"total_parents": 0,
"total_children": 0
}
}
],
"links": {
"self": "http://localhost:3000/articles/companies?page%5Bnumber%5D=1&page%5Bsize%5D=2",
"next": "http://localhost:3000/articles/companies?page%5Bnumber%5D=2&page%5Bsize%5D=2",
"last": "http://localhost:3000/articles/companies?page%5Bnumber%5D=26&page%5Bsize%5D=2"
},
"meta": {
"total_items": 52
}
Retrieve all company articles. Automatically paginated.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /articles/companies
URL query parameters
| Parameter | Default | Description |
|---|---|---|
| fields[{record-type}] | All fields | Return only specified fields, e.g. ?fields[companies]=display_title,description |
| filter[{field}] | All records | Filter search by field, e.g. ?filter[end]=true |
| page[number] | 1 | Select the page number, e.g. ?page[number]=3 |
| page[size] | 30 | Select the number of records per page, e.g. ?page[size]=20 |
Success HTTP response code
200 OK
Get a single company
Response body |
HTTP 200
# GET /articles/companies/nintendo-co-ltd
{
"data": {
"id": "8",
"type": "companies",
"attributes": {
"display_title": "Nintendo Co., Ltd.",
"sort_title": "Nintendo Co., Ltd.",
"slug": "nintendo-co-ltd",
"description": "Nintendo is a Japanese video game hardware and software company founded in 1889.",
"last_review_outcome": null,
"last_review_comments": null,
"origin_date": null,
"origin_year": 1889,
"ended": null,
"end_date": null,
"end_year": null
},
"relationships": {
"primary_image": {
"data": {
"id": "17",
"type": "images"
},
"links": {
"related": "http://localhost:3000/media/images/17"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/1"
}
},
"last_reviewed_by": {
"data": null
},
"origin_place": {
"data": {
"id": "2964",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/2964"
}
},
"latest_place": {
"data": null
},
"names": {
"data": [
{
"id": "8",
"type": "company_names"
},
{
"id": "53",
"type": "company_names"
},
{
"id": "54",
"type": "company_names"
},
{
"id": "55",
"type": "company_names"
},
{
"id": "56",
"type": "company_names"
}
],
"links": {
"related": "http://localhost:3000/articles/companies/8/names"
},
"meta": {
"total": 5
}
},
"notes": {
"data": [
{
"id": "1",
"type": "company_notes"
},
{
"id": "2",
"type": "company_notes"
}
],
"links": {
"related": "http://localhost:3000/articles/companies/8/notes"
},
"meta": {
"total": 2
}
},
"images": {
"data": [
{
"id": "1",
"type": "images"
},
{
"id": "2",
"type": "images"
},
{
"id": "3",
"type": "images"
},
{
"id": "4",
"type": "images"
},
{
"id": "5",
"type": "images"
},
{
"id": "17",
"type": "images"
}
],
"links": {
"related": "http://localhost:3000/articles/companies/8/images"
},
"meta": {
"total": 6
}
},
"credits": {
"data": [
{
"id": "11",
"type": "company_credits"
},
{
"id": "33",
"type": "company_credits"
},
{
"id": "35",
"type": "company_credits"
},
{
"id": "39",
"type": "company_credits"
}
],
"links": {
"related": "http://localhost:3000/articles/companies/8/credits"
},
"meta": {
"total": 4
}
},
"parents": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/companies/8/parents"
},
"meta": {
"total": 0
}
},
"children": {
"data": [
{
"id": "12",
"type": "company_kinships"
},
{
"id": "28",
"type": "company_kinships"
},
{
"id": "29",
"type": "company_kinships"
}
],
"links": {
"related": "http://localhost:3000/articles/companies/8/children"
},
"meta": {
"total": 3
}
},
"platforms": {
"data": [
{
"id": "24",
"type": "platforms"
},
{
"id": "25",
"type": "platforms"
},
{
"id": "26",
"type": "platforms"
},
{
"id": "27",
"type": "platforms"
},
{
"id": "28",
"type": "platforms"
},
{
"id": "29",
"type": "platforms"
},
{
"id": "30",
"type": "platforms"
},
{
"id": "31",
"type": "platforms"
},
{
"id": "32",
"type": "platforms"
},
{
"id": "33",
"type": "platforms"
},
{
"id": "34",
"type": "platforms"
},
{
"id": "35",
"type": "platforms"
},
{
"id": "36",
"type": "platforms"
},
{
"id": "37",
"type": "platforms"
},
{
"id": "38",
"type": "platforms"
},
{
"id": "39",
"type": "platforms"
}
],
"links": {
"related": "http://localhost:3000/platforms?filter%5Bholder_id%5D=8"
},
"meta": {
"total": 16
}
}
},
"links": {
"self": "http://localhost:3000/articles/companies/8"
},
"meta": {
"created_at": "2017-08-25T08:32:15.829Z",
"updated_at": "2017-08-25T08:32:31.459Z",
"meta_description": "Find Nintendo Co., Ltd.'s game credits, profile, images and facts at Dbljump, the video game reference.",
"meta_keywords": "Nintendo Co., Ltd., 1889, Kyoto, Kyoto Prefecture, Japan, Nintendo, 任天堂株式会社, Nintendō Kabushiki gaisha, Nintendo Playing Card Co., Nintendo Koppai, company, profile, biography, trivia, dbljump, video games, pc games, gaming",
"status": "published",
"last_submitted_at": null,
"last_reviewed_at": null,
"published_at": "2017-08-25T08:32:15.798Z",
"total_names": 5,
"total_notes": 2,
"total_images": 6,
"total_credits": 4,
"total_parents": 0,
"total_children": 3
}
}
}
Retrieve a single company article. Companies are publicly available. No sign-in is required.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /articles/companies/{slug} (replace {slug} with record slug)
Success HTTP response code
200 OK
Response attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| display_title | string | Y | The article title, usually the company name. |
| description | text | A short biography up to 800 chars. | |
| origin_date | date | Between 1st Jan 1800 and the present. | |
| origin_year | integer | Between 1800 and the present year. | |
| end | boolean | True if the company has end. | |
| end_date | date | Between 1st Jan 1800 and the present. | |
| end_year | integer | Between 1800 and the present year. | |
| slug | string | Y | A record ID based on the display_title. |
Relationships
| Association | Record type | Relationship type |
|---|---|---|
| origin_place | places | belongs_to |
| latest_place | places | belongs_to |
| created_by | users | belongs_to |
| primary_image | images | belongs_to |
| platforms | platforms | has_many |
Meta
The meta section of the JSON response includes keywords, description, created_at and updated_at attributes.
Create a new company
Request body |
POST /articles/companies
{
"data": {
"type": "companies",
"attributes": {
"display_title": "New Firm",
"description": "New Firm is a new company, and this describes it.",
"origin_date": "1965-09-12",
"origin_year": "",
"end": "",
"end_date": "2012-05-18",
"end_year": ""
},
"relationships": {
"primary_image": {
"data": {
"id": "1",
"type": "images"
}
},
"origin_place": {
"data": {
"id": "2883",
"type": "places"
}
},
"latest_place": {
"data": {
"id": "2932",
"type": "places"
}
}
}
}
}
Response body |
HTTP 201
{
"data": {
"id": "49",
"type": "companies",
"attributes": {
"display_title": "New Firm",
"description": "New Firm is a new company, and this describes it.",
"slug": "new-firm",
"last_submitted_at": null,
"last_reviewed_at": null,
"last_review_outcome": null,
"last_review_comments": null,
"published_at": null,
"status": "draft",
"origin_date": "1965-09-12",
"origin_year": 1965,
"end": true,
"end_date": "2012-05-18",
"end_year": 2012
},
"relationships": {
"primary_image": {
"data": {
"id": "1",
"type": "images"
},
"links": {
"related": "http://localhost:3000/media/images/nintendo-office-photo"
}
},
"created_by": {
"data": {
"id": "2",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/2"
}
},
"last_reviewed_by": {
"data": null
},
"origin_place": {
"data": {
"id": "2883",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/los-angeles-california-united-states"
}
},
"latest_place": {
"data": {
"id": "2932",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/kyoto-kyoto-prefecture-japan"
}
},
"names": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/companies/new-firm/names"
}
},
"notes": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/companies/new-firm/notes"
}
},
"images": {
"data": [
{
"id": "1",
"type": "images"
}
],
"links": {
"related": "http://localhost:3000/articles/companies/new-firm/images"
}
},
"credits": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/companies/new-firm/credits"
}
},
"parents": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/companies/new-firm/parents"
}
},
"children": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/companies/new-firm/children"
}
}
},
"links": {
"self": "http://localhost:3000/articles/companies/new-firm"
}
},
"included": [
{
"id": "1",
"type": "images",
"attributes": {
"file": "http://localhost:3000/uploads/images/1/nintendo-hq-kyoto-2006.jpg",
"title": "Nintendo office"
},
"links": {
"self": "http://localhost:3000/media/images/nintendo-office-photo"
}
},
{
"id": "2",
"type": "users",
"attributes": {
"username": "neil",
"avatar": "http://localhost:3000/uploads/user_avatar/2/1706221451.jpg"
},
"links": {
"self": "http://localhost:3000/users/2"
}
},
{
"id": "2883",
"type": "places",
"attributes": {
"name": "Los Angeles",
"formatted": "Los Angeles, California, United States"
},
"links": {
"self": "http://localhost:3000/places/los-angeles-california-united-states"
}
},
{
"id": "2932",
"type": "places",
"attributes": {
"name": "Kyoto",
"formatted": "Kyoto, Kyoto Prefecture, Japan"
},
"links": {
"self": "http://localhost:3000/places/kyoto-kyoto-prefecture-japan"
}
}
],
"meta": {
"keywords": "New Firm, 1965, Los Angeles, California, United States, Kyoto, Kyoto Prefecture, Japan, company, profile, biography, trivia, dbljump, video games, pc games, gaming",
"description": "Find New Firm's game credits, profile, images and facts at Dbljump, the video game reference.",
"created_at": "2017-06-27T22:28:07.651Z",
"updated_at": "2017-06-27T22:28:07.651Z"
}
}
Create a new company article. User must be an editor or admin.
- User authentication: required
- Authorization level: editor or admin
HTTP request
POST /articles/companies
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| display_title | string | Y | 1-250 characters. |
| description | text | 1-800 characters. | |
| origin_date | date | Between 1st Jan 1800 and the present. | |
| origin_year | integer | Between 1800 and the present year. | |
| end | boolean | True if the company has end. | |
| end_date | date | Between 1st Jan 1800 and the present. | |
| end_year | integer | Between 1800 and the present year. |
Relationships
Check this section’s code example to see how to update these relationships.
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| origin_place | belongs_to | places | Can be a country, subdivision, or locality. | |
| latest_place | belongs_to | places | Can be a country, subdivision, or locality. | |
| primary_image | belongs_to | images | The main article image, usually the company logo. |
Success HTTP response code
201 Created
Update a company
Request body |
PATCH /articles/companies/microsoft-corporation
{
"data": {
"type": "companies",
"id": "microsoft-corporation",
"attributes": {
"display_title": "Changed Name",
"description": "Updated description for an updated article.",
"origin_date": "1940-09-12",
"origin_year": "",
"ended": "",
"end_date": "2013-04-05",
"end_year": ""
},
"relationships": {
"primary_image": {
"data": {
"id": "1",
"type": "images"
}
},
"origin_place": {
"data": {
"id": "25",
"type": "places"
}
},
"latest_place": {
"data": {
"id": "2933",
"type": "places"
}
}
}
}
}
Response body |
HTTP 200
{
"data": {
"id": "4",
"type": "companies",
"attributes": {
"display_title": "Changed Name",
"description": "Updated description for an updated article.",
"slug": "changed-name",
"last_submitted_at": null,
"last_reviewed_at": null,
"last_review_outcome": null,
"last_review_comments": null,
"published_at": "2017-06-28T17:04:18.271Z",
"status": "published",
"origin_date": "1940-09-12",
"origin_year": 1940,
"end": true,
"end_date": "2013-04-05",
"end_year": 2013
},
"relationships": {
"primary_image": {
"data": {
"id": "1",
"type": "images"
},
"links": {
"related": "http://localhost:3000/media/images/nintendo-office-photo"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/1"
}
},
"last_reviewed_by": {
"data": null
},
"origin_place": {
"data": {
"id": "25",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/bolivia"
}
},
"latest_place": {
"data": {
"id": "2933",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/sonobe-kyoto-prefecture-japan"
}
},
"names": {
"data": [
{
"id": "12",
"type": "company_names"
},
{
"id": "13",
"type": "company_names"
}
],
"links": {
"related": "http://localhost:3000/articles/companies/changed-name/names"
}
},
"notes": {
"data": [
{
"id": "5",
"type": "company_notes"
}
],
"links": {
"related": "http://localhost:3000/articles/companies/changed-name/notes"
}
},
"images": {
"data": [
{
"id": "1",
"type": "images"
}
],
"links": {
"related": "http://localhost:3000/articles/companies/changed-name/images"
}
},
"credits": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/companies/changed-name/credits"
}
},
"parents": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/companies/changed-name/parents"
}
},
"children": {
"data": [
{
"id": "17",
"type": "company_kinships"
}
],
"links": {
"related": "http://localhost:3000/articles/companies/changed-name/children"
}
}
},
"links": {
"self": "http://localhost:3000/articles/companies/changed-name"
}
},
"included": [
{
"id": "1",
"type": "images",
"attributes": {
"file": "http://localhost:3000/uploads/images/1/nintendo-hq-kyoto-2006.jpg",
"title": "Nintendo office"
},
"links": {
"self": "http://localhost:3000/media/images/nintendo-office-photo"
}
},
{
"id": "1",
"type": "users",
"attributes": {
"username": "tikithekiwi",
"avatar": null
},
"links": {
"self": "http://localhost:3000/users/1"
}
},
{
"id": "25",
"type": "places",
"attributes": {
"name": "Bolivia",
"formatted": "Bolivia"
},
"links": {
"self": "http://localhost:3000/places/bolivia"
}
},
{
"id": "2933",
"type": "places",
"attributes": {
"name": "Sonobe",
"formatted": "Sonobe, Kyoto Prefecture, Japan"
},
"links": {
"self": "http://localhost:3000/places/sonobe-kyoto-prefecture-japan"
}
}
],
"meta": {
"keywords": "Changed Name, 1940, Bolivia, Sonobe, Kyoto Prefecture, Japan, MS, Microsoft, company, profile, biography, trivia, dbljump, video games, pc games, gaming",
"description": "Find Changed Name's game credits, profile, images and facts at Dbljump, the video game reference.",
"created_at": "2017-06-28T17:04:18.295Z",
"updated_at": "2017-06-28T17:05:53.641Z"
}
}
Update an existing company article. The user must be an editor.
- User authentication: required
- Authorization level: admin
HTTP request
PATCH /articles/companies/{slug} (replace {slug} with record slug)
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| display_title | string | Y | 1-250 characters. |
| description | text | 1-800 characters. | |
| origin_date | date | Between 1st Jan 1800 and the present. | |
| origin_year | integer | Between 1800 and the present year. | |
| end | boolean | True if the company has end. | |
| end_date | date | Between 1st Jan 1800 and the present. | |
| end_year | integer | Between 1800 and the present year. |
Relationships
Check this section’s code example to see how to update these relationships.
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| primary_image | belongs_to | images | The main article image, usually a company logo. | |
| origin_place | belongs_to | places | Can be a country, subdivision, or locality. | |
| latest_place | belongs_to | places | Can be a country, subdivision, or locality. | |
| platforms | has_many | platforms | Gaming platforms this company holds. |
Success HTTP response code
200 OK
Delete a company
Delete an existing company article. User must be an editor or admin.
- User authentication: required
- Authorization level: editor or admin
HTTP request
DELETE /articles/companies/{slug} (replace {slug} with record slug)
Success HTTP response code
204 No Content
Errors
Errors specific to creating and updating company articles.
| HTTP code | Error code | Pointer | Title |
|---|---|---|---|
| 400 | COMPANY_DISPLAY_TITLE_BLANK | display_title | Display title is required. |
| 400 | COMPANY_DISPLAY_TITLE_TOO_LONG | display_title | Display title cannot be more than 250 characters. |
| 400 | COMPANY_DESCRIPTION_TOO_LONG | description | Description cannot be more than 800 characters. |
| 400 | COMPANY_ORIGIN_DATE_INCLUSION | origin_date | Founded date must be a past date not before 1800. |
| 400 | COMPANY_ORIGIN_YEAR_INCLUSION | origin_year | Founded year must be a past year not before 1800. |
| 400 | COMPANY_END_DATE_INCLUSION | end_date | Closed date must be a past date not before 1800. |
| 400 | COMPANY_END_DATE_INVALID | end_date | Closed date must not be eariler than founded date. |
| 400 | COMPANY_END_YEAR_INCLUSION | end_year | Closed year must be a past year not before 1800. |
| 400 | COMPANY_END_YEAR_INVALID | end_year | Closed year must not be eariler than founded year. |
Articles: Company Aliases
Resources related to company aliases. An alias is another name the company is known by. The JSON:API type is company_aliases.
Mutable attributes
display_text (string, required)
The alias. 1-100 chars.
kind (string, required)
Name classification. Must be name, styled or AKA.
writing_system (string, required)
Must be Latin, Japanese, Cyrillic, Chinese or Arabic.
year_adopted (integer)
Must be between 1800 and the present year.
dropped (boolean)
true if the alias is no longer used. Auto-set to true if year_dropped is present.
year_dropped (integer)
Must be between 1800 and the present year, and greater than year_adopted.
Relationships
| Name | JSON:API type | Relationship type |
|---|---|---|
place |
places |
belongs_to |
company |
companies |
belongs_to |
Get company aliases
Response body |
HTTP 200
# GET /articles/company_aliases?page[size]=2
{
"data": [
{
"id": "1",
"type": "company_aliases",
"attributes": {
"display_text": "任天堂株式会社",
"kind": "name",
"writing_system": "Japanese",
"year_adopted": null,
"dropped": null,
"year_dropped": null
},
"relationships": {
"place": {
"data": null
}
}
},
{
"id": "2",
"type": "company_aliases",
"attributes": {
"display_text": "Nintendō Kabushiki gaisha",
"kind": "name",
"writing_system": "Latin",
"year_adopted": null,
"dropped": true,
"year_dropped": null
},
"relationships": {
"place": {
"data": null
}
}
}
],
"links": {
"self": "http://localhost:3000/articles/companies/nintendo-co-ltd/names?page%5Bnumber%5D=1&page%5Bsize%5D=2",
"next": "http://localhost:3000/articles/companies/nintendo-co-ltd/names?page%5Bnumber%5D=2&page%5Bsize%5D=2",
"last": "http://localhost:3000/articles/companies/nintendo-co-ltd/names?page%5Bnumber%5D=3&page%5Bsize%5D=2"
},
"meta": {
"total_items": 5
}
}
Retrieve a collection of company aliases.
HTTP request
GET /articles/company_aliases
Filter fields
company_iddisplay_textkindwriting_systemyear_adoptedyear_droppeddropped
Sort fields
company_iddisplay_textkindwriting_systemyear_adoptedyear_droppeddropped
Success HTTP response code
200 OK
Get a single company alias
Response body |
HTTP 200
# GET /articles/company_names/5
{
"data": {
"id": "5",
"type": "company_names",
"attributes": {
"name": "Nintendo",
"kind": "styled",
"writing_system": "Latin",
"year_adopted": null,
"dropped": null,
"year_dropped": null
},
"relationships": {
"company": {
"data": {
"id": "1",
"type": "companies"
},
"links": {
"related": "http://localhost:3000/articles/companies/nintendo-co-ltd"
}
},
"place": {
"data": null
}
}
},
"included": [
{
"id": "1",
"type": "companies",
"attributes": {
"display_title": "Nintendo Co., Ltd."
},
"links": {
"self": "http://localhost:3000/articles/companies/nintendo-co-ltd"
}
}
],
"meta": {
"keywords": "nintendo, nintendo co., ltd., name, title, alias, dbljump, video games, pc games, gaming",
"description": "Nintendo is an alternate name or title for Nintendo Co., Ltd.. Learn more at Dbljump, the video game reference.",
"created_at": "2017-04-24T09:09:13.793Z",
"updated_at": "2017-04-24T09:09:13.793Z"
}
}
Retrieve a single company name.
HTTP request
GET /articles/company_names/{id} (replace {id} with record ID)
Success HTTP response code
200 OK
Create a new company alias
Request body |
POST /articles/company_aliases
{
"data": {
"type": "company_aliases",
"attributes": {
"display_text": "New Name",
"kind": "name",
"writing_system": "Latin",
"year_adopted": "2010",
"dropped": "",
"year_dropped": "2017"
},
"relationships": {
"company": {
"data": {
"id": "1",
"type": "companies"
}
},
"place": {
"data": {
"id": "17",
"type": "places"
}
}
}
}
}
Response body |
HTTP 201
{
"data": {
"id": "61",
"type": "company_aliases",
"attributes": {
"display_text": "New Name",
"kind": "name",
"writing_system": "Latin",
"year_adopted": 2010,
"dropped": true,
"year_dropped": 2017
},
"relationships": {
"company": {
"data": {
"id": "1",
"type": "companies"
},
"links": {
"related": "http://localhost:3000/articles/companies/nintendo-co-ltd"
}
},
"place": {
"data": {
"id": "17",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/bangladesh"
}
}
}
},
"included": [
{
"id": "1",
"type": "companies",
"attributes": {
"display_title": "Nintendo Co., Ltd."
},
"links": {
"self": "http://localhost:3000/articles/companies/nintendo-co-ltd"
}
},
{
"id": "17",
"type": "places",
"attributes": {
"name": "Bangladesh",
"formatted": "Bangladesh"
},
"links": {
"self": "http://localhost:3000/places/bangladesh"
}
}
],
"meta": {
"keywords": "new name, nintendo co., ltd., bangladesh, name, title, alias, dbljump, video games, pc games, gaming",
"description": "New Name is an alternate name or title for Nintendo Co., Ltd.. Learn more at Dbljump, the video game reference.",
"created_at": "2017-05-03T10:05:55.948Z",
"updated_at": "2017-05-03T10:05:55.948Z"
}
}
Create a new company alias record. User must be an editor or admin.
HTTP request
POST /articles/company_aliases
Success HTTP response code
201 Created
Update a company alias
Request body |
PATCH /articles/company_aliases/7
{
"data": {
"type": "company_aliases",
"id": "7",
"attributes": {
"display_text": "アップデート",
"kind": "styled",
"writing_system": "Japanese",
"year_adopted": "1995",
"dropped": "true",
"year_dropped": ""
},
"relationships": {
"place": {
"data": {
"id": "102",
"type": "places"
}
}
}
}
}
Response body |
HTTP 200
{
"data": {
"id": "7",
"type": "company_aliases",
"attributes": {
"display_text": "アップデート",
"kind": "styled",
"writing_system": "Japanese",
"year_adopted": 1995,
"dropped": true,
"year_dropped": null
},
"relationships": {
"company": {
"data": {
"id": "2",
"type": "companies"
},
"links": {
"related": "http://localhost:3000/articles/companies/sega-games-co-ltd"
}
},
"place": {
"data": {
"id": "102",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/japan"
}
}
}
},
"included": [
{
"id": "2",
"type": "companies",
"attributes": {
"display_title": "Sega Games Co., Ltd."
},
"links": {
"self": "http://localhost:3000/articles/companies/sega-games-co-ltd"
}
},
{
"id": "102",
"type": "places",
"attributes": {
"name": "Japan"
},
"links": {
"self": "http://localhost:3000/places/japan"
}
}
],
"meta": {
"keywords": "アップデート, sega games co., ltd., japan, name, title, alias, dbljump, video games, pc games, gaming",
"description": "アップデート is an alternate name or title for Sega Games Co., Ltd.. Learn more at Dbljump, the video game reference.",
"created_at": "2017-04-24T09:09:13.815Z",
"updated_at": "2017-05-03T10:28:40.939Z"
}
}
Update an existing company alias. The user must be an editor or admin.
The company relationship cannot be updated.
HTTP request
PATCH /articles/company_aliases/{id} (replace {id} with record ID)
Success HTTP response code
200 OK
Delete a company alias
Delete an existing company alias. User must be an editor or admin.
HTTP request
DELETE /articles/company_aliases/{id} (replace {id} with record ID)
Success HTTP response code
204 No Content
Errors
Errors specific to creating and updating company aliases.
| HTTP code | Error code | Pointer | Title |
|---|---|---|---|
| 400 | COMPANY_ALIAS_DISPLAY_TEXT_BLANK | name | Name is required. |
| 400 | COMPANY_ALIAS_DISPLAY_TEXT_TOO_LONG | name | Name cannot be more than 250 characters. |
| 400 | COMPANY_ALIAS_DISPLAY_TEXT_TAKEN | name | Name must be unique to its parent company. |
| 400 | COMPANY_ALIAS_KIND_BLANK | kind | Kind is required. |
| 400 | COMPANY_ALIAS_KIND_INCLUSION | kind | Kind must be an accepted value. |
| 400 | COMPANY_ALIAS_WRITING_SYSTEM_BLANK | writing_system | Writing system is required. |
| 400 | COMPANY_ALIAS_WRITING_SYSTEM_INCLUSION | writing_system | Writing system must be an accepted value. |
| 400 | COMPANY_ALIAS_YEAR_ADOPTED_INCLUSION | year_adopted | Year adopted must be a past year not before 1800. |
| 400 | COMPANY_ALIAS_YEAR_DROPPED_INCLUSION | year_dropped | Year dropped must be a past year not before 1800. |
| 400 | COMPANY_ALIAS_YEAR_DROPPED_INVALID | year_dropped | Year dropped must not be earlier than year adopted. |
| 400 | COMPANY_ALIAS_PLACE_ID_INVALID | data/relationships/place/data/id | Place ID must be a valid country or region ID. |
Articles: Company Notes
Resources related to company notes. Notes are trivia, stories or facts about a company.
Request attributes
See Create a new company note and Update a company note.
Response attributes
Get all of a company’s titles
Response body |
HTTP 200
# GET /articles/company_notes?page[size]=2
{
"data": [
{
"id": "1",
"type": "company_notes",
"attributes": {
"category": "History",
"body": "Nintendo was a playing card manufacturer before it started making video games.",
"cite_url": "",
"cite_title": "",
"cite_website": ""
},
"relationships": {
"company": {
"data": {
"id": "1",
"type": "companies"
},
"links": {
"related": "http://localhost:3000/articles/companies/nintendo-co-ltd"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/1"
}
}
}
},
{
"id": "2",
"type": "company_notes",
"attributes": {
"category": "Significance",
"body": "The first video game console ever played in space was made by Nintendo. Aleksandr Serebrov played Tetris on a Game Boy.",
"cite_url": "",
"cite_title": "",
"cite_website": ""
},
"relationships": {
"company": {
"data": {
"id": "1",
"type": "companies"
},
"links": {
"related": "http://localhost:3000/articles/companies/nintendo-co-ltd"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/1"
}
}
}
}
],
"links": {},
"meta": {
"total_items": 3
}
}
Retrieve all company notes. Automatically paginated.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /articles/company_notes
URL query parameters
| Parameter | Default | Description |
|---|---|---|
| fields[{record-type}] | All fields | Return only specified fields, e.g. ?fields[company_notes]=body |
| filter[{field}] | All records | Filter search by field, e.g. ?filter[category]=Hist |
| page[number] | 1 | Select the page number, e.g. ?page[number]=3 |
| page[size] | 30 | Select the number of records per page, e.g. ?page[size]=20 |
Success HTTP response code
200 OK
Get a single company note
Response body |
HTTP 200
# GET /articles/company_notes/1
{
"data": {
"id": "1",
"type": "company_notes",
"attributes": {
"category": "History",
"body": "Nintendo was a playing card manufacturer before it started making video games.",
"cite_url": "",
"cite_title": "",
"cite_website": ""
},
"relationships": {
"company": {
"data": {
"id": "1",
"type": "companies"
},
"links": {
"related": "http://localhost:3000/articles/companies/nintendo-co-ltd"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/1"
}
}
}
},
"meta": {
"keywords": "nintendo co., ltd., notes, trivia, facts, dbljump, video games, pc games, gaming",
"description": "Nintendo was a playing card manufacturer before it started making video games.",
"created_at": "2017-05-17T21:40:00.986Z",
"updated_at": "2017-05-17T21:40:00.986Z"
}
}
Retrieve a single company note. Game notes are publicly available. No sign-in is required.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /articles/company_notes/{id} (replace {id} with record ID)
Success HTTP response code
200 OK
Response attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| category | string | Y | See Category. |
| body | string | Y | The note text. 5-2000 chars. |
| cite_url | string | The URL of the source web page. 5-250 chars. | |
| cite_title | string | The title of the source web page. 5-250 chars. | |
| cite_website | string | The name of the source website. 1-100 chars. |
Relationships
| Association | Record type | Relationship type |
|---|---|---|
| company | companies | belongs_to |
| created_by | users | belongs_to |
Meta
The meta section of the JSON response includes keywords, description, created_at and updated_at attributes.
Create a new company note
Request body |
POST /articles/company_notes
{
"data": {
"type": "company_notes",
"attributes": {
"category": "History",
"body": "The note text.",
"cite_url": "http://ign.com/article",
"cite_title": "The Article Title",
"cite_website": "IGN"
}
},
"relationships": {
"company": {
"data": {
"id": "1",
"type": "companies"
}
}
}
Response body |
HTTP 201
{
"data": {
"id": "14",
"type": "company_notes",
"attributes": {
"category": "History",
"body": "The note text.",
"cite_url": "http://ign.com/article",
"cite_title": "The Article Title",
"cite_website": "IGN"
},
"relationships": {
"company": {
"data": {
"id": "1",
"type": "companies"
},
"links": {
"related": "http://localhost:3000/articles/companies/nintendo-co-ltd"
}
},
"created_by": {
"data": {
"id": "2",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/2"
}
}
}
},
"meta": {
"keywords": "nintendo co., ltd., notes, trivia, facts, dbljump, video games, pc games, gaming",
"description": "The note text.",
"created_at": "2017-05-18T21:42:31.019Z",
"updated_at": "2017-05-18T21:42:31.019Z"
}
}
Create a new company note record. A note is a fact, story or piece of trivia about a company. User must be an editor or admin.
- User authentication: required
- Authorization level: editor or admin
HTTP request
POST /articles/company_notes
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| category | string | Y | See Category. |
| body | string | Y | The note text. 5-2000 chars. |
| cite_url | string | The URL of the source web page. 5-250 chars. | |
| cite_title | string | The title of the source web page. 5-250 chars. | |
| cite_website | string | The name of the source website. 1-100 chars. |
Relationships
Check this section’s code example to see how to update these relationships.
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| company | belongs_to | Y | companies | The company the name belongs to. |
Category
The category attribute accepts the following values.
| Value | Description |
|---|---|
| history | Notes related to the history of the company. |
| organization | Notes related to the structure of the company. |
| products | Notes related to the company’s products. |
| tech | Notes related to the company’s innovations and technologies used. |
| impact | Notes related to the company’s achievements and impact on the wider world. |
Success HTTP response code
201 Created
Update a company note
Request body |
PATCH /articles/company_notes/1
{
"data": {
"type": "company_notes",
"id": "1",
"attributes": {
"category": "History",
"body": "The updated note text.",
"cite_url": "http://ign.com/updated",
"cite_title": "The Updated Title",
"cite_website": "IGN"
}
}
}
Response body |
HTTP 200
{
"data": {
"id": "1",
"type": "company_notes",
"attributes": {
"category": "History",
"body": "The updated note text.",
"cite_url": "http://ign.com/updated",
"cite_title": "The Updated Title",
"cite_website": "IGN"
},
"relationships": {
"company": {
"data": {
"id": "1",
"type": "companies"
},
"links": {
"related": "http://localhost:3000/articles/companies/nintendo-co-ltd"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/1"
}
}
}
},
"meta": {
"keywords": "nintendo co., ltd., notes, trivia, facts, dbljump, video games, pc games, gaming",
"description": "The updated note text.",
"created_at": "2017-05-17T21:40:00.986Z",
"updated_at": "2017-05-18T21:55:39.825Z"
}
}
Update an existing company note. The user must be an editor.
- User authentication: required
- Authorization level: admin
HTTP request
PATCH /articles/company_notes/{id} (replace {id} with record ID)
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| category | string | Y | See Category. |
| body | string | Y | The note text. 5-2000 chars. |
| cite_url | string | The URL of the source web page. 5-250 chars. | |
| cite_title | string | The title of the source web page. 5-250 chars. | |
| cite_website | string | The name of the source website. 1-100 chars. |
Relationships
Check this section’s code example to see how to update these relationships.
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| version | belongs_to | company_versions | Version must belong to same company as title. |
Success HTTP response code
200 OK
Delete a company note
Delete an existing company note. User must be an editor or admin.
- User authentication: required
- Authorization level: editor or admin
HTTP request
DELETE /articles/company_notes/{id} (replace {id} with record ID)
Success HTTP response code
204 No Content
Errors
Errors specific to creating and updating company notes.
| HTTP code | Error code | Pointer | Title |
|---|---|---|---|
| 400 | COMPANY_NOTE_CATEGORY_BLANK | category | Category is required. |
| 400 | COMPANY_NOTE_CATEGORY_INCLUSION | category | Category must be an accepted value. |
| 400 | COMPANY_NOTE_BODY_BLANK | body | Body is required. |
| 400 | COMPANY_NOTE_BODY_TOO_SHORT | body | Body cannot be less than 5 characters. |
| 400 | COMPANY_NOTE_BODY_TOO_LONG | body | Body cannot be more than 8000 characters. |
| 400 | COMPANY_NOTE_CITE_URL_TOO_SHORT | cite_url | Cite URL cannot be less than 5 characters. |
| 400 | COMPANY_NOTE_CITE_URL_TOO_LONG | cite_url | Cite URL cannot be more than 250 characters. |
| 400 | COMPANY_NOTE_CITE_TITLE_TOO_LONG | cite_title | Cite title cannot be more than 250 characters. |
| 400 | COMPANY_NOTE_CITE_WEBSITE_TOO_LONG | cite_website | Cite website cannot be more than 100 characters. |
Articles: Company Kinships
Kinships are relationships between companies, e.g. ownership or division. Each kinship is between two companies, the parent and the child.
These resources include separate routes for indexing and creating parent kinships (/articles/companies/{company-id}/parents) and child kinships (/articles/companies/{company-id}/children) for a given company. A single common route is used for showing, updating, and deleting existing kinship records (/articles/company_kinships/{id}).
Get all company kinships
Response body |
HTTP 200
# GET /articles/company_kinships
{
"data": [
{
"id": "1",
"type": "company_kinships",
"attributes": {
"kind": "division",
"start_year": null,
"end_year": null
},
"relationships": {
"parent": {
"data": {
"id": "1",
"type": "companies"
},
"links": {
"related": "http://localhost:3000/articles/companies/nintendo-co-ltd"
}
},
"child": {
"data": {
"id": "5",
"type": "companies"
},
"links": {
"related": "http://localhost:3000/articles/companies/nintendo-entertainment-analysis-development"
}
}
}
},
{
"id": "2",
"type": "company_kinships",
"attributes": {
"kind": "division",
"start_year": null,
"end_year": null
},
"relationships": {
"parent": {
"data": {
"id": "1",
"type": "companies"
},
"links": {
"related": "http://localhost:3000/articles/companies/nintendo-co-ltd"
}
},
"child": {
"data": {
"id": "22",
"type": "companies"
},
"links": {
"related": "http://localhost:3000/articles/companies/retro-studios-inc"
}
}
}
},
{
"id": "3",
"type": "company_kinships",
"attributes": {
"kind": "ownership",
"start_year": null,
"end_year": null
},
"relationships": {
"parent": {
"data": {
"id": "1",
"type": "companies"
},
"links": {
"related": "http://localhost:3000/articles/companies/nintendo-co-ltd"
}
},
"child": {
"data": {
"id": "21",
"type": "companies"
},
"links": {
"related": "http://localhost:3000/articles/companies/monolith-soft-inc"
}
}
}
}
],
"links": {},
"meta": {
"total_items": 3
}
}
Retrieve all company kinships. Automatically paginated.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /articles/company_kinships
URL query parameters
| Parameter | Default | Description |
|---|---|---|
| fields[{record-type}] | All fields | Return only specified fields, e.g. ?fields[company_kinships]=kind |
| filter[{field}] | All records | Filter search by field, e.g. ?filter[kind]=division |
| page[number] | 1 | Select the page number, e.g. ?page[number]=3 |
| page[size] | 30 | Select the number of records per page, e.g. ?page[size]=20 |
Success HTTP response code
200 OK
Get a single company kinship
Response body |
HTTP 200
# GET /articles/company_kinships/5
{
"data": {
"id": "5",
"type": "company_kinships",
"attributes": {
"kind": "ownership",
"start_year": null,
"end_year": null
},
"relationships": {
"parent": {
"data": {
"id": "4",
"type": "companies"
},
"links": {
"related": "http://localhost:3000/articles/companies/microsoft-corporation"
}
},
"child": {
"data": {
"id": "17",
"type": "companies"
},
"links": {
"related": "http://localhost:3000/articles/companies/mojang-ab"
}
}
}
},
"included": [
{
"id": "4",
"type": "companies",
"attributes": {
"display_title": "Microsoft Corporation"
},
"links": {
"self": "http://localhost:3000/articles/companies/microsoft-corporation"
}
},
{
"id": "17",
"type": "companies",
"attributes": {
"display_title": "Mojang AB"
},
"links": {
"self": "http://localhost:3000/articles/companies/mojang-ab"
}
}
],
"meta": {
"keywords": "Microsoft Corporation, Mojang AB, ownership, company, ownership, parent, division, subsidiary, branch, dbljump, video games, pc games, gaming",
"description": "",
"created_at": "2017-07-01T11:26:52.623Z",
"updated_at": "2017-07-01T11:26:52.623Z"
}
}
Retrieve a single company kinship record. Company kinships are publicly available. No sign-in is required.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /articles/company_kinships/{id} (replace {id} with record ID)
Success HTTP response code
200 OK
Response attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| kind | string | Y | The kinship classification. Must be ‘ownership’ or 'division’. |
| start_year | integer | Year the kinship was formed. Must be between 1800 and present year. | |
| end_year | integer | Year the kinship was ended. Must be between 1800 and present year. |
Relationships
| Association | Record type | Relationship type |
|---|---|---|
| parent | companies | belongs_to |
| child | companies | belongs_to |
Meta
The meta section of the JSON response includes keywords, description, created_at and updated_at attributes.
Create a new company kinship
Request body |
POST /articles/company_kinships
{
"data": {
"type": "company_kinships",
"attributes": {
"kind": "ownership",
"start_year": "1997",
"end_year": ""
},
"relationships": {
"child": {
"data": {
"id": "11",
"type": "companies"
}
},
"parent": {
"data": {
"id": "7",
"type": "companies"
}
}
}
}
}
Response body |
HTTP 201
{
"data": {
"id": "7",
"type": "company_kinships",
"attributes": {
"kind": "ownership",
"start_year": 1997,
"end_year": null
},
"relationships": {
"parent": {
"data": {
"id": "7",
"type": "companies"
},
"links": {
"related": "http://localhost:3000/articles/companies/electronic-arts-inc-ea"
}
},
"child": {
"data": {
"id": "11",
"type": "companies"
},
"links": {
"related": "http://localhost:3000/articles/companies/ea-maxis"
}
}
}
},
"included": [
{
"id": "7",
"type": "companies",
"attributes": {
"display_title": "Electronic Arts, Inc. (EA)"
},
"links": {
"self": "http://localhost:3000/articles/companies/electronic-arts-inc-ea"
}
},
{
"id": "11",
"type": "companies",
"attributes": {
"display_title": "EA Maxis"
},
"links": {
"self": "http://localhost:3000/articles/companies/ea-maxis"
}
}
],
"meta": {
"keywords": "Electronic Arts, Inc. (EA), EA Maxis, ownership, company, ownership, parent, division, subsidiary, branch, dbljump, video games, pc games, gaming",
"description": "",
"created_at": "2017-07-01T12:05:57.502Z",
"updated_at": "2017-07-01T12:05:57.502Z"
}
}
Create a new company kinship record. User must be an editor or admin.
- User authentication: required
- Authorization level: editor or admin
HTTP request
POST /articles/companies/{company-slug}/children
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| kind | string | Y | The name classification. Must be ‘name’, 'styled’ or 'alias’. |
| start_year | integer | Year the kinship was formed. Must be between 1800 and present year. | |
| end_year | integer | Year the kinship was ended. Must be between 1800 and present year. |
Relationships
Check this section’s code example to see how to update these relationships.
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| parent | belongs_to | Y | companies | The parent company. |
| child | belongs_to | Y | companies | The child company. |
Success HTTP response code
201 Created
Update a company kinship
Request body |
PATCH /articles/company_kinships/7
{
"data": {
"type": "company_kinships",
"id": "7",
"attributes": {
"kind": "ownership",
"start_year": "1997",
"end_year": "2017"
},
"relationships": {
"child": {
"data": {
"id": "11",
"type": "companies"
}
},
"parent": {
"data": {
"id": "7",
"type": "companies"
}
}
}
}
}
Response body |
HTTP 200
{
"data": {
"id": "7",
"type": "company_kinships",
"attributes": {
"kind": "ownership",
"start_year": 1997,
"end_year": 2017
},
"relationships": {
"parent": {
"data": {
"id": "7",
"type": "companies"
},
"links": {
"related": "http://localhost:3000/articles/companies/electronic-arts-inc-ea"
}
},
"child": {
"data": {
"id": "11",
"type": "companies"
},
"links": {
"related": "http://localhost:3000/articles/companies/ea-maxis"
}
}
}
},
"included": [
{
"id": "7",
"type": "companies",
"attributes": {
"display_title": "Electronic Arts, Inc. (EA)"
},
"links": {
"self": "http://localhost:3000/articles/companies/electronic-arts-inc-ea"
}
},
{
"id": "11",
"type": "companies",
"attributes": {
"display_title": "EA Maxis"
},
"links": {
"self": "http://localhost:3000/articles/companies/ea-maxis"
}
}
],
"meta": {
"keywords": "Electronic Arts, Inc. (EA), EA Maxis, ownership, company, ownership, parent, division, subsidiary, branch, dbljump, video games, pc games, gaming",
"description": "",
"created_at": "2017-07-01T12:05:57.502Z",
"updated_at": "2017-07-01T12:10:00.459Z"
}
}
Update an existing company kinship. The user must be an editor.
- User authentication: required
- Authorization level: admin
HTTP request
PATCH /articles/company_kinships/{id} (replace {id} with record ID)
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| kind | string | Y | The name classification. Must be ‘name’, 'styled’ or 'alias’. |
| start_year | integer | Year the kinship was formed. Must be between 1800 and present year. | |
| end_year | integer | Year the kinship was ended. Must be between 1800 and present year. |
Relationships
Check this section’s code example to see how to update these relationships.
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| parent | belongs_to | Y | companies | The parent company. |
| child | belongs_to | Y | companies | The child company. |
Success HTTP response code
200 OK
Delete a company kinship
Delete an existing company kinship. User must be an editor or admin.
- User authentication: required
- Authorization level: editor or admin
HTTP request
DELETE /articles/company_kinships/{id} (replace {id} with record ID)
Success HTTP response code
204 No Content
Errors
Errors specific to creating and updating company kinships.
| HTTP code | Error code | Pointer | Title |
|---|---|---|---|
| 400 | COMPANY_KINSHIP_KIND_BLANK | kind | Kind is required. |
| 400 | COMPANY_KINSHIP_KIND_INCLUSION | kind | Kind must be an accepted value. |
| 400 | COMPANY_KINSHIP_START_YEAR_INCLUSION | start_year | Start year must be a past year not before 1800. |
| 400 | COMPANY_KINSHIP_END_YEAR_INCLUSION | end_year | End year must be a past year not before 1800. |
| 400 | COMPANY_KINSHIP_END_YEAR_INVALID | end_year | End year must not be earlier than start year. |
| 400 | COMPANY_KINSHIP_PARENT_ID_BLANK | data/relationships/parent/data/id | Parent is required. |
| 400 | COMPANY_KINSHIP_CHILD_ID_BLANK | data/relationships/child/data/id | Child is required. |
| 400 | COMPANY_KINSHIP_PARENT_ID_INCLUSION | data/relationships/parent/data/id | Parent ID must not be the same as child ID. |
Articles: Company Credits
Resources related to company credits.
Request attributes
See Create a new company credit and Update a company credit.
Response attributes
Get all company credits
Response body |
HTTP 200
# GET /articles/company_credits
{
"data": [
{
"id": "3",
"type": "company_credits",
"attributes": {
"category": "publishing",
"role": "Publisher"
},
"relationships": {
"credited": {
"data": {
"id": "1",
"type": "companies"
},
"links": {
"related": "http://localhost:3000/articles/companies/nintendo-co-ltd"
}
},
"game": {
"data": {
"id": "46",
"type": "games"
},
"links": {
"related": "http://localhost:3000/articles/games/the-wonderful-101"
}
},
"version": {
"data": {
"id": "1",
"type": "game_versions"
},
"links": {
"related": "http://localhost:3000/articles/game_versions/1"
}
},
"place": {
"data": null
}
}
}
],
"links": {},
"meta": {
"total_items": 1
}
}
Retrieve all company game credits. Automatically paginated.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /articles/company_credits
URL query parameters
| Parameter | Default | Description |
|---|---|---|
| fields[{record-type}] | All fields | Return only specified fields, e.g. ?fields[company_credits]=role |
| filter[{field}] | All records | Filter search by field, e.g. ?filter[category]=publishing |
| page[number] | 1 | Select the page number, e.g. ?page[number]=3 |
| page[size] | 30 | Select the number of records per page, e.g. ?page[size]=20 |
Success HTTP response code
200 OK
Get a single company credit
Response body |
HTTP 200
# GET /articles/company_credits/1
{
"data": {
"id": "4",
"type": "company_credits",
"attributes": {
"category": "development",
"role": "Developer"
},
"relationships": {
"credited": {
"data": {
"id": "1",
"type": "companies"
},
"links": {
"related": "http://localhost:3000/articles/companies/nintendo-co-ltd"
}
},
"game": {
"data": {
"id": "46",
"type": "games"
},
"links": {
"related": "http://localhost:3000/articles/games/the-wonderful-101"
}
},
"version": {
"data": {
"id": "1",
"type": "game_versions"
},
"links": {
"related": "http://localhost:3000/articles/game_versions/1"
}
},
"place": {
"data": null
}
}
},
"included": [
{
"id": "1",
"type": "companies",
"attributes": {
"display_title": "Nintendo Co., Ltd."
},
"links": {
"self": "http://localhost:3000/articles/companies/nintendo-co-ltd"
}
},
{
"id": "46",
"type": "games",
"attributes": {
"display_title": "The Wonderful 101"
},
"links": {
"self": "http://localhost:3000/articles/games/the-wonderful-101"
}
}
],
"meta": {
"keywords": "The Wonderful 101, Nintendo Co., Ltd., Developer, company, credit, dbljump, video games, pc games, gaming",
"description": "Find staff and company credits for The Wonderful 101 at Dbljump, the video game reference.",
"created_at": "2017-06-30T23:44:17.051Z",
"updated_at": "2017-06-30T23:44:17.051Z"
}
}
Retrieve a single company credit. Game credits are publicly available. No sign-in is required.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /articles/company_credits/{id} (replace {id} with record ID)
Success HTTP response code
200 OK
Response attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| category | string | Y | The credit category. |
| role | string | Y | The credit, e.g. ‘Publisher’ or 'Developer’. |
Relationships
| Association | Record type | Relationship type |
|---|---|---|
| credited | companies | belongs_to |
| game | games | belongs_to |
| version | game_versions | belongs_to |
| place | places | belongs_to |
Meta
The meta section of the JSON response includes keywords, description, created_at and updated_at attributes.
Create a new company credit
Request body |
POST /articles/company_credits
{
"data": {
"type": "company_credits",
"attributes": {
"category": "development",
"role": "Developer"
},
"relationships": {
"credited": {
"data": {
"id": "1",
"type": "games"
}
},
"game": {
"data": {
"id": "46",
"type": "games"
}
},
"version": {
"data": {
"id": "1",
"type": "game_versions"
}
},
"place": {
"data": {
"id": "",
"type": "places"
}
}
}
}
}
Response body |
HTTP 201
{
"data": {
"id": "4",
"type": "company_credits",
"attributes": {
"category": "development",
"role": "Developer"
},
"relationships": {
"credited": {
"data": {
"id": "1",
"type": "companies"
},
"links": {
"related": "http://localhost:3000/articles/companies/nintendo-co-ltd"
}
},
"game": {
"data": {
"id": "46",
"type": "games"
},
"links": {
"related": "http://localhost:3000/articles/games/the-wonderful-101"
}
},
"version": {
"data": {
"id": "1",
"type": "game_versions"
},
"links": {
"related": "http://localhost:3000/articles/game_versions/1"
}
},
"place": {
"data": null
}
}
},
"included": [
{
"id": "1",
"type": "companies",
"attributes": {
"display_title": "Nintendo Co., Ltd."
},
"links": {
"self": "http://localhost:3000/articles/companies/nintendo-co-ltd"
}
},
{
"id": "46",
"type": "games",
"attributes": {
"display_title": "The Wonderful 101"
},
"links": {
"self": "http://localhost:3000/articles/games/the-wonderful-101"
}
}
],
"meta": {
"keywords": "The Wonderful 101, Nintendo Co., Ltd., Developer, company, credit, dbljump, video games, pc games, gaming",
"description": "Find staff and company credits for The Wonderful 101 at Dbljump, the video game reference.",
"created_at": "2017-06-30T23:44:17.051Z",
"updated_at": "2017-06-30T23:44:17.051Z"
}
}
Create a new game credit for a given company. User must be an editor or admin.
- User authentication: required
- Authorization level: editor or admin
HTTP request
POST /articles/company_credits
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| category | string | Y | The credit category. Must be an accepted value. |
| role | string | Y | The credit, e.g. ‘Publisher’ or 'Developr’. Max 100 chars. |
Relationships
Check this section’s code example to see how to update these relationships.
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| credited | belongs_to | Y | companies | The company credited. |
| game | belongs_to | Y | games | The game the credit relates to. |
| version | belongs_to | game_versions | The game version the credit relates to (optional). | |
| place | belongs_to | places | The place the credit relates to (optional). |
Company credit categories
The following are accepted value for the categories attribute:
- publishing
- development
- technology
- visuals
- sound
- language
- special
- misc
Success HTTP response code
201 Created
Update a company credit
Request body |
PATCH /articles/company_credits/3
{
"data": {
"type": "company_credits",
"id": "3",
"attributes": {
"category": "special",
"role": "Special Thanks"
},
"relationships": {
"version": {
"data": {
"id": "1",
"type": "game_versions"
}
},
"place": {
"data": {
"id": "55",
"type": "places"
}
}
}
}
}
Response body |
HTTP 200
{
"data": {
"id": "3",
"type": "company_credits",
"attributes": {
"category": "special",
"role": "Special Thanks"
},
"relationships": {
"credited": {
"data": {
"id": "1",
"type": "companies"
},
"links": {
"related": "http://localhost:3000/articles/companies/nintendo-co-ltd"
}
},
"game": {
"data": {
"id": "46",
"type": "games"
},
"links": {
"related": "http://localhost:3000/articles/games/the-wonderful-101"
}
},
"version": {
"data": {
"id": "1",
"type": "game_versions"
},
"links": {
"related": "http://localhost:3000/articles/game_versions/1"
}
},
"place": {
"data": {
"id": "55",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/czechia"
}
}
}
},
"included": [
{
"id": "1",
"type": "companies",
"attributes": {
"display_title": "Nintendo Co., Ltd."
},
"links": {
"self": "http://localhost:3000/articles/companies/nintendo-co-ltd"
}
},
{
"id": "46",
"type": "games",
"attributes": {
"display_title": "The Wonderful 101"
},
"links": {
"self": "http://localhost:3000/articles/games/the-wonderful-101"
}
},
{
"id": "55",
"type": "places",
"attributes": {
"formatted": "Czechia"
},
"links": {
"self": "http://localhost:3000/places/czechia"
}
}
],
"meta": {
"keywords": "The Wonderful 101, Nintendo Co., Ltd., Special Thanks, Czechia, company, credit, dbljump, video games, pc games, gaming",
"description": "Find staff and company credits for The Wonderful 101 at Dbljump, the video game reference.",
"created_at": "2017-06-30T23:23:15.317Z",
"updated_at": "2017-06-30T23:55:47.337Z"
}
}
Update an existing company credit. The user must be an editor.
- User authentication: required
- Authorization level: admin
HTTP request
PATCH /articles/company_notes/{id} (replace {id} with record ID)
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| category | string | Y | The credit category. Must be an accepted value. |
| role | string | Y | The credit, e.g. ‘Publisher’ or 'Developer’. |
Relationships
Check this section’s code example to see how to update these relationships.
NOTE - The game and credited relationships cannot be updated.
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| version | belongs_to | game_versions | The game version the credit relates to (optional). | |
| place | belongs_to | places | The place the credit relates to (optional). |
Company credit categories
The following are accepted value for the categories attribute:
- publishing
- development
- technology
- visuals
- sound
- language
- special
- misc
Success HTTP response code
200 OK
Delete a company credit
Delete an existing company credit. User must be an editor or admin.
- User authentication: required
- Authorization level: editor or admin
HTTP request
DELETE /articles/company_credits/{id} (replace {id} with record ID)
Success HTTP response code
204 No Content
Errors
Errors specific to creating and updating company credits.
| HTTP code | Error code | Pointer | Title |
|---|---|---|---|
| 400 | COMPANY_CREDIT_CREDITED_ID_BLANK | data/relationships/credited/data/id | Credited is required. |
| 400 | COMPANY_CREDIT_GAME_ID_BLANK | data/relationships/game/data/id | Game is required. |
| 400 | COMPANY_CREDIT_VERSION_ID_INVALID | data/relationships/version/data/id | Version ID must be a version of credit game. |
| 400 | COMPANY_CREDIT_PLACE_ID_INVALID | data/relationships/place/data/id | Place ID must be a valid country or region ID. |
| 400 | COMPANY_CREDIT_ROLE_BLANK | role | Role is required. |
| 400 | COMPANY_CREDIT_ROLE_TOO_LONG | role | Role cannot be more than 100 characters. |
| 400 | COMPANY_CREDIT_CATEGORY_BLANK | category | Category is required. |
| 400 | COMPANY_CREDIT_CATEGORY_INCLUSION | category | Category must be an accepted value. |
Articles: Peer Reviews
Resources related to peer reviews of game, company and person articles.
When a user with editor privileges creates an article, the article is not published until it passes review by another user with editor privileges. These resources include an endpoint for submitting an article for review, and recording the outcome of the review.
Submit an article for review
Request body |
POST /articles/peer_reviews
{
"data": {
"type": "peer_reviews",
"attributes": {
"article_id": "1"
}
}
}
Response body |
HTTP 200
{
"data": {
"id": "1",
"type": "companies",
"attributes": {
"display_title": "Nintendo Co., Ltd.",
"description": "Nintendo is a Japanese video game hardware and software company founded in 1889.",
"slug": "nintendo-co-ltd",
"last_submitted_at": "2017-06-21T16:15:23.948Z",
"last_reviewed_at": null,
"last_review_outcome": null,
"last_review_comments": null,
"published_at": null,
"status": "submitted",
"origin_date": null,
"origin_year": 1889,
"end": null,
"end_date": null,
"end_year": null
},
"relationships": {
"primary_image": {
"data": null
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/1"
}
},
"last_reviewed_by": {
"data": null
},
"origin_place": {
"data": {
"id": "2932",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/kyoto-kyoto-prefecture-japan"
}
},
"latest_place": {
"data": null
},
"names": {
"data": [
{
"id": "1",
"type": "company_names"
},
{
"id": "2",
"type": "company_names"
},
{
"id": "3",
"type": "company_names"
},
{
"id": "4",
"type": "company_names"
},
{
"id": "5",
"type": "company_names"
}
],
"links": {
"related": "http://localhost:3000/articles/companies/nintendo-co-ltd/names"
}
},
"notes": {
"data": [
{
"id": "1",
"type": "company_notes"
},
{
"id": "2",
"type": "company_notes"
}
],
"links": {
"related": "http://localhost:3000/articles/companies/nintendo-co-ltd/notes"
}
},
"images": {
"data": [
{
"id": "1",
"type": "images"
},
{
"id": "2",
"type": "images"
}
],
"links": {
"related": "http://localhost:3000/articles/companies/nintendo-co-ltd/images"
}
},
"credits": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/companies/nintendo-co-ltd/credits"
}
},
"parents": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/companies/nintendo-co-ltd/parents"
}
},
"children": {
"data": [
{
"id": "5",
"type": "company_kinships"
}
],
"links": {
"related": "http://localhost:3000/articles/companies/nintendo-co-ltd/children"
}
}
},
"links": {
"self": "http://localhost:3000/articles/companies/nintendo-co-ltd"
}
},
"meta": {
"keywords": "Nintendo Co., Ltd., 1889, Kyoto, Kyoto Prefecture, Japan, 任天堂株式会社, Nintendō Kabushiki gaisha, Nintendo Playing Card Co., Nintendo Koppai, Nintendo, company, profile, biography, trivia, dbljump, video games, pc games, gaming",
"description": "Find Nintendo Co., Ltd.'s game credits, profile, images and facts at Dbljump, the video game reference.",
"created_at": "2017-06-20T23:07:11.468Z",
"updated_at": "2017-06-21T16:15:24.482Z"
}
}
Submit a game, company, or person article for peer review. The user must be the creator of the article.
- User authentication: required
- Authorization level: editor or admin; user must be article creator
HTTP request
POST /articles/peer_reviews
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| article_id | integer | Y | The article record ID |
Success HTTP response code
200 OK
Review an unpublished article
Request body |
PATCH /articles/peer_reviews/1
{
"data": {
"type": "peer_reviews",
"id": "1",
"attributes": {
"last_review_outcome": "fail_style",
"last_review_comments": "Please fix typing errors."
}
}
}
Response body |
HTTP 200
{
"data": {
"id": "1",
"type": "companies",
"attributes": {
"display_title": "Nintendo Co., Ltd.",
"description": "Nintendo is a Japanese video game hardware and software company founded in 1889.",
"slug": "nintendo-co-ltd",
"last_submitted_at": "2017-06-21T16:15:23.948Z",
"last_reviewed_at": "2017-06-21T16:21:15.946Z",
"last_review_outcome": "fail_style",
"last_review_comments": "Please fix typing errors.",
"published_at": null,
"status": "draft",
"origin_date": null,
"origin_year": 1889,
"end": null,
"end_date": null,
"end_year": null
},
"relationships": {
"primary_image": {
"data": null
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/1"
}
},
"last_reviewed_by": {
"data": {
"id": "2",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/2"
}
},
"origin_place": {
"data": {
"id": "2932",
"type": "places"
},
"links": {
"related": "http://localhost:3000/places/kyoto-kyoto-prefecture-japan"
}
},
"latest_place": {
"data": null
},
"names": {
"data": [
{
"id": "1",
"type": "company_names"
},
{
"id": "2",
"type": "company_names"
},
{
"id": "3",
"type": "company_names"
},
{
"id": "4",
"type": "company_names"
},
{
"id": "5",
"type": "company_names"
}
],
"links": {
"related": "http://localhost:3000/articles/companies/nintendo-co-ltd/names"
}
},
"notes": {
"data": [
{
"id": "1",
"type": "company_notes"
},
{
"id": "2",
"type": "company_notes"
}
],
"links": {
"related": "http://localhost:3000/articles/companies/nintendo-co-ltd/notes"
}
},
"images": {
"data": [
{
"id": "1",
"type": "images"
},
{
"id": "2",
"type": "images"
}
],
"links": {
"related": "http://localhost:3000/articles/companies/nintendo-co-ltd/images"
}
},
"credits": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/companies/nintendo-co-ltd/credits"
}
},
"parents": {
"data": [],
"links": {
"related": "http://localhost:3000/articles/companies/nintendo-co-ltd/parents"
}
},
"children": {
"data": [
{
"id": "5",
"type": "company_kinships"
}
],
"links": {
"related": "http://localhost:3000/articles/companies/nintendo-co-ltd/children"
}
}
},
"links": {
"self": "http://localhost:3000/articles/companies/nintendo-co-ltd"
}
},
"meta": {
"keywords": "Nintendo Co., Ltd., 1889, Kyoto, Kyoto Prefecture, Japan, 任天堂株式会社, Nintendō Kabushiki gaisha, Nintendo Playing Card Co., Nintendo Koppai, Nintendo, company, profile, biography, trivia, dbljump, video games, pc games, gaming",
"description": "Find Nintendo Co., Ltd.'s game credits, profile, images and facts at Dbljump, the video game reference.",
"created_at": "2017-06-20T23:07:11.468Z",
"updated_at": "2017-06-21T16:21:16.184Z"
}
}
Record the outcome of an article peer review. The user must be an editor, and must not be the article creator.
- User authentication: required
- Authorization level: admin
HTTP request
PATCH /articles/peer_reviews/{ID} (replace {ID} with article ID)
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| last_review_outcome | string | Y | Must be ok, fail_style, fail_incomplete, or fail_accuracy |
| last_review_comments | text | Y | Reviewer feedback on submission. 1-800 characters. |
Success HTTP response code
200 OK
Errors
Errors specific to peer reviews of articles.
| HTTP code | Error code | Pointer | Title |
|---|---|---|---|
| 401 | PEER_REVIEW_SUBMISSION_DECLINED | Peer review submission can only be made by the article creator. | |
| 401 | PEER_REVIEW_OUTCOME_DECLINED | Peer review cannot be made by article creator. | |
| 400 | PEER_REVIEW_ALREADY_PUBLISHED | The article has already passed peer review. | |
| 400 | PEER_REVIEW_OUTCOME_BLANK | last_review_outcome |
Review outcome must be present. |
| 400 | PEER_REVIEW_OUTCOME_INCLUSION | last_review_outcome |
Review outcome must be an accepted value. |
| 400 | PEER_REVIEW_COMMENTS_BLANK | last_review_comments |
Review comments must be present. |
| 400 | PEER_REVIEW_COMMENTS_TOO_LONG | last_review_comments |
Review comments cannpt be longer than 800 characters. |
Users
Resources related to user accounts.
Request attributes
See Register a new user and Update a user account details.
Response attributes
See Get single user.
Get all users
Response body |
HTTP 200
# GET /users?page[size]=2
{
"data": [
{
"id": "1",
"type": "users",
"attributes": {
"email": "tiki@dbljump.com",
"username": "tikithekiwi",
"role": "admin",
"given_names": "Tiki",
"family_name": "the Kiwi",
"gender": "Female",
"avatar": null,
"avatar_thumb": null,
"birthday": "1988-09-01",
"jwt": null
},
"relationships": {
"country": {
"data": null,
"links": {
"related": "http://api.dbljump.com/places/united-kingdom"
}
},
"images": {
"links": {
"related": "http://api.dbljump.com/users/1/images"
}
}
},
"links": {
"self": "http://api.dbljump.com/users/1"
},
"meta": {
"description": "Tiki the Kiwi is a member at Dbljump, the video game reference.",
"keywords": "tikithekiwi, Tiki the Kiwi, user, dbljump, video games, pc games, gaming",
"last_signed_in_at": null,
"last_sign_in_ip": null,
"sign_in_count": 0,
"activated_at": "2017-07-12T13:28:27.875Z",
"created_at": "2017-07-12T13:28:27.985Z",
"updated_at": "2017-07-12T13:28:27.985Z"
}
},
{
"id": "3",
"type": "users",
"attributes": {
"email": "member@example.com",
"username": "member",
"role": "member",
"given_names": null,
"family_name": null,
"gender": null,
"avatar": null,
"avatar_thumb": null,
"birthday": null,
"jwt": null
},
"relationships": {
"country": {
"data": null,
"links": {
"related": "http://api.dbljump.com/places/united-kingdom"
}
},
"images": {
"links": {
"related": "http://api.dbljump.com/users/3/images"
}
}
},
"links": {
"self": "http://api.dbljump.com/users/3"
},
"meta": {
"description": " is a member at Dbljump, the video game reference.",
"keywords": "member, , user, dbljump, video games, pc games, gaming",
"last_signed_in_at": null,
"last_sign_in_ip": null,
"sign_in_count": 0,
"activated_at": "2017-07-12T13:30:04.484Z",
"created_at": "2017-07-12T13:30:04.561Z",
"updated_at": "2017-07-12T13:30:04.561Z"
}
}
],
"links": {
"self": "http://api.dbljump.com/users?page%5Bnumber%5D=1&page%5Bsize%5D=2",
"next": "http://api.dbljump.com/users?page%5Bnumber%5D=2&page%5Bsize%5D=2",
"last": "http://api.dbljump.com/users?page%5Bnumber%5D=2&page%5Bsize%5D=2"
},
"meta": {
"total_items": 4
}
}
Retrieve all users. Automatically paginated. Admin-level authorization required.
- User authentication: required
- Authorization level: admin
HTTP request
GET /users
URL query parameters
| Parameter | Default | Description |
|---|---|---|
| fields[{record-type}] | All fields | Return only specified fields, e.g. ?fields[users]=username,avatar |
| filter[{field}] | All records | Filter search by field, e.g. ?filter[role]=admin |
| page[number] | 1 | Select the page number, e.g. ?page[number]=3, e.g. ?page[number]=3 |
| page[size] | 30 | Select the number of records per page, e.g. ?page[size]=20 |
Success HTTP response code
200 OK
Get single user
HTTP 200 response body
# GET /users/2
{
"data": {
"id": "2",
"type": "users",
"attributes": {
"email": "neil@example.com",
"username": "neil",
"role": "admin",
"given_names": "Neil",
"family_name": "Wheatley",
"gender": "male",
"avatar": "https://dbljumpheroku.s3.amazonaws.com/uploads/user_avatar/2/17071213.jpg",
"avatar_thumb": "https://dbljumpheroku.s3.amazonaws.com/uploads/user_avatar/2/th_17071213.jpg",
"birthday": "1980-02-14",
"jwt": null
},
"relationships": {
"country": {
"data": {
"id": "219",
"type": "places"
},
"links": {
"related": "http://api.dbljump.com/places/united-kingdom"
}
},
"images": {
"links": {
"related": "http://api.dbljump.com/users/2/images"
}
}
},
"links": {
"self": "http://api.dbljump.com/users/2"
},
"meta": {
"description": "Neil Wheatley is a member at Dbljump, the video game reference.",
"keywords": "neil, Neil Wheatley, user, dbljump, video games, pc games, gaming",
"last_signed_in_at": "2017-07-12T13:35:42.036Z",
"last_sign_in_ip": "86.12.129.15",
"sign_in_count": 1,
"activated_at": "2017-07-12T13:30:02.955Z",
"created_at": "2017-07-12T13:30:03.831Z",
"updated_at": "2017-07-12T13:35:42.112Z"
}
},
"included": [
{
"id": "219",
"type": "places",
"attributes": {
"name": "United Kingdom"
},
"links": {
"self": "http://api.dbljump.com/places/united-kingdom"
},
"meta": {
"description": "Find video game companies and games industry professionals from United Kingdom at Dbljump.",
"keywords": "United Kingdom, UK, GB, British, country, place, dbljump, video games, pc games, gaming",
"created_at": "2017-07-12T13:28:33.305Z",
"updated_at": "2017-07-12T13:28:33.305Z"
}
}
]
}
Retrieve a single existing user account record. Any user can retrive their own account. An admin-level user can retrieve any user account.
- User authentication: required
- Authorization level: Any, if retrieving own account. Admin if retriveing other user’s account.
HTTP request
GET /users/{id} (replace {id} with user record ID)
Success HTTP response code
200 OK
Response attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| string | Y | The user’s registered email address. | |
| username | string | Y | The user’s registered username. |
| role | string | Y | Authorization role. Can be member, editor or admin. See Role. |
| given_names | string | The user’s given names, e.g. ‘Jean Pierre’. | |
| family_name | string | The user’s family name, e.g. 'Blanc’. | |
| gender | string | Usually male or female, but can be any string. |
|
| avatar | string | URL of the user’s avatar image. | |
| avatar_thumb | string | URL of the 150x150 thumbnail avatar. | |
| birthday | date | E.g. '1977-12-19’ | |
| jwt | string | Always null for this endpoint. |
Relationships
| Association | Record type | Relationship type |
|---|---|---|
| country | places(countries) | belongs_to |
| images | images | has_many |
Meta
The meta section of the JSON response includes keywords, description, created_at, updated_at, last_signed_in_at, last_sign_in_ip, sign_in_count and activated_at attributes.
Register a new user
Request body |
POST /users
{
"data": {
"type": "users",
"attributes": {
"username": "new_user",
"email": "new@user.com",
"password": "password",
"password_confirmation": "password"
}
}
}
HTTP 201 response body
{
"data": {
"id": "5",
"type": "users",
"attributes": {
"email": "new@user.com",
"username": "new_user",
"role": "member",
"given_names": null,
"family_name": null,
"gender": null,
"avatar": null,
"avatar_thumb": null,
"birthday": null,
"jwt": null
},
"relationships": {
"country": {
"data": null,
"links": {
"related": "http://api.dbljump.com/places/united-kingdom"
}
},
"images": {
"links": {
"related": "http://api.dbljump.com/users/5/images"
}
}
},
"links": {
"self": "http://api.dbljump.com/users/5"
},
"meta": {
"description": " is a member at Dbljump, the video game reference.",
"keywords": "new_user, , user, dbljump, video games, pc games, gaming",
"last_signed_in_at": null,
"last_sign_in_ip": null,
"sign_in_count": 0,
"activated_at": null,
"created_at": "2017-07-12T13:39:16.554Z",
"updated_at": "2017-07-12T13:39:17.007Z"
}
}
}
Create a new user account. No authentication is required. Anyone can sign up for a new account with the default role of member.
- User authentication: not required
- Authorization level: N/A
HTTP request
POST /users
Request attributes
| Attribute | Type | Req’d | Description |
|---|---|---|---|
| username | string | Y | Must be unique. 2-24 chars. Letters, numbers and underscores only. See Username. |
| string | Y | Must be unique. Max 255 chars. Email format only. Downcased on save. See Email. | |
| password | string | Y | Any 8-24 chars. |
| password_confirmation | string | Y | Must match password. |
Username
Usernames must be unique, 2-24 chars, and include letters, numbers and underscores only. They must match the following regular expressions.
| Language | Regular expression |
|---|---|
| Ruby | /^a-zA-Z0-9*[a-zA-Z0-9]$/ |
| JavaScript | ^a-zA-Z0-9*[a-zA-Z0-9]$ |
Email addresses must be unique, no moe than 255 chars, and be in a valid email format. They must match the following regular expressions.
| Language | Regular expression |
|---|---|
| Ruby | /\A[\w+-.]+@[a-z\d-.]+.[a-z]+\z/i |
| JavaScript | ^[\w+-.]+@[a-z\d-.]+.[a-z]+$ |
Success HTTP response code
201 Created
Update a user account details
Request body |
PATCH /users/5
{
"data": {
"type": "users",
"id": "5",
"attributes": {
"email": "updated@email.com",
"username": "updated_username",
"password": "newpassword",
"password_confirmation": "newpassword",
"role": "editor",
"given_names": "Updated",
"family_name": "Name",
"gender": "male",
"birthday": "1985-07-20",
"base64_file": "data:image/gif;base64,R0lGODlhBQAFAIAAAAAAAP///ywAAAAABQAFAAACBIyPqVgAOw==",
"remove_avatar": "false"
},
"relationships": {
"country": {
"data": {
"id": "5",
"type": "places"
}
}
}
}
}
HTTP 200 response body
{
"data": {
"id": "5",
"type": "users",
"attributes": {
"email": "updated@email.com",
"username": "updated_username",
"role": "editor",
"given_names": "Updated",
"family_name": "Name",
"gender": "male",
"avatar": "https://dbljumpheroku.s3.amazonaws.com/uploads/user_avatar/5/1707121343.gif",
"avatar_thumb": "https://dbljumpheroku.s3.amazonaws.com/uploads/user_avatar/5/th_1707121343.gif",
"birthday": "1985-07-20",
"jwt": null
},
"relationships": {
"country": {
"data": {
"id": "5",
"type": "places"
},
"links": {
"related": "http://api.dbljump.com/places/andorra"
}
},
"images": {
"links": {
"related": "http://api.dbljump.com/users/5/images"
}
}
},
"links": {
"self": "http://api.dbljump.com/users/5"
},
"meta": {
"description": "Updated Name is a member at Dbljump, the video game reference.",
"keywords": "updated_username, Updated Name, user, dbljump, video games, pc games, gaming",
"last_signed_in_at": null,
"last_sign_in_ip": null,
"sign_in_count": 0,
"activated_at": null,
"created_at": "2017-07-12T13:39:16.554Z",
"updated_at": "2017-07-12T13:43:43.133Z"
}
},
"included": [
{
"id": "5",
"type": "places",
"attributes": {
"name": "Andorra"
},
"links": {
"self": "http://api.dbljump.com/places/andorra"
},
"meta": {
"description": "Find video game companies and games industry professionals from Andorra at Dbljump.",
"keywords": "Andorra, AD, Andorran, country, place, dbljump, video games, pc games, gaming",
"created_at": "2017-07-12T13:28:28.516Z",
"updated_at": "2017-07-12T13:28:28.516Z"
}
}
]
}
Update an existing user account. A user can update their own account. An admin can update any other non-admin account.
Admin-level authorization is required to update attributes role.
- User authentication: required
- Authorization level: Any if editing own account. Admin if editing other user’s account. Admin-level accounts can only be edited by the account owner.
HTTP request
PATCH /users/{id} (replace {id} with user record ID)
Request attributes
| Attribute | Type | Req’d | Description |
|---|---|---|---|
| username | string | Y | Must be unique. 2-24 chars. Letters, numbers and underscores only. See Username. |
| string | Y | Must be unique. Max 255 chars. Email format only. Downcased on save. See Email. | |
| role | string | Authorization level. Defaults to member. Can only be updated by admin users. See Role. |
|
| password | string | Y | New password. Any 8-24 chars. |
| password_confirmation | string | Y | Required if changing password. Must match password. |
| given_names | string | Any 1-20 chars. | |
| family_name | string | Any 1-20 chars. | |
| gender | string | Any 1-20 chars. Client could suggest ‘male’ or 'female’. | |
| birthday | date | Format 'YYYY-MM-DD’. Must not be a future date or > 100 years ago. | |
| base64_file | string | Base64 encoded JPEG, GIF or PNG. Any size (needs review). Use to upload avatar. |
|
| remove_avatar | boolean | Set as true to remove the avatar. |
Relationships
Check this section’s code example to see how to update these relationships.
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| country | belongs_to | places | A country record, e.g. the user’s birth country. |
Role
Dbljump has three kinds of users, representing three levels of authorization. They are defined by the value of the role attribute, which has three possible values.
| Value | Description |
|---|---|
| member | Ordinary users who sign up at Dbljump.com. No special privileges. |
| editor | Can edit and create records. Must complete an approval process. |
| admin | The highest level of authorization. Can do everything. |
Success HTTP response code
200 OK
Delete a user account
Delete an existing user account. A user can delete their own account. An admin can delete any other non-admin account.
- User authentication: required
- Authorization level: Any, if deleting own account. Admin if deleting other user’s account. Admin-level accounts can only be deleted by the account owner.
HTTP request
DELETE /users/{id} (replace {id} with user record ID)
Success HTTP response code
204 No Content
Errors
Errors specific to registering, updating and authenticating user accounts.
POST and PATCH errors
| HTTP code | Error code | Pointer | Title |
|---|---|---|---|
| 400 | USER_USERNAME_BLANK | username | Username is required. |
| 400 | USER_USERNAME_INVALID | username | Username can only contain letters, numbers, and underscores. |
| 400 | USER_USERNAME_TAKEN | username | Username has already been taken. |
| 400 | USER_USERNAME_TOO_SHORT | username | Username cannot be less than 2 characters. |
| 400 | USER_USERNAME_TOO_LONG | username | Username cannot be more than 24 characters. |
| 400 | USER_EMAIL_BLANK | Email is required. | |
| 400 | USER_EMAIL_INVALID | Email must be a valid address. | |
| 400 | USER_EMAIL_TAKEN | Email has already been taken. | |
| 400 | USER_EMAIL_TOO_LONG | Username cannot be more than 255 characters. | |
| 400 | USER_ROLE_INVALID | role | Role must be ‘member’, 'editor’, or 'admin’. |
| 400 | USER_PASSWORD_BLANK | password | Password is required. |
| 400 | USER_PASSWORD_TOO_SHORT | password | Password cannot be less than 8 characters. |
| 400 | USER_PASSWORD_TOO_LONG | password | Password cannot be more than 24 characters. |
| 400 | USER_PASSWORD_CONFIRMATION_CONFIRMATION | password_confirmation | Password and confirmation must match. |
| 400 | USER_GIVEN_NAMES_TOO_LONG | given_names | Given name cannot be more than 20 characters. |
| 400 | USER_FAMILY_NAME_TOO_LONG | family_name | Family name cannot be more than 20 characters. |
| 400 | USER_GENDER_TOO_LONG | gender | Gender cannot be more than 20 characters. |
| 400 | USER_BIRTHDAY_INCLUSION | birthday | Birthday must not be a future date, or over 100 years ago. |
| 400 | USER_COUNTRY_ID_INVALID | relationships/country/data/id | Country must be valid. |
| 400 | USER_BASE64_FILE_INVALID | base64_file | Base64 file must be in the correct format. |
Authentication errors
| HTTP code | Error code | Pointer | Title |
|---|---|---|---|
| 401 | USER_CREDENTIALS_INVALID | - | User not authorized. |
Users: authentications
Resources related to user sign-ins.
Sign in a user
Request body |
POST /users//authentications
{
"data": {
"type": "users",
"attributes": {
"email": "neil@example.com",
"password": "password",
"remember_me": "true"
}
}
}
HTTP 200 response body
{
"data": {
"id": "2",
"type": "users",
"attributes": {
"email": "neil@example.com",
"username": "neil",
"role": "admin",
"given_names": "Neil",
"family_name": "Wheatley",
"gender": "male",
"avatar": "null",
"avatar_thumb": null,
"birthday": "1980-02-14",
"jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoyLCJ1c2VyX3JvbGUiOiJhZG1pbiIsImV4cGlyeSI6IjIwMTctMDgtMTEgMTM6NDg6NDcgKzAwMDAifQ.Q8HJ0HNUDnKc776MAT4S-c7OqVtB20Uq8yQTxt_twqY"
},
"relationships": {
"country": {
"data": {
"id": "219",
"type": "places"
},
"links": {
"related": "http://api.dbljump.com/places/united-kingdom"
}
},
"images": {
"links": {
"related": "http://api.dbljump.com/users/2/images"
}
}
},
"links": {
"self": "http://api.dbljump.com/users/2"
},
"meta": {
"description": "Neil Wheatley is a member at Dbljump, the video game reference.",
"keywords": "neil, Neil Wheatley, user, dbljump, video games, pc games, gaming",
"last_signed_in_at": "2017-07-12T13:48:47.195Z",
"last_sign_in_ip": "86.12.129.15",
"sign_in_count": 2,
"activated_at": "2017-07-12T13:30:02.955Z",
"created_at": "2017-07-12T13:30:03.831Z",
"updated_at": "2017-07-12T13:48:47.255Z"
}
},
"included": [
{
"id": "219",
"type": "places",
"attributes": {
"name": "United Kingdom"
},
"links": {
"self": "http://api.dbljump.com/places/united-kingdom"
},
"meta": {
"description": "Find video game companies and games industry professionals from United Kingdom at Dbljump.",
"keywords": "United Kingdom, UK, GB, British, country, place, dbljump, video games, pc games, gaming",
"created_at": "2017-07-12T13:28:33.305Z",
"updated_at": "2017-07-12T13:28:33.305Z"
}
}
]
}
Sign in an existing user. With valid credentials, returns a JSON web token (JWT) used to authenticate user requests.
- User authentication: not required
- Authorization level: N/A
HTTP request
POST /users/authentications
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| string | Y | The user’s registered email. Max 255 chars. Must be email format. | |
| password | string | Y | The user’s password. |
| remember_me | boolean | JWT authentication token expires in 30 days if true, 1 day if false. Defaults to false. |
Success HTTP response code
200 OK
Response attributes
See the table in Get single user for all attribute details.
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| jwt | string | Y | The JSON web token used for authentication. Should be added to the HTTP Authorization header in further requests until user is signed out. |
Users: activations
Resources related to user account activations.
How activations work
A new user cannot sign in until they activate their account. Activations work like this:
- When a user signs up for a new account, they receive an email with a link they must follow to activate their account.
- The link contains an activation token and the user’s email. Clicking the link passes these to the API.
- On successful activation, the API sets the user attribute
activated_atto the current time, and returns a JWT the client can use to sign in the activated user. - If the user loses their activation email/link, or if it has expired, they can request a new one.
Send a new activation email
Request body |
POST /users/activations
{
"data": {
"type": "user_activations",
"attributes": {
"email": "user@example.com"
}
}
}
Send a new account activation link by email to a user’s registered email address.
- User authentication: not required
- Authorization level: N/A
HTTP request
POST /users/activations
Request attributes
| Attribute | Type | Req’d | Description |
|---|---|---|---|
| string | The user’s registered email address. |
Success HTTP response code
204 No Content
Errors
Errors specific to user activation link requests.
| HTTP code | Error code | Pointer | Title | Detail |
|---|---|---|---|---|
| 400 | USER_EMAIL_INVALID | User not found. | Invalid email address. | |
| 400 | USER_ALREADY_ACTIVATED | Cannot activate user. | User already activated. |
Activate a user account
Request body |
PATCH /users/activations/{activation_token}
{
"data": {
"type": "user_activations",
"id": "G2MnBqMJVF43tffPmKrmnw",
"attributes": {
"email": "user@example.com"
}
}
}
HTTP 200 response body
{
"data": {
"id": "5",
"type": "users",
"attributes": {
"email": "user@example.com",
"username": "new_user",
"role": "member",
"given_names": null,
"family_name": null,
"gender": null,
"avatar": null,
"avatar_thumb": null,
"birthday": null,
"jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjo1LCJ1c2VyX3JvbGUiOiJtZW1iZXIiLCJleHBpcnkiOiIyMDE3LTAzLTIyIDIzOjU1OjMyICswMDAwIn0.WqLjZkgyEh3Trv2U9q2PDBkbY4toWPJx02zbqTSn540"
},
"relationships": {
"country": {
"data": {
"id": "5",
"type": "places"
},,
"links": {
"related": "http://api.dbljump.com/places/countries/andorra"
}
},
"images": {
"links": {
"related": "http://api.dbljump.com/users/5/images"
}
}
},
"links": {
"self": "http://api.dbljump.com/users/5"
},
"meta": {
"last_signed_in_at": null,
"last_sign_in_ip": null,
"sign_in_count": 0,
"activated_at": "2017-03-21T23:55:32.873Z"
}
},
"included": [
{
"id": "5",
"type": "places",
"attributes": {
"subtype": "countries",
"slug": "andorra",
"name": "Andorra",
"short_name": null,
"formatted": "Andorra"
},
"links": {
"self": "http://localhost:3000/places/countries/united-kingdom"
}
}
]
}
Activate a user account. This endpoint should be triggered by an activation link sent to the user by email. The response includes a JWT authentication token, which can be used to automatically sign in the user.
- User authentication: not required
- Authorization level: N/A
HTTP request
PATCH /users/activations/{activation_token} (replace {activation_token} with the user’s activation token)
Request attributes
| Attribute | Type | Description |
|---|---|---|
| id | string | User activation token. Provided in the activation link. |
| string | The user’s registered email. Provided in the activation link. |
Success HTTP response code
200 OK
Response attributes
See the table in Get single user for all attribute details.
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| jwt | string | Y | The JSON web token used for authentication. Should be added to the HTTP Authorization header in further requests until user is signed out. |
Errors
Errors specific to user activations.
| HTTP code | Error code | Pointer | Title | Detail |
|---|---|---|---|---|
| 400 | USER_ACTIVATION_INVALID | N/A | Cannot activate user. | Invalid user or activation token. |
| 400 | USER_ALREADY_ACTIVATED | Cannot activate user. | User already activated. |
Users: passwords
Resources related to user passwords.
If a user needs a new password, they can:
- Enter their registered email address and receive a password-reset link by email
- Set a new password after clicking the password-reset email
Request a password-reset link
Request body |
POST /users/passwords
{
"data": {
"type": "user_passwords",
"attributes": {
"email": "user@example.com"
}
}
}
A user can request an email with a link to reset their password.
- User authentication: not required
- Authorization level: N/A
HTTP request
POST /users/passwords
Request attributes
| Attribute | Type | Description |
|---|---|---|
| string | The user’s registered email. Required. Max 255 chars. Must be email format. |
Success HTTP response code
204 No Content
Errors
Errors specific to user password reset link requests.
| HTTP code | Error code | Pointer | Title | Detail |
|---|---|---|---|---|
| 400 | USER_EMAIL_INVALID | User not found. | Invalid email address. | |
| 400 | USER_ACTIVATION_REQUIRED | User activation required. | User not yet activated. |
Set a new user password
Request body |
PATCH /users/passwords/{password_reset_token}
{
"data": {
"type": "user_passwords",
"id": "Bml5G2MnBqMJVFacD243tffPmKrmnwX",
"attributes": {
"email": "user@example.com",
"password": "new_password",
"password_confirmation": "new_password"
}
}
}
A user can set a new password after following a reset-password link. The reset token in the link expires after 2 hours.
- User authentication: not required
- Authorization level: N/A
HTTP request
PATCH /users/passwords/{password_reset_token} (replace {password_reset_token} with the password reset token)
Request attributes
| Attribute | Type | Description |
|---|---|---|
| id | string | The password reset token, available in the password reset link URL. Required. |
| string | The user’s registered email address, available in the password reset link URL. Required. | |
| password | string | New password. Required. Any 8-24 chars. |
| password_confirmation | string | Required. Must match password. |
Success HTTP response code
204 No Content
Errors
Errors specific to user password resets.
| HTTP code | Error code | Pointer | Title | Detail |
|---|---|---|---|---|
| 400 | USER_EMAIL_INVALID | User not found. | Invalid email address. | |
| 400 | USER_ACTIVATION_REQUIRED | User activation required. | User not yet activated. | |
| 400 | USER_PASSWORD_TOKEN_INVALID | password_reset_token | Cannot reset user password. | Password reset token invalid. |
| 400 | USER_PASSWORD_TOKEN_EXPIRED | password_reset_token | Cannot reset user password. | Password reset token expired. |
| 400 | USER_PASSWORD_BLANK | password | Password is required. | |
| 400 | USER_PASSWORD_TOO_SHORT | password | Password cannot be less than 8 characters. | |
| 400 | USER_PASSWORD_TOO_LONG | password | Password cannot be more than 24 characters. | |
| 400 | USER_PASSWORD_CONFIRMATION_CONFIRMATION | password_confirmation | Password and confirmation must match. |
Places
Resources related to places.
Kinds of place
There are four kinds of place, determined by the value of the kind attribute.
| Kind | Description | Relationships |
|---|---|---|
| Region | A group of countries | Has many country children. |
| Country | A country, e.g. Japan | Belongs to many regions. Has many subdivision children. |
| Subdivision | An administrative area of a country, e.g. a county or state | Belongs to a parent country. Has many locality children. |
| Locality | A city or town | Belongs to a parent subdivision. |
Request attributes
See Create a new place record and Update a place record.
Response attributes
See Get single place.
Get all places
Response body |
HTTP 200
# GET /places?page[size]=2&filter[kind]=subdivision
{
"data": [
{
"id": "2237",
"type": "places",
"attributes": {
"kind": "subdivision",
"slug": "sabha-libya",
"name": "Sabha",
"formatted": "Sabha, Libya",
"short_name": null,
"also_known_as": [],
"latitude": null,
"longitude": null,
"iso_code": null
},
"relationships": {
"parent": {
"data": {
"id": "117",
"type": "places"
},
"links": {
"related": "http://api.dbljump.com/places/libya"
}
},
"children": {
"data": [],
"links": {
"related": "http://api.dbljump.com/places/sabha-libya/children"
}
},
"regions": {
"data": [
{
"id": "236",
"type": "places"
}
],
"links": {
"related": "http://api.dbljump.com/places/sabha-libya/regions"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://api.dbljump.com/users/1"
}
}
},
"links": {
"self": "http://api.dbljump.com/places/sabha-libya"
},
"meta": {
"description": "Find video game companies and games industry professionals from Sabha, Libya at Dbljump.",
"keywords": "Sabha, Libya, state, county, place, dbljump, video games, pc games, gaming",
"created_at": "2017-07-12T13:29:41.294Z",
"updated_at": "2017-07-12T13:29:41.294Z"
}
},
{
"id": "240",
"type": "places",
"attributes": {
"kind": "subdivision",
"slug": "all-niue",
"name": "All",
"formatted": "All, Niue",
"short_name": null,
"also_known_as": [],
"latitude": null,
"longitude": null,
"iso_code": null
},
"relationships": {
"parent": {
"data": {
"id": "151",
"type": "places"
},
"links": {
"related": "http://api.dbljump.com/places/niue"
}
},
"children": {
"data": [],
"links": {
"related": "http://api.dbljump.com/places/all-niue/children"
}
},
"regions": {
"data": [],
"links": {
"related": "http://api.dbljump.com/places/all-niue/regions"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://api.dbljump.com/users/1"
}
}
},
"links": {
"self": "http://api.dbljump.com/places/all-niue"
},
"meta": {
"description": "Find video game companies and games industry professionals from All, Niue at Dbljump.",
"keywords": "All, Niue, state, county, place, dbljump, video games, pc games, gaming",
"created_at": "2017-07-12T13:28:34.868Z",
"updated_at": "2017-07-12T13:28:34.868Z"
}
}
],
"links": {
"self": "http://api.dbljump.com/places?filter%5Bkind%5D=subdivision&page%5Bnumber%5D=1&page%5Bsize%5D=2",
"next": "http://api.dbljump.com/places?filter%5Bkind%5D=subdivision&page%5Bnumber%5D=2&page%5Bsize%5D=2",
"last": "http://api.dbljump.com/places?filter%5Bkind%5D=subdivision&page%5Bnumber%5D=1321&page%5Bsize%5D=2"
},
"meta": {
"total_items": 2641
}
}
Retrieve all places. Automatically paginated.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /places
URL query parameters
| Parameter | Default | Description |
|---|---|---|
| fields[{record-type}] | All fields | Return only specified fields, e.g. ?fields[places]=name,formatted |
| filter[{field}] | All records | Filter search by field, e.g. ?filter[kind]=country,region |
| page[number] | 1 | Select the page number, e.g. ?page[number]=3 |
| page[size] | 30 | Select the number of records per page, e.g. ?page[size]=20 |
Success HTTP response code
200 OK
Get single place
Response body |
HTTP 200
# GET /places/united-states
{
"data": {
"id": "220",
"type": "places",
"attributes": {
"kind": "country",
"slug": "united-states",
"name": "United States",
"formatted": "United States",
"short_name": "USA",
"also_known_as": [
"'United States of America'"
],
"latitude": 38,
"longitude": -97,
"iso_code": "US"
},
"relationships": {
"parent": {
"data": null
},
"children": {
"data": [
{
"id": "2734",
"type": "places"
},
{
"id": "2733",
"type": "places"
},
{
"id": "2732",
"type": "places"
},
{
"id": "2731",
"type": "places"
},
{
"id": "2730",
"type": "places"
},
{
"id": "2729",
"type": "places"
},
{
"id": "2728",
"type": "places"
},
{
"id": "2727",
"type": "places"
},
{
"id": "2726",
"type": "places"
},
{
"id": "2725",
"type": "places"
},
{
"id": "2724",
"type": "places"
},
{
"id": "2723",
"type": "places"
},
{
"id": "2722",
"type": "places"
},
{
"id": "2721",
"type": "places"
},
{
"id": "2720",
"type": "places"
},
{
"id": "2719",
"type": "places"
},
{
"id": "2718",
"type": "places"
},
{
"id": "2717",
"type": "places"
},
{
"id": "2716",
"type": "places"
},
{
"id": "2715",
"type": "places"
},
{
"id": "2714",
"type": "places"
},
{
"id": "2713",
"type": "places"
},
{
"id": "2712",
"type": "places"
},
{
"id": "2711",
"type": "places"
},
{
"id": "2710",
"type": "places"
},
{
"id": "2709",
"type": "places"
},
{
"id": "2708",
"type": "places"
},
{
"id": "2707",
"type": "places"
},
{
"id": "2706",
"type": "places"
},
{
"id": "2705",
"type": "places"
},
{
"id": "2704",
"type": "places"
},
{
"id": "2703",
"type": "places"
},
{
"id": "2702",
"type": "places"
},
{
"id": "2701",
"type": "places"
},
{
"id": "2700",
"type": "places"
},
{
"id": "2699",
"type": "places"
},
{
"id": "2698",
"type": "places"
},
{
"id": "2697",
"type": "places"
},
{
"id": "2696",
"type": "places"
},
{
"id": "2695",
"type": "places"
},
{
"id": "2694",
"type": "places"
},
{
"id": "2693",
"type": "places"
},
{
"id": "2692",
"type": "places"
},
{
"id": "2691",
"type": "places"
},
{
"id": "2690",
"type": "places"
},
{
"id": "2689",
"type": "places"
},
{
"id": "2688",
"type": "places"
},
{
"id": "2687",
"type": "places"
},
{
"id": "2686",
"type": "places"
},
{
"id": "2685",
"type": "places"
},
{
"id": "2684",
"type": "places"
},
{
"id": "2683",
"type": "places"
},
{
"id": "2682",
"type": "places"
},
{
"id": "2681",
"type": "places"
},
{
"id": "2680",
"type": "places"
},
{
"id": "2679",
"type": "places"
},
{
"id": "2678",
"type": "places"
},
{
"id": "2677",
"type": "places"
},
{
"id": "2676",
"type": "places"
},
{
"id": "2675",
"type": "places"
}
],
"links": {
"related": "http://localhost:3000/places/220/children"
},
"meta": {
"total": 60
}
},
"regions": {
"data": [
{
"id": "240",
"type": "places"
},
{
"id": "238",
"type": "places"
},
{
"id": "233",
"type": "places"
}
],
"links": {
"related": "http://localhost:3000/places/220/regions"
},
"meta": {
"total": 3
}
},
"origin_articles": {
"data": [
{
"id": "55",
"type": "people"
},
{
"id": "57",
"type": "people"
},
{
"id": "64",
"type": "people"
},
{
"id": "56",
"type": "people"
},
{
"id": "67",
"type": "people"
}
]
},
"latest_articles": {
"data": []
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://localhost:3000/users/1"
}
}
},
"links": {
"self": "http://localhost:3000/places/220"
},
"meta": {
"created_at": "2017-08-25T08:31:18.461Z",
"updated_at": "2017-08-25T08:31:18.461Z",
"meta_description": "Find video game companies and games industry professionals from United States at Dbljump.",
"meta_keywords": "United States, USA, 'United States of America', US, American, country, place, dbljump, video games, pc games, gaming",
"total_children": 60,
"total_regions": 3,
"total_origin_articles": 5,
"total_latest_articles": 0
}
}
}
Retrieve a single place record. Places are publicly available. No sign-in is required.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /places/{slug} (replace {slug} with place record slug)
Success HTTP response code
200 OK
Response attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| kind | string | Y | The place classification. Either ‘region’, 'country’, 'subdivision’, or 'locality’. |
| slug | string | Y | A record ID based on the formatted name, e.g. 'glasgow-scotland-united-kingdom’. |
| name | string | Y | The place name, e.g. 'Glasow’ or 'Scotland’ or 'United Kingdom’ or 'Europe’. |
| formatted | string | Y | The full name including parent places, e.g. 'Glasgow, Scotland, United Kingdom’. |
| short_name | string | A commonly-used short name, e.g. 'USA’, 'UK’, 'CA’, 'LA’. | |
| also_known_as | array | An array of aliases, e.g. ['Nippon', '日本'] for Japan. |
|
| latitude | number | Geographic coordinate. | |
| longitude | number | Geographic coordinate. | |
| iso_code | string | Countries only | 2-character ISO 3166-1 code. Countries only. |
Relationships
| Name | Record type | Relationship type | Description |
|---|---|---|---|
| created_by | users | belongs_to | The user that created the record. |
| parent | places | belongs_to | The country a subdivision is in; he subdivision a locality is in; null for countries and regions. |
| children | places | has_many | The countries inside a region; the subdivisions inside a country; the localities inside a subdivision; null for localities. |
| regions | places | has_many | The regions that a country, subdivision, or locality belong to. Null for regions. |
| origin_articles | polymorphic | has_many | Companies founded or people born in this place. |
| latest_articles | polymorphic | has_many | Companies HQ’d or people who died in this place. |
Meta
The meta section of the JSON response includes keywords, description, created_at and updated_at attributes.
Create a new place record
Request body |
POST /places
{
"data": {
"type": "places",
"attributes": {
"kind": "subdivision",
"name": "Maryland",
"short_name": "MD",
"also_known_as": ["Old Line State", "Chesapeake Bay State"],
"latitude": "38.0",
"longitude": "-77.0",
"iso_code": ""
},
"relationships": {
"parent": {
"data": {
"id": "220",
"type": "places"
}
}
}
}
}
Response body |
HTTP 201
{
"data": {
"id": "2939",
"type": "places",
"attributes": {
"kind": "subdivision",
"slug": "maryland-united-states",
"name": "Maryland",
"formatted": "Maryland, United States",
"short_name": "MD",
"also_known_as": [
"Old Line State",
"Chesapeake Bay State"
],
"latitude": 38,
"longitude": -77,
"iso_code": ""
},
"relationships": {
"parent": {
"data": {
"id": "220",
"type": "places"
},
"links": {
"related": "http://api.dbljump.com/places/united-states"
}
},
"children": {
"data": [],
"links": {
"related": "http://api.dbljump.com/places/maryland-united-states/children"
}
},
"regions": {
"data": [
{
"id": "238",
"type": "places"
},
{
"id": "233",
"type": "places"
}
],
"links": {
"related": "http://api.dbljump.com/places/maryland-united-states/regions"
}
},
"created_by": {
"data": {
"id": "2",
"type": "users"
},
"links": {
"related": "http://api.dbljump.com/users/2"
}
}
},
"links": {
"self": "http://api.dbljump.com/places/maryland-united-states"
},
"meta": {
"description": "Find video game companies and games industry professionals from Maryland, United States at Dbljump.",
"keywords": "Maryland, United States, MD, Old Line State, Chesapeake Bay State, state, county, place, dbljump, video games, pc games, gaming",
"created_at": "2017-07-12T13:54:03.802Z",
"updated_at": "2017-07-12T13:54:03.802Z"
}
},
"included": [
{
"id": "2",
"type": "users",
"attributes": {
"username": "neil",
"role": "admin",
"given_names": "Neil",
"family_name": "Wheatley",
"avatar": "https://dbljumpheroku.s3.amazonaws.com/uploads/user_avatar/2/1707121330.jpg"
},
"links": {
"self": "http://api.dbljump.com/users/2"
},
"meta": {
"description": "Neil Wheatley is a member at Dbljump, the video game reference.",
"keywords": "neil, Neil Wheatley, user, dbljump, video games, pc games, gaming",
"last_signed_in_at": "2017-07-12T13:48:47.195Z",
"last_sign_in_ip": "86.12.129.15",
"sign_in_count": 2,
"activated_at": "2017-07-12T13:30:02.955Z",
"created_at": "2017-07-12T13:30:03.831Z",
"updated_at": "2017-07-12T13:48:47.255Z"
}
}
]
}
Create a new place record. Use the kind attribute to set whether the place is a region (i.e. a group of countries), country, subdivision (i.e. a state or county), or locality (i.e. a town or city). Admin-level authorization required, or editor-level if kind == 'locality'.
- User authentication: required
- Authorization level: admin for
region,countryorsubdivision; editor forlocalityrecords.
HTTP request
POST /places
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| kind | string | Y | Must be ‘region’, 'country’, 'subdivision’, or 'locality’. |
| name | string | Y | Unique. 2-50 chars. English-language common name, e.g. 'United States’. |
| short_name | string | Unique. 2-20 chars. Common short name, e.g. 'USA’. | |
| also_known_as | array | Members must be 2-50 char strings. E.g. ['US', 'America']. |
|
| latitude | number | Between -90 and 90. | |
| longitude | number | Between -180 and 180. | |
| iso_code | string | Country-only | Unique. 2 chars. ISO 3166-1 country code. |
Relationships
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| parent | belongs_to | Subdivisions and localities only | places | The country a subdivision is in; the subdivision a locality is in. |
| children | has_many | places | The countries inside a region. |
Success HTTP response code
201 Created
Update a place record
Request body |
PATCH /places/europe
{
"data": {
"type": "places",
"id": "europe",
"attributes": {
"name": "New Name",
"short_name": "Short",
"also_known_as": ["Edited Region", "Renamed Region"],
"latitude": "54.5",
"longitude": "15.3"
},
"relationships": {
"children": {
"data": [
{ "type": "places", "id": "219" },
{ "type": "places", "id": "71" },
{ "type": "places", "id": "75" }
]
}
}
}
}
Response body |
HTTP 200
{
"data": {
"id": "234",
"type": "places",
"attributes": {
"kind": "region",
"slug": "new-name",
"name": "New Name",
"formatted": "New Name",
"short_name": "Short",
"also_known_as": [
"Edited Region",
"Renamed Region"
],
"latitude": 54.5,
"longitude": 15.3,
"iso_code": null
},
"relationships": {
"parent": {
"data": null,
"links": {
"related": "http://api.dbljump.com/places/united-states"
}
},
"children": {
"data": [
{
"id": "71",
"type": "places"
},
{
"id": "75",
"type": "places"
},
{
"id": "219",
"type": "places"
}
],
"links": {
"related": "http://api.dbljump.com/places/new-name/children"
}
},
"regions": {
"data": null,
"links": {
"related": "http://api.dbljump.com/places/new-name/regions"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://api.dbljump.com/users/1"
}
}
},
"links": {
"self": "http://api.dbljump.com/places/new-name"
},
"meta": {
"description": "Find video game companies and games industry professionals from New Name at Dbljump.",
"keywords": "New Name, Short, Edited Region, Renamed Region, place, geography, dbljump, video games, pc games, gaming",
"created_at": "2017-07-12T13:28:33.655Z",
"updated_at": "2017-07-12T13:57:30.480Z"
}
},
"included": [
{
"id": "1",
"type": "users",
"attributes": {
"username": "tikithekiwi",
"role": "admin",
"given_names": "Tiki",
"family_name": "the Kiwi",
"avatar": null
},
"links": {
"self": "http://api.dbljump.com/users/1"
},
"meta": {
"description": "Tiki the Kiwi is a member at Dbljump, the video game reference.",
"keywords": "tikithekiwi, Tiki the Kiwi, user, dbljump, video games, pc games, gaming",
"last_signed_in_at": null,
"last_sign_in_ip": null,
"sign_in_count": 0,
"activated_at": "2017-07-12T13:28:27.875Z",
"created_at": "2017-07-12T13:28:27.985Z",
"updated_at": "2017-07-12T13:28:27.985Z"
}
}
]
}
Update an existing place record. The user must be an admin, except for locality records that were created by the current user. The kind attribute cannot be changed.
- User authentication: required
- Authorization level: admin, except for
localityrecords that were created by the current user.
HTTP request
PATCH /places/{slug} (replace {slug} with place record slug)
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| name | string | Y | Unique. 2-250 chars. English-language common name, e.g. ‘United States’. |
| short_name | string | Unique. 2-20 chars. Common short name, e.g. 'USA’. | |
| also_known_as | array | Members must be 2-50 char strings. E.g. ['US', 'America']. |
|
| latitude | number/float | Between -90 and 90. | |
| longitude | number/float | Between -180 and 180. | |
| iso_code | string | Country-only | Unique. 2 chars. ISO 3166-1 country code. |
Relationships
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| parent | belongs_to | Subdivisions and localities only | places | The country a subdivision is in; the subdivision a locality is in. |
| children | has_many | places | The countries inside a region. | |
| origin_articles | has_many | polymorphic | Companies founded or people born in this place. | |
| latest_articles | has_many | polymorphic | Companies HQ’d or people who died in this place. |
Success HTTP response code
200 OK
Delete a place record
Delete an existing place record. Admin-level authorization required.
- User authentication: required
- Authorization level: admin
HTTP request
DELETE /places/{slug} (replace {slug} with place record slug)
Success HTTP response code
204 No Content
Get all place children
Response body |
HTTP 200
# GET /places/united-states/children?page[size]=3
{
"data": [
{
"id": "329",
"type": "places",
"attributes": {
"kind": "subdivision",
"slug": "alabama-united-states",
"name": "Alabama",
"formatted": "Alabama, United States",
"short_name": null,
"also_known_as": [],
"latitude": 32.3182314,
"longitude": -86.902298,
"iso_code": null
},
"relationships": {
"parent": {
"data": {
"id": "220",
"type": "places"
},
"links": {
"related": "http://api.dbljump.com/places/united-states"
}
},
"children": {
"data": [],
"links": {
"related": "http://api.dbljump.com/places/alabama-united-states/children"
}
},
"regions": {
"data": [
{
"id": "238",
"type": "places"
},
{
"id": "233",
"type": "places"
}
],
"links": {
"related": "http://api.dbljump.com/places/alabama-united-states/regions"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://api.dbljump.com/users/1"
}
}
},
"links": {
"self": "http://api.dbljump.com/places/alabama-united-states"
},
"meta": {
"description": "Find video game companies and games industry professionals from Alabama, United States at Dbljump.",
"keywords": "Alabama, United States, state, county, place, dbljump, video games, pc games, gaming",
"created_at": "2017-07-12T13:28:36.800Z",
"updated_at": "2017-07-12T13:28:36.800Z"
}
},
{
"id": "335",
"type": "places",
"attributes": {
"kind": "subdivision",
"slug": "alaska-united-states",
"name": "Alaska",
"formatted": "Alaska, United States",
"short_name": null,
"also_known_as": [],
"latitude": 64.2008413,
"longitude": -149.4936733,
"iso_code": null
},
"relationships": {
"parent": {
"data": {
"id": "220",
"type": "places"
},
"links": {
"related": "http://api.dbljump.com/places/united-states"
}
},
"children": {
"data": [],
"links": {
"related": "http://api.dbljump.com/places/alaska-united-states/children"
}
},
"regions": {
"data": [
{
"id": "238",
"type": "places"
},
{
"id": "233",
"type": "places"
}
],
"links": {
"related": "http://api.dbljump.com/places/alaska-united-states/regions"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://api.dbljump.com/users/1"
}
}
},
"links": {
"self": "http://api.dbljump.com/places/alaska-united-states"
},
"meta": {
"description": "Find video game companies and games industry professionals from Alaska, United States at Dbljump.",
"keywords": "Alaska, United States, state, county, place, dbljump, video games, pc games, gaming",
"created_at": "2017-07-12T13:28:36.924Z",
"updated_at": "2017-07-12T13:28:36.924Z"
}
},
{
"id": "398",
"type": "places",
"attributes": {
"kind": "subdivision",
"slug": "american-samoa-united-states",
"name": "American Samoa",
"formatted": "American Samoa, United States",
"short_name": null,
"also_known_as": [],
"latitude": 21.3239718,
"longitude": -157.876498,
"iso_code": null
},
"relationships": {
"parent": {
"data": {
"id": "220",
"type": "places"
},
"links": {
"related": "http://api.dbljump.com/places/united-states"
}
},
"children": {
"data": [],
"links": {
"related": "http://api.dbljump.com/places/american-samoa-united-states/children"
}
},
"regions": {
"data": [
{
"id": "238",
"type": "places"
},
{
"id": "233",
"type": "places"
}
],
"links": {
"related": "http://api.dbljump.com/places/american-samoa-united-states/regions"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://api.dbljump.com/users/1"
}
}
},
"links": {
"self": "http://api.dbljump.com/places/american-samoa-united-states"
},
"meta": {
"description": "Find video game companies and games industry professionals from American Samoa, United States at Dbljump.",
"keywords": "American Samoa, United States, state, county, place, dbljump, video games, pc games, gaming",
"created_at": "2017-07-12T13:28:39.075Z",
"updated_at": "2017-07-12T13:28:39.075Z"
}
}
],
"links": {
"self": "http://api.dbljump.com/places/united-states/children?page%5Bnumber%5D=1&page%5Bsize%5D=3",
"next": "http://api.dbljump.com/places/united-states/children?page%5Bnumber%5D=2&page%5Bsize%5D=3",
"last": "http://api.dbljump.com/places/united-states/children?page%5Bnumber%5D=20&page%5Bsize%5D=3"
},
"meta": {
"total_items": 60
}
}
Retrieve all places that belong to a given places, i.e. countries that belong to a region; subdivisions that belong to a country; and localities that belong to a subdivision. Returns a 404 error for localities, which do not have children. Automatically paginated.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /places/{place-slug}/children
URL query parameters
| Parameter | Default | Description |
|---|---|---|
| fields[{record-type}] | All fields | Return only specified fields, e.g. ?fields[places]=name,formatted |
| filter[{field}] | All records | Filter search by field, e.g. ?filter[name]=Tokyo Prefecture |
| page[number] | 1 | Select the page number, e.g. ?page[number]=3 |
| page[size] | 30 | Select the number of records per page, e.g. ?page[size]=20 |
Success HTTP response code
200 OK
Get all place regions
Response body |
HTTP 200
# GET /places/united-states/regions
{
"data": [
{
"id": "238",
"type": "places",
"attributes": {
"kind": "region",
"slug": "us-and-canada",
"name": "US and Canada",
"formatted": "US and Canada",
"short_name": "US&Ca",
"also_known_as": [],
"latitude": null,
"longitude": null,
"iso_code": null
},
"relationships": {
"parent": {
"data": null,
"links": {
"related": "http://api.dbljump.com/places/niue"
}
},
"children": {
"data": [
{
"id": "36",
"type": "places"
},
{
"id": "220",
"type": "places"
}
],
"links": {
"related": "http://api.dbljump.com/places/us-and-canada/children"
}
},
"regions": {
"data": null,
"links": {
"related": "http://api.dbljump.com/places/us-and-canada/regions"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://api.dbljump.com/users/1"
}
}
},
"links": {
"self": "http://api.dbljump.com/places/us-and-canada"
},
"meta": {
"description": "Find video game companies and games industry professionals from US and Canada at Dbljump.",
"keywords": "US and Canada, US&Ca, place, geography, dbljump, video games, pc games, gaming",
"created_at": "2017-07-12T13:28:33.735Z",
"updated_at": "2017-07-12T13:28:33.735Z"
}
},
{
"id": "233",
"type": "places",
"attributes": {
"kind": "region",
"slug": "north-america",
"name": "North America",
"formatted": "North America",
"short_name": "NA",
"also_known_as": [],
"latitude": null,
"longitude": null,
"iso_code": null
},
"relationships": {
"parent": {
"data": null,
"links": {
"related": "http://api.dbljump.com/places/niue"
}
},
"children": {
"data": [
{
"id": "36",
"type": "places"
},
{
"id": "133",
"type": "places"
},
{
"id": "220",
"type": "places"
}
],
"links": {
"related": "http://api.dbljump.com/places/north-america/children"
}
},
"regions": {
"data": null,
"links": {
"related": "http://api.dbljump.com/places/north-america/regions"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://api.dbljump.com/users/1"
}
}
},
"links": {
"self": "http://api.dbljump.com/places/north-america"
},
"meta": {
"description": "Find video game companies and games industry professionals from North America at Dbljump.",
"keywords": "North America, NA, place, geography, dbljump, video games, pc games, gaming",
"created_at": "2017-07-12T13:28:33.636Z",
"updated_at": "2017-07-12T13:28:33.636Z"
}
}
],
"links": {},
"meta": {
"total_items": 2
}
}
Retrieve all regions that a given country belongs to. Returns a 404 error for regions, subdivision, and localities. Automatically paginated.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /places/{place-slug}/regions
URL query parameters
| Parameter | Default | Description |
|---|---|---|
| fields[{record-type}] | All fields | Return only specified fields, e.g. ?fields[places]=formatted |
| filter[{field}] | All records | Filter search by field, e.g. ?filter[name]=Asia |
| page[number] | 1 | Select the page number, e.g. ?page[number]=3 |
| page[size] | 30 | Select the number of records per page, e.g. ?page[size]=20 |
Success HTTP response code
200 OK
Errors
Errors specific to creating and updating place records.
| HTTP code | Error code | Pointer | Title |
|---|---|---|---|
| 400 | PLACE_KIND_BLANK | kind | Kind is required. |
| 400 | PLACE_KIND_INCLUSION | kind | Kind must be ‘region’, 'country’, 'subdivision’ or 'locality’. |
| 400 | PLACE_KIND_PRESENT | kind | Kind cannot be changed. |
| 400 | PLACE_NAME_BLANK | name | Name is required. |
| 400 | PLACE_NAME_TAKEN | name | Name has already been taken. |
| 400 | PLACE_NAME_TOO_SHORT | name | Name must be at least 2 characters. |
| 400 | PLACE_NAME_TOO_LONG | name | Name cannot be more than 50 characters. |
| 400 | PLACE_SHORT_NAME_TAKEN | short_name | Short name has already been taken. |
| 400 | PLACE_SHORT_NAME_TOO_SHORT | short_name | Short name must be at least 2 characters. |
| 400 | PLACE_SHORT_NAME_TOO_LONG | short_name | Short name cannot be more than 20 characters. |
| 400 | PLACE_ALSO_KNOWN_AS_TOO_SHORT | also_known_as | Also-known-as tags must be at least 2 characters. |
| 400 | PLACE_ALSO_KNOWN_AS_TOO_LONG | also_known_as | Also-known-as tags cannot be more than 50 characters. |
| 400 | PLACE_LATITUDE_GREATER_THAN_OR_EQUAL_TO | latitude | Latitude must be between -90 and 90. |
| 400 | PLACE_LATITUDE_LESS_THAN_OR_EQUAL_TO | latitude | Latitude must be between -90 and 90. |
| 400 | PLACE_LONGITUDE_GREATER_THAN_OR_EQUAL_TO | longitude | Longitude must be between -180 and 180. |
| 400 | PLACE_LONGITUDE_LESS_THAN_OR_EQUAL_TO | longitude | Longitude must be between -180 and 180. |
| 400 | PLACE_ISO_CODE_BLANK | iso_code | ISO code is required for country records. |
| 400 | PLACE_ISO_CODE_PRESENT | iso_code | ISO code is only used by country records. |
| 400 | PLACE_ISO_CODE_TAKEN | iso_code | There’s already a country with that ISO code. |
| 400 | PLACE_ISO_CODE_TOO_SHORT | iso_code | ISO code must be 2 characters long. |
| 400 | PLACE_ISO_CODE_TOO_LONG | iso_code | ISO code must be 2 characters long. |
| 400 | PLACE_PARENT_BLANK | relationships/parent/data/id | Parent is required for subdivisions and localities. |
| 400 | PLACE_PARENT_PRESENT | relationships/parent/data/id | Regions and countries cannot have a parent place. |
| 400 | PLACE_PARENT_INVALID | relationships/parent/data/id | That parent place ID isn’t valid. |
| 400 | PLACE_CHILDREN_PRESENT | relationships/parent/data/id | Localities cannot cannot contain child places. |
| 400 | PLACE_CHILDREN_INVALID | relationships/parent/data/id | At least one of the child place IDs isn’t valid. |
Media: Images
Resources related to images.
An image record includes the URL of an image stored on Amazon S3, plus metadata about the image. An image can be associated with many articles (i.e. games, companies and people).
Request attributes
See Upload a new image and Update an image record.
Response attributes
See Get single image
Get all images
Response body |
HTTP 200
# GET /media/images?page[size]=2
{
"data": [
{
"id": "1",
"type": "images",
"attributes": {
"kind": "photo",
"slug": "nintendo-office-photo",
"original": "https://dbljumpheroku.s3.amazonaws.com/uploads/images/1/nintendo-hq-kyoto-2006.jpg",
"thumb": "https://dbljumpheroku.s3.amazonaws.com/uploads/images/1/th_nintendo-hq-kyoto-2006.jpg",
"title": "Nintendo office",
"description": "Head Quarters of Nintendo, Minami-ku, Kyoto, Japan. The picture was taken by the poster in February, 2006.",
"year": 2006,
"date": "2006-02-18",
"usage_type": "licensed",
"usage_license_code": "cc_by_sa_3_0",
"usage_license_name": "Creative Commons Attribution-ShareAlike 3.0",
"usage_license_url": "https://creativecommons.org/licenses/by-sa/3.0",
"attributed_name": "Moja~commonswiki",
"attributed_url": "",
"source_url": "https://en.wikipedia.org/wiki/Nintendo#/media/File:Nintendo_office.jpg"
},
"relationships": {
"uploaded_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://api.dbljump.com/users/1"
}
},
"place": {
"data": null,
"links": {
"related": "http://api.dbljump.com/places/afghanistan"
}
}
},
"links": {
"self": "http://api.dbljump.com/media/images/nintendo-office-photo"
}
},
{
"id": "2",
"type": "images",
"attributes": {
"kind": "photo",
"slug": "mario-figure-photo",
"original": "https://dbljumpheroku.s3.amazonaws.com/uploads/images/2/mario-figure.jpg",
"thumb": "https://dbljumpheroku.s3.amazonaws.com/uploads/images/2/th_mario-figure.jpg",
"title": "Mario figure",
"description": "",
"year": 2016,
"date": "2016-07-30",
"usage_type": "free",
"usage_license_code": null,
"usage_license_name": null,
"usage_license_url": null,
"attributed_name": null,
"attributed_url": null,
"source_url": ""
},
"relationships": {
"uploaded_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://api.dbljump.com/users/1"
}
},
"place": {
"data": null,
"links": {
"related": "http://api.dbljump.com/places/afghanistan"
}
}
},
"links": {
"self": "http://api.dbljump.com/media/images/mario-figure-photo"
}
}
],
"links": {
"self": "http://api.dbljump.com/media/images?page%5Bnumber%5D=1&page%5Bsize%5D=2",
"next": "http://api.dbljump.com/media/images?page%5Bnumber%5D=2&page%5Bsize%5D=2",
"last": "http://api.dbljump.com/media/images?page%5Bnumber%5D=2&page%5Bsize%5D=2"
},
"meta": {
"total_items": 3
}
}
Retrieve all images. Automatically paginated.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /media/images
URL query parameters
| Parameter | Default | Description |
|---|---|---|
| fields[{record-type}] | All fields | Return only specified fields, e.g. ?fields[images]=file,title |
| filter[{field}] | All records | Filter search by field, e.g. ?filter[kind]=logo |
| page[number] | 1 | Select the page number, e.g. ?page[number]=3 |
| page[size] | 30 | Select the number of records per page, e.g. ?page[size]=20 |
Success HTTP response code
200 OK
Get single image
Response body |
HTTP 200
# GET /media/images/mario-figure-photo
{
"data": {
"id": "2",
"type": "images",
"attributes": {
"kind": "photo",
"slug": "mario-figure-photo",
"original": "https://dbljumpheroku.s3.amazonaws.com/uploads/images/2/mario-figure.jpg",
"thumb": "https://dbljumpheroku.s3.amazonaws.com/uploads/images/2/th_mario-figure.jpg",
"title": "Mario figure",
"description": "",
"year": 2016,
"date": "2016-07-30",
"usage_type": "free",
"usage_license_code": null,
"usage_license_name": null,
"usage_license_url": null,
"attributed_name": null,
"attributed_url": null,
"source_url": ""
},
"relationships": {
"uploaded_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://api.dbljump.com/users/1"
}
},
"place": {
"data": null,
"links": {
"related": "http://api.dbljump.com/places/afghanistan"
}
}
},
"links": {
"self": "http://api.dbljump.com/media/images/mario-figure-photo"
}
},
"included": [
{
"id": "1",
"type": "users",
"attributes": {
"username": "tikithekiwi",
"role": "admin",
"given_names": "Tiki",
"family_name": "the Kiwi",
"avatar": null
},
"links": {
"self": "http://api.dbljump.com/users/1"
}
}
],
"meta": {
"keywords": "mario figure, photo, 2016, 2016-07-30, image, picture, media, dbljump, video games, pc games, gaming",
"description": "'Mario figure' is a video game image at Dbljump.",
"created_at": "2017-04-21T09:27:48.640Z",
"updated_at": "2017-04-21T09:27:48.640Z"
}
}
Retrieve a single image record. Images are publicly available. No sign-in is required.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /media/images/{slug} (replace {slug} with image record slug)
Success HTTP response code
200 OK
Response attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| original | string | Y | URL of the original file. |
| thumb | string | Y | URL of the thumbnail version, resized to max-width 300px. |
| slug | string | Y | A record ID based on metadata, e.g. ‘photo-of-hideo-kojima’. |
| kind | string | Y | See Kind. |
| title | string | Y | The image title. |
| description | string | The image description. | |
| year | integer | Year the image was created. | |
| date | date | Date the image was created. | |
| usage_type | string | Y | One of three usage types:'free’, 'fair’, or 'licensed’. See Usage type. |
| usage_license_code | string | * | Req’d if usage_type is 'licensed’. See Usage license section. |
| attributed_name | string | * | The image owner’s name. Always present if usage_type is 'licensed’. |
| attributed_url | string | The image owner’s website URL. | |
| source_url | string | * | The URL the image was sourced from. Always present if usage_type is 'licensed’. |
Relationships
| Association | Record type | Relationship type |
|---|---|---|
| uploaded_by | users | belongs_to |
| place | places | belongs_to |
Meta
The meta section of the JSON response includes keywords, description, created_at and updated_at attributes.
Upload a new image
Request body |
POST /media/images
{
"data": {
"type": "images",
"attributes": {
"base64_file": "data:image/gif;base64,R0lGODlhBQAFAIAAAAAAAP///ywAAAAABQAFAAACBIyPqVgAOw==",
"kind": "photo",
"title": "Portrait of Takashi Tezuka",
"description": "Takashi Tezuka in Kyoto on 2nd February 2017.",
"year": "",
"date": "2017-02-02",
"usage_type": "licensed",
"usage_license_code": "cc_by_4_0",
"attributed_name": "Jonny Snapper",
"attributed_url": "http://www.jonnys-game-pics.com",
"source_url": "http://www.jonnys-game-pics.com/tezuka.jpg"
},
"relationships": {
"place": {
"data": {
"id": "1",
"type": "places"
}
}
}
}
}
Response body |
HTTP 201
{
"data": {
"id": "3",
"type": "images",
"attributes": {
"kind": "photo",
"slug": "portrait-of-takashi-tezuka-photo",
"original": "https://dbljumpheroku.s3.amazonaws.com/uploads/images/3/file.gif",
"thumb": "https://dbljumpheroku.s3.amazonaws.com/uploads/images/3/th_file.gif",
"title": "Portrait of Takashi Tezuka",
"description": "Takashi Tezuka in Kyoto on 2nd February 2017.",
"year": 2017,
"date": "2017-02-02",
"usage_type": "licensed",
"usage_license_code": "cc_by_4_0",
"usage_license_name": "Creative Commons Attribution 4.0",
"usage_license_url": "https://creativecommons.org/licenses/by/4.0",
"attributed_name": "Jonny Snapper",
"attributed_url": "http://www.jonnys-game-pics.com",
"source_url": "http://www.jonnys-game-pics.com/tezuka.jpg"
},
"relationships": {
"uploaded_by": {
"data": {
"id": "2",
"type": "users"
},
"links": {
"related": "http://api.dbljump.com/users/2"
}
},
"place": {
"data": {
"id": "1",
"type": "places"
},
"links": {
"related": "http://api.dbljump.com/places/afghanistan"
}
}
},
"links": {
"self": "http://api.dbljump.com/media/images/portrait-of-takashi-tezuka-photo"
}
},
"included": [
{
"id": "2",
"type": "users",
"attributes": {
"username": "neil",
"role": "admin",
"given_names": "Neil",
"family_name": "Wheatley",
"avatar": "https://dbljumpheroku.s3.amazonaws.com/uploads/user_avatar/2/1704210927.jpg"
},
"links": {
"self": "http://api.dbljump.com/users/2"
}
},
{
"id": "1",
"type": "places",
"attributes": {
"kind": "country",
"slug": "afghanistan",
"name": "Afghanistan",
"formatted": "Afghanistan",
"short_name": null
},
"links": {
"self": "http://api.dbljump.com/places/afghanistan"
}
}
],
"meta": {
"keywords": "portrait of takashi tezuka, photo, 2017, 2017-02-02, jonny snapper, image, picture, media, dbljump, video games, pc games, gaming",
"description": "'Portrait of Takashi Tezuka' is a video game image at Dbljump.",
"created_at": "2017-04-21T09:32:01.323Z",
"updated_at": "2017-04-21T09:32:01.323Z"
}
}
Upload a new image. User must be an editor or admin.
- User authentication: required
- Authorization level: admin
HTTP request
POST /media/images
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| base64_file | string | Y | Image file encoded as base64. See File. |
| kind | string | Y | See Kind. |
| title | string | Y | Max 100 chars. |
| description | string | Max 250 chars. | |
| year | integer | 1800 to present year. | |
| date | date | 1800-01-01 to present year. | |
| usage_type | string | Y | Must be ‘free’, 'fair’, or 'licensed’. See Usage type. |
| usage_license_code | string | * | Req’d if usage_type is 'licensed’. See Usage license. |
| attributed_name | string | * | Image owner’s name. Max 100 chars. Req’d if usage_type is 'licensed’. |
| attributed_url | string | The owner’s website. Max 250 chars. | |
| source_url | string | * | Req’d if usage_type is 'licensed’. Max 250 chars. URL of image source. |
Relationships
Check this section’s code example to see how to update these relationships.
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| place | belongs_to | places | A place record the image is associated with. |
File
File type: File uploads must be of type GIF, JPG/JPEG, or PNG.
Base64: Image file uploads are handled by the Ruby gems CarrierWave and Carrierwave::Base64. Base64 strings should have the correct data format, i.e.:
data:image/jpeg;base64,(base64 encoded data)
Kind
The kind attribute accepts the following values.
| Kind | Description |
|---|---|
| artwork | Miscellaneous artwork, e.g. production design drawings or promotional art |
| boxart | Official box art from various regions |
| doc | Image of a document, e.g. a leaked presentation slide |
| logo | Usually a company or game logo |
| photo | A photograph |
| poster | A game poster |
| screen | A screenshot from a game |
Usage type
Users should only upload images that can legally be shown on Dbljump.com. An image must therefore have one of three usage_type values.
| Usage type | usage_type value | Description |
|---|---|---|
| Free | free | The image is in the public domain and free to use without attribution. |
| Fair use | fair | The image can be used under US fair use law. May include logos, box-arts, and screenshots. |
| Licensed | licensed | The image is free to use with some-rights-reserved license, e.g. Creative Commons. |
Usage license attribute
If usage_type is set to licensed, a valid image license code must be provided. Acceptable values are below. We could add an API endpoint to retrieve all these values, such as /media-licenses.
| usage_license_code | License name | License URL |
|---|---|---|
| cc_by_2_0 | Creative Commons Attribution 2.0 | https://creativecommons.org/licenses/by/2.0 |
| cc_by_2_5 | Creative Commons Attribution 2.5 | https://creativecommons.org/licenses/by/2.5/ |
| cc_by_sa_2_0 | Creative Commons Attribution-ShareAlike 2.0 | https://creativecommons.org/licenses/by-sa/2.0 |
| cc_by_nd_2_0 | Creative Commons Attribution-NoDerivs 2.0 | http://creativecommons.org/licenses/by-nd/2.0/ |
| cc_by_3_0 | Creative Commons Attribution 3.0 | https://creativecommons.org/licenses/by/3.0/ |
| cc_by_sa_3_0 | Creative Commons Attribution-ShareAlike 3.0 | https://creativecommons.org/licenses/by-sa/3.0 |
| cc_by_nd_3_0 | Creative Commons Attribution-NoDerivs 3.0 | http://creativecommons.org/licenses/by-nd/3.0 |
| cc_by_4_0 | Creative Commons Attribution 4.0 | https://creativecommons.org/licenses/by/4.0 |
| cc_by_sa_4_0 | Creative Commons Attribution-ShareAlike 4.0 | https://creativecommons.org/licenses/by-sa/4.0 |
| cc_by_nd_4_0 | Creative Commons Attribution-NoDerivs 4.0 | http://creativecommons.org/licenses/by-nd/4.0 |
Success HTTP response code
201 Created
Update an image record
Request body |
PATCH /media/images/nintendo-office-photo
{
"data": {
"type": "images",
"id": "portrait-of-takashi-tezuka-2017-likeness-jonny-snapper",
"attributes": {
"kind": "screen",
"title": "New Title",
"description": "New description.",
"year": "",
"date": "2000-01-01",
"usage_type": "licensed",
"usage_license_code": "cc_by_3_0",
"attributed_name": "New Attributed Name",
"attributed_url": "http://www.new-site.com",
"source_url": "http://www.new-site/new-file.jpg"
},
"relationships": {
"country": {
"data": {
"id": "3",
"type": "places"
}
}
}
}
}
Response body |
HTTP 200
{
"data": {
"id": "1",
"type": "images",
"attributes": {
"kind": "screen",
"slug": "new-title-screen",
"original": "https://dbljumpheroku.s3.amazonaws.com/uploads/images/1/nintendo-hq-kyoto-2006.jpg",
"thumb": "https://dbljumpheroku.s3.amazonaws.com/uploads/images/1/th_nintendo-hq-kyoto-2006.jpg",
"title": "New Title",
"description": "New description.",
"year": 2000,
"date": "2000-01-01",
"usage_type": "licensed",
"usage_license_code": "cc_by_3_0",
"usage_license_name": "Creative Commons Attribution 3.0",
"usage_license_url": "https://creativecommons.org/licenses/by/3.0/",
"attributed_name": "New Attributed Name",
"attributed_url": "http://www.new-site.com",
"source_url": "http://www.new-site/new-file.jpg"
},
"relationships": {
"uploaded_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://api.dbljump.com/users/1"
}
},
"place": {
"data": null,
"links": {
"related": "http://api.dbljump.com/places/afghanistan"
}
}
},
"links": {
"self": "http://api.dbljump.com/media/images/new-title-screen"
}
},
"included": [
{
"id": "1",
"type": "users",
"attributes": {
"username": "tikithekiwi",
"role": "admin",
"given_names": "Tiki",
"family_name": "the Kiwi",
"avatar": null
},
"links": {
"self": "http://api.dbljump.com/users/1"
}
}
],
"meta": {
"keywords": "new title, screen, 2000, 2000-01-01, new attributed name, image, picture, media, dbljump, video games, pc games, gaming",
"description": "'New Title' is a video game image at Dbljump.",
"created_at": "2017-04-21T09:27:46.355Z",
"updated_at": "2017-04-21T09:34:24.055Z"
}
}
Update an existing image record. The user must be an editor.
The file attribute cannot be updated. A new image file can only be uploaded with a new image record.
- User authentication: required
- Authorization level: editor
HTTP request
PATCH /media/images/{slug} (replace {slug} with image record slug)
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| kind | string | Y | See Kind. |
| title | string | Y | Max 100 chars. |
| description | string | Max 250 chars. | |
| year | integer | 1800 to present year. | |
| date | date | 1800-01-01 to present year. | |
| usage_type | string | Y | Must be ‘free’, 'fair’, or 'licensed’. See Usage type. |
| usage_license_code | string | * | Req’d if usage_type is 'licensed’. See Usage license. |
| attributed_name | string | * | Image owner’s name. Max 100 chars. Req’d if usage_type is 'licensed’. |
| attributed_url | string | The owner’s website. Max 250 chars. | |
| source_url | string | * | Req’d if usage_type is 'licensed’. Max 250 chars. URL of image source. |
Relationships
Check this section’s code example to see how to update these relationships.
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| place | belongs_to | places | A place record the image is associated with. |
Success HTTP response code
200 OK
Delete an image record
Delete an existing image record. An editor can delete images they uploaded. An admin can delete any image.
- User authentication: required
- Authorization level: Editor to delete own images. Admin to delete any image.
HTTP request
DELETE /media/images/{slug} (replace {slug} with image record slug)
Success HTTP response code
204 No Content
Errors
Errors specific to creating and updating image records.
| HTTP code | Error code | Pointer | Title |
|---|---|---|---|
| 400 | IMAGE_BASE64_FILE_BLANK | base64_file | File is required. |
| 400 | IMAGE_BASE64_FILE_INVALID | base64_file | Base64 file must be in the correct format. |
| 400 | IMAGE_BASE64_FILE_PRESENT | base64_file | Base64 file is not accepted for this action. |
| 400 | IMAGE_TITLE_BLANK | title | Title is required. |
| 400 | IMAGE_TITLE_TOO_LONG | title | Title cannot be more than 100 characters. |
| 400 | IMAGE_DESCRIPTION_TOO_LONG | description | Description cannot be more than 250 characters. |
| 400 | IMAGE_KIND_BLANK | kind | Kind is required. |
| 400 | IMAGE_KIND_INCLUSION | kind | Kind must be a valid value. |
| 400 | IMAGE_YEAR_INCLUSION | year | Year must be between 1800 and the present year. |
| 400 | IMAGE_DATE_INCLUSION | year | Date must be between 1 January 1800 and the present date. |
| 400 | IMAGE_USAGE_TYPE_BLANK | usage_type | Usage type is required. |
| 400 | IMAGE_USAGE_TYPE_INCLUSION | usage_type | Usage type must be ‘free’, 'fair’, or 'licensed’. |
| 400 | IMAGE_ATTRIBUTED_NAME_BLANK | attributed_name | Attributed name is required if usage type is 'licensed’. |
| 400 | IMAGE_ATTRIBUTED_NAME_TOO_LONG | attributed_name | Attributed name cannot be more than 100 characters. |
| 400 | IMAGE_ATTRIBUTED_URL_TOO_LONG | attributed_url | Attributed URL cannot be more than 250 characters. |
| 400 | IMAGE_SOURCE_URL_BLANK | source_url | Source url is required if usage type is 'licensed’. |
| 400 | IMAGE_SOURCE_URL_TOO_LONG | source_url | Source url cannot be more than 250 characters. |
| 400 | IMAGE_USAGE_LICENSE_CODE_BLANK | usage_license_code | Usage license code is required if usage type is 'licensed’. |
| 400 | IMAGE_USAGE_LICENSE_CODE_INCLUSION | usage_license_code | Usage license code must be valid. |
| 400 | IMAGE_PLACE_ID_INVALID | relationships/place/data/id | Must be a valid place ID. |
Media licenses
Users should only upload privately-owned media items (such as images) to Dbljump if they are published with a license that gives us the legal right to use them (e.g. Creative Commons licenses).
This resource catalogues such licenses. Through the media/images endpoint, it also allows us to relate licenses to media items so we can show proper rights attributions.
The JSON:API type for this resource is media_licenses.
Mutable attributes
name (string, required, unique)
The license name. 1-100 chars.
short_name (string, required, unique)
A short version of the name. 1-15 chars.
url (string, required, unique)
The URL of the official web page for the license. 1-250 chars.
Immutable relationships
These relationships cannot be updated at this endpoint.
| Name | JSON:API type | Relationship type |
|---|---|---|
images |
images |
Has many |
created_by |
users |
Belongs to |
updated_by |
users |
Belongs to |
Get media licenses
Response body |
HTTP 200
# GET /media/licenses?page[size]=2&sort=name
{
"data": [
{
"id": "1",
"type": "media_licenses",
"attributes": {
"name": "A Super License",
"short_name": "CC BY 2.0",
"url": "https://creativecommons.org/licenses/by/2.0"
},
"relationships": {
"images": {
"data": [
{
"id": "25",
"type": "images"
},
{
"id": "30",
"type": "images"
},
{
"id": "34",
"type": "images"
}
]
},
"updated_by": {
"data": null
},
"created_by": {
"data": null
}
},
"links": {
"self": "http://localhost:3000/media/licenses/1"
},
"meta": {
"created_at": "2017-12-11T11:05:41.001Z",
"updated_at": "2017-12-11T16:44:52.176Z",
"meta_description": "Find media published under A Super License at Dbljump, the video game reference.",
"meta_keywords": "A Super License, CC BY 2.0, creative commons, license, media, dbljump, video games, pc games, gaming",
"total_images": 15
}
},
{
"id": "2",
"type": "media_licenses",
"attributes": {
"name": "Creative Commons Attribution 2.5",
"short_name": "CC BY 2.5",
"url": "https://creativecommons.org/licenses/by/2.5/"
},
"relationships": {
"images": {
"data": [
{
"id": "39",
"type": "images"
}
]
},
"updated_by": {
"data": null
},
"created_by": {
"data": null
}
},
"links": {
"self": "http://localhost:3000/media/licenses/2"
},
"meta": {
"created_at": "2017-12-11T11:05:41.010Z",
"updated_at": "2017-12-11T11:05:41.010Z",
"meta_description": "Find media published under Creative Commons Attribution 2.5 at Dbljump, the video game reference.",
"meta_keywords": "Creative Commons Attribution 2.5, CC BY 2.5, creative commons, license, media, dbljump, video games, pc games, gaming",
"total_images": 1
}
}
],
"links": {
"self": "http://localhost:3000/media/licenses?page%5Bnumber%5D=1&page%5Bsize%5D=2&sort=name",
"next": "http://localhost:3000/media/licenses?page%5Bnumber%5D=2&page%5Bsize%5D=2&sort=name",
"last": "http://localhost:3000/media/licenses?page%5Bnumber%5D=6&page%5Bsize%5D=2&sort=name"
},
"meta": {
"total_items": 11
}
}
Retrieve a collection of media licenses. No user authentication required.
HTTP request
GET /media/licenses
URL query support
| Query type | Details |
|---|---|
| Filter fields | name, short_name, url |
| Sort fields | name, short_name, url |
| Include | created_by, updated_by |
| Pagination | Yes |
| Search | No |
Success HTTP response code
200 OK
Get a single media license
Response body |
HTTP 200
# GET /media/licenses/1
{
"data": {
"id": "2",
"type": "media_licenses",
"attributes": {
"name": "Creative Commons Attribution 2.5",
"short_name": "CC BY 2.5",
"url": "https://creativecommons.org/licenses/by/2.5/"
},
"relationships": {
"images": {
"data": [
{
"id": "39",
"type": "images"
}
]
},
"updated_by": {
"data": null
},
"created_by": {
"data": null
}
},
"links": {
"self": "http://localhost:3000/media/licenses/2"
},
"meta": {
"created_at": "2017-12-11T11:05:41.010Z",
"updated_at": "2017-12-11T11:05:41.010Z",
"meta_description": "Find media published under Creative Commons Attribution 2.5 at Dbljump, the video game reference.",
"meta_keywords": "Creative Commons Attribution 2.5, CC BY 2.5, creative commons, license, media, dbljump, video games, pc games, gaming",
"total_images": 1
}
}
}
Retrieve a single media license.
HTTP request
GET /media/licenses/{id} (replace {id} with record ID)
Success HTTP response code
200 OK
Create a new media license
Request body |
POST /media/licenses
{
"data": {
"type": "media_licenses",
"attributes": {
"name": "New License",
"short_name": "New",
"url": "https://www.licenses.org/new-license"
}
}
}
Response body |
HTTP 201
{
"data": {
"id": "12",
"type": "media_licenses",
"attributes": {
"name": "New License",
"short_name": "New",
"url": "https://www.licenses.org/new-license"
},
"relationships": {
"images": {
"data": []
},
"updated_by": {
"data": {
"id": "2",
"type": "users"
}
},
"created_by": {
"data": {
"id": "2",
"type": "users"
}
}
},
"links": {
"self": "http://localhost:3000/media/licenses/12"
},
"meta": {
"created_at": "2017-12-11T20:49:14.349Z",
"updated_at": "2017-12-11T20:49:14.349Z",
"meta_description": "Find media published under New License at Dbljump, the video game reference.",
"meta_keywords": "New License, New, creative commons, license, media, dbljump, video games, pc games, gaming",
"total_images": 0
}
}
}
Create a new media license record. The user must be an admin.
HTTP request
POST /articles/company_aliases
Success HTTP response code
201 Created
Update a media license
Request body |
PATCH /media/licenses/9
{
"data": {
"type": "media_licenses",
"id": "9",
"attributes": {
"name": "Updated License",
"short_name": "Updated",
"url": "https://www.licenses.org/updated-license"
}
}
}
Response body |
HTTP 200
{
"data": {
"id": "9",
"type": "media_licenses",
"attributes": {
"name": "Updated License",
"short_name": "Updated",
"url": "https://www.licenses.org/updated-license"
},
"relationships": {
"images": {
"data": []
},
"updated_by": {
"data": {
"id": "2",
"type": "users"
}
},
"created_by": {
"data": {
"id": "2",
"type": "users"
}
}
},
"links": {
"self": "http://localhost:3000/media/licenses/9"
},
"meta": {
"created_at": "2017-12-11T11:05:41.084Z",
"updated_at": "2017-12-11T20:51:21.759Z",
"meta_description": "Find media published under Updated License at Dbljump, the video game reference.",
"meta_keywords": "Updated License, Updated, creative commons, license, media, dbljump, video games, pc games, gaming",
"total_images": 0
}
}
}
Update an existing media license. The user must be an admin.
HTTP request
PATCH /media/licenses/{id} (replace {id} with record ID)
Success HTTP response code
200 OK
Delete a media license
Delete an existing media license. User must be an admin.
HTTP request
DELETE /media/licenses/{id} (replace {id} with record ID)
Success HTTP response code
204 No Content
Media license errors
| HTTP code | Error code | Pointer | Title |
|---|---|---|---|
| 400 | MEDIA_LICENSE_NAME_BLANK | name | Name is required. |
| 400 | MEDIA_LICENSE_NAME_TOO_LONG | name | Name cannot be more than 100 characters. |
| 400 | MEDIA_LICENSE_NAME_TAKEN | name | Name must be unique. |
| 400 | MEDIA_LICENSE_SHORT_NAME_BLANK | short_name | Short name is required. |
| 400 | MEDIA_LICENSE_SHORT_NAME_TOO_LONG | short_name | Short name cannot be more than 15 characters. |
| 400 | MEDIA_LICENSE_SHORT_NAME_TAKEN | short_name | Short name must be unique. |
| 400 | MEDIA_LICENSE_URL_BLANK | url | URL is required. |
| 400 | MEDIA_LICENSE_URL_TOO_LONG | url | URL cannot be more than 250 characters. |
| 400 | MEDIA_LICENSE_URL_TAKEN | url | URL must be unique. |
Platforms
Resources related to game platforms.
Game platforms can include dedicated game systems (e.g. Sony PlayStation 4), computers (e.g. Atari ST), operating systems (e.g. Microsoft Windows), add-ons with unique game libraries (e.g. Sega 32X), and arcade systems (e.g. Capcom CPS-2).
Request attributes
See Create a new platform record and Update a platform record.
Response attributes
See Get single country.
Get all platforms
HTTP 200 response body
{
"data": [
{
"id": "1",
"type": "platforms",
"attributes": {
"slug": "sony-playstation",
"name": "PlayStation",
"short_name": "PS",
"name_with_holder": "Sony PlayStation",
"sphere": "home",
"kind": "system"
},
"relationships": {
"holder": {
"meta": {}
},
"parent": {
"data": null,
"links": {
"related": "http://api.dbljump.com/platforms/sega-genesis"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://api.dbljump.com/users/1"
}
}
},
"links": {
"self": "http://api.dbljump.com/platforms/sony-playstation"
}
},
{
"id": "2",
"type": "platforms",
"attributes": {
"slug": "sony-playstation-2",
"name": "PlayStation 2",
"short_name": "PS2",
"name_with_holder": "Sony PlayStation 2",
"sphere": "home",
"kind": "system"
},
"relationships": {
"holder": {
"meta": {}
},
"parent": {
"data": null,
"links": {
"related": "http://api.dbljump.com/platforms/sega-genesis"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://api.dbljump.com/users/1"
}
}
},
"links": {
"self": "http://api.dbljump.com/platforms/sony-playstation-2"
}
},
{
"id": "3",
"type": "platforms",
"attributes": {
"slug": "sony-playstation-3",
"name": "PlayStation 3",
"short_name": "PS3",
"name_with_holder": "Sony PlayStation 3",
"sphere": "home",
"kind": "system"
},
"relationships": {
"holder": {
"meta": {}
},
"parent": {
"data": null,
"links": {
"related": "http://api.dbljump.com/platforms/sega-genesis"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://api.dbljump.com/users/1"
}
}
},
"links": {
"self": "http://api.dbljump.com/platforms/sony-playstation-3"
}
}
],
"links": {
"self": "http://api.dbljump.com/platforms?page%5Bnumber%5D=1&page%5Bsize%5D=3",
"next": "http://api.dbljump.com/platforms?page%5Bnumber%5D=2&page%5Bsize%5D=3",
"last": "http://api.dbljump.com/platforms?page%5Bnumber%5D=13&page%5Bsize%5D=3"
},
"meta": {
"total_items": 38
}
}
Retrieve all platforms. Automatically paginated.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /platforms
URL query parameters
| Parameter | Default | Description |
|---|---|---|
| fields[{record-type}] | All fields | Return only specified fields, e.g. ?fields[platforms]=name,short_name |
| filter[{field}] | All records | Filter search by field, e.g. ?filter[name]=Tokyo Prefecture |
| page[number] | 1 | Select the page number, e.g. ?page[number]=3 |
| page[size] | 30 | Select the number of records per page, e.g. ?page[size]=20 |
Success HTTP response code
200 OK
Get single platform
HTTP 200 response body
{
"data": {
"id": "31",
"type": "platforms",
"attributes": {
"slug": "sega-32x",
"name": "32X",
"short_name": "32X",
"name_with_holder": "Sega 32X",
"sphere": "home",
"kind": "add-on"
},
"relationships": {
"holder": {
"meta": {}
},
"parent": {
"data": {
"id": "29",
"type": "platforms"
},
"links": {
"related": "http://api.dbljump.com/platforms/sega-genesis"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://api.dbljump.com/users/1"
}
}
},
"links": {
"self": "http://api.dbljump.com/platforms/sega-32x"
}
},
"included": [
{
"id": "1",
"type": "users",
"attributes": {
"username": "tikithekiwi",
"role": "admin",
"given_names": "Tiki",
"family_name": "the Kiwi",
"avatar": null
},
"links": {
"self": "http://api.dbljump.com/users/1"
}
}
],
"meta": {
"keywords": "32x, 32x, sega, home, add-on, platform, dbljump, video games, pc games, gaming",
"description": "Find out about games for 32X by Sega Games Co., Ltd. at Dbljump, the video game reference.",
"created_at": "2017-03-30T12:40:16.950Z",
"updated_at": "2017-03-30T12:40:16.950Z"
}
}
Retrieve a single platform record. Platforms are publicly available. No sign-in is required.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /platforms/{slug} (replace {slug} with platform record slug)
Success HTTP response code
200 OK
Response attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| slug | string | Y | A record ID based on metadata, e.g. ‘sega-genesis’. |
| name | string | Y | The full North American name, or nearest alternative, e.g. 'Genesis’ |
| short_name | string | The common abbreviated name, e.g. 'SNES’. | |
| name_with_holder | string | Immutable. A 'full name’ including the platform holder name. | |
| sphere | string | Y | The usual platform environment. See Sphere. |
| kind | string | Y | Platform type. See Kind. |
Relationships
| Association | Record type | Relationship type |
|---|---|---|
| holder | companies | belongs_to |
| parent | platforms | belongs_to |
| created_by | users | belongs_to |
Meta
The meta section of the JSON response includes keywords, description, created_at and updated_at attributes.
Create a new platform record
Request body
{
"data": {
"type": "platforms",
"attributes": {
"name": "New Platform",
"short_name": "NPlat",
"sphere": "home",
"kind": "add-on",
}
"relationships": {
"holder": {
"data": {
"id": null,
"type": "companies"
}
},
"parent": {
"data": {
"id": "13",
"type": "platforms"
}
}
}
}
}
HTTP 201 response body
{
"data": {
"id": "39",
"type": "platforms",
"attributes": {
"slug": "nintendo-new-platform",
"name": "New Platform",
"short_name": "NPlat",
"name_with_holder": "Nintendo New Platform",
"sphere": "home",
"kind": "add-on"
},
"relationships": {
"holder": {
"meta": {}
},
"parent": {
"data": {
"id": "13",
"type": "platforms"
},
"links": {
"related": "http://api.dbljump.com/platforms/nintendo-switch"
}
},
"created_by": {
"data": {
"id": "2",
"type": "users"
},
"links": {
"related": "http://api.dbljump.com/users/2"
}
}
},
"links": {
"self": "http://api.dbljump.com/platforms/nintendo-new-platform"
}
},
"included": [
{
"id": "2",
"type": "users",
"attributes": {
"username": "neil",
"role": "admin",
"given_names": "Neil",
"family_name": "Wheatley",
"avatar": "https://dbljumpheroku.s3.amazonaws.com/uploads/user_avatar/2/1703301240.jpg"
},
"links": {
"self": "http://api.dbljump.com/users/2"
}
}
],
"meta": {
"keywords": "new platform, nplat, nintendo, home, add-on, platform, dbljump, video games, pc games, gaming",
"description": "Find out about games for New Platform by Nintendo Co., Ltd. at Dbljump, the video game reference.",
"created_at": "2017-03-30T13:32:37.200Z",
"updated_at": "2017-03-30T13:32:37.200Z"
}
}
Create a new platform record. Admin-level authorization required.
- User authentication: required
- Authorization level: admin
HTTP request
POST /platforms
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| name | string | Y | Max 50 chars. The full North American name, or nearest alternative, e.g. ‘Genesis’ |
| short_name | string | Max 10 chars. The common abbreviated name, e.g. 'SNES’. | |
| sphere | string | Y | The usual platform environment. See Sphere. |
| kind | string | Y | Platform type. See Kind. |
Relationships
Check this section’s code example to see how to update these relationships.
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| holder | belongs_to | Y | companies | Must be a valid company. The platform holder, e.g. 'Sony’ for PlayStation. |
| parent | belongs_to | platforms | Must be a valid platform. Used for add-ons, e.g. 'Sega CD’ belongs to Sega Genesis. |
Sphere
The sphere attribute must take one of the following values.
| Value | Description |
|---|---|
| home | Usually used at home, e.g. a home console or computer. |
| portable | Portable or handheld, e.g. PS Vita or Nintendo Game Boy. |
| mobile | A phone, tablet or mobile operating system, e.g. Android. |
| arcade | Associated with public game arcades, e.g. Sega NAOMI. |
| non-gaming | For platforms not usually associated with gaming. |
Kind
The kind attribute must take one of the following values.
| Value | Description |
|---|---|
| system | Hardware such as a console, computer or device. |
| OS | A software operating system that might run on various devices. |
| add-on | A device that requires its parent platform to run. |
Success HTTP response code
201 Created
Update a platform record
Request body
{
"data": {
"type": "platforms",
"id": "sega-dreamcast-2",
"attributes": {
"name": "Updated Name",
"short_name": "Changed",
"name_with_holder": "Sega Updated Name,
"sphere": "portable",
"kind": "system"
},
"relationships": {
"holder": {
"data": {
"id": null,
"type": "companies"
}
},
"parent": {
"data": {
"id": "2",
"type": "platforms"
}
}
}
}
}
HTTP 200 response body
{
"data": {
"id": "27",
"type": "platforms",
"attributes": {
"slug": "nintendo-updated-name",
"name": "Updated Name",
"short_name": "Changed",
"sphere": "portable",
"kind": "system"
},
"relationships": {
"holder": {
"meta": {}
},
"parent": {
"data": {
"id": "2",
"type": "platforms"
},
"links": {
"related": "http://api.dbljump.com/platforms/sony-playstation-2"
}
},
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://api.dbljump.com/users/1"
}
}
},
"links": {
"self": "http://api.dbljump.com/platforms/nintendo-updated-name"
}
},
"included": [
{
"id": "1",
"type": "users",
"attributes": {
"username": "tikithekiwi",
"role": "admin",
"given_names": "Tiki",
"family_name": "the Kiwi",
"avatar": null
},
"links": {
"self": "http://api.dbljump.com/users/1"
}
}
],
"meta": {
"keywords": "updated name, changed, nintendo, portable, system, platform, dbljump, video games, pc games, gaming",
"description": "Find out about games for Updated Name by Nintendo Co., Ltd. at Dbljump, the video game reference.",
"created_at": "2017-03-30T12:40:16.756Z",
"updated_at": "2017-03-30T13:34:53.017Z"
}
}
Update an existing platform record. The user must be an admin.
- User authentication: required
- Authorization level: admin
HTTP request
PATCH /platforms/{slug} (replace {slug} with platform record slug)
Request attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| name | string | Y | Max 50 chars. The full North American name, or nearest alternative, e.g. ‘Genesis’ |
| short_name | string | Max 10 chars. The common abbreviated name, e.g. 'SNES’. | |
| sphere | string | Y | The usual platform environment. See Sphere. |
| kind | string | Y | Platform type. See Kind. |
Relationships
Check this section’s code example to see how to update these relationships.
| Name | Relationship | Req’d? | JSON:API type | Description |
|---|---|---|---|---|
| holder | belongs_to | Y | companies | Must be a valid company. The platform holder, e.g. 'Sony’ for PlayStation. |
| parent | belongs_to | platforms | Must be a valid platform. Used for add-ons, e.g. 'Sega CD’ belongs to Sega Genesis. |
Success HTTP response code
200 OK
Delete a platform record
Delete an existing platform record. Admin-level authorization required.
- User authentication: required
- Authorization level: admin
HTTP request
DELETE /platforms/{slug} (replace {slug} with platform record slug)
Success HTTP response code
204 No Content
Errors
Errors specific to creating and updating platform records.
| HTTP code | Error code | Pointer | Title |
|---|---|---|---|
| 400 | PLATFORM_NAME_BLANK | name | Name is required. |
| 400 | PLATFORM_NAME_TAKEN | name | Name has already been taken. |
| 400 | PLATFORM_NAME_TOO_LONG | name | Name cannot be more than 50 characters. |
| 400 | PLATFORM_SHORT_NAME_TAKEN | short_name | Short name has already been taken. |
| 400 | PLATFORM_SHORT_TOO_LONG | short_name | Short name cannot be more than 10 characters. |
| 400 | PLATFORM_SPHERE_BLANK | sphere | Sphere is required. |
| 400 | PLATFORM_SPHERE_INCLUSION | sphere | Sphere must be an accepted value. |
| 400 | PLATFORM_KIND_BLANK | kind | Kind is required. |
| 400 | PLATFORM_KIND_INCLUSION | kind | Kind must be an accepted value. |
| 400 | PLATFORM_HOLDER_ID_BLANK | relationships/holder/data/id | Holder is required. |
| 400 | PLATFORM_HOLDER_ID_INVALID | relationships/holder/data/id | Holder ID must be a valid company ID. |
| 400 | PLATFORM_PARENT_ID_INVALID | relationships/parent/data/id | Parent ID must be a valid platform ID. |
Genres
Resources related to genres. Genres have a many-to-many relationship with game records, but this relationship is set by updating the game record.
Request attributes
See Create a new genre and Update a genre record.
Response attributes
See Get single genre
Get all genres
Response body |
HTTP 200
# GET /genres?page[size]=3
{
"data": [
{
"id": "1",
"type": "genres",
"attributes": {
"name": "action",
"short_name": "",
"also_known_as": [],
"slug": "action"
},
"relationships": {
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://api.dbljump.com/users/1"
}
}
},
"links": {
"self": "http://api.dbljump.com/genres/action"
}
},
{
"id": "2",
"type": "genres",
"attributes": {
"name": "adventure",
"short_name": "",
"also_known_as": [],
"slug": "adventure"
},
"relationships": {
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://api.dbljump.com/users/1"
}
}
},
"links": {
"self": "http://api.dbljump.com/genres/adventure"
}
},
{
"id": "3",
"type": "genres",
"attributes": {
"name": "art",
"short_name": "",
"also_known_as": [],
"slug": "art"
},
"relationships": {
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://api.dbljump.com/users/1"
}
}
},
"links": {
"self": "http://api.dbljump.com/genres/art"
}
}
],
"links": {
"self": "http://api.dbljump.com/genres?page%5Bnumber%5D=1&page%5Bsize%5D=3",
"next": "http://api.dbljump.com/genres?page%5Bnumber%5D=2&page%5Bsize%5D=3",
"last": "http://api.dbljump.com/genres?page%5Bnumber%5D=21&page%5Bsize%5D=3"
},
"meta": {
"total_items": 63
}
}
Retrieve all genres. Automatically paginated.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /genres
URL query parameters
| Parameter | Default | Description |
|---|---|---|
| fields[{record-type}] | All fields | Return only specified fields, e.g. ?fields[genres]=name |
| filter[{field}] | All records | Filter search by field, e.g. ?filter[name]=action |
| page[number] | 1 | Select the page number, e.g. ?page[number]=3 |
| page[size] | 30 | Select the number of records per page, e.g. ?page[size]=20 |
Success HTTP response code
200 OK
Get single genre
Response body |
HTTP 200
# GET /genres/action
{
"data": {
"id": "1",
"type": "genres",
"attributes": {
"name": "action",
"short_name": "",
"also_known_as": [],
"slug": "action"
},
"relationships": {
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://api.dbljump.com/users/1"
}
}
},
"links": {
"self": "http://api.dbljump.com/genres/action"
}
},
"included": [
{
"id": "1",
"type": "users",
"attributes": {
"username": "tikithekiwi",
"role": "admin",
"given_names": "Tiki",
"family_name": "the Kiwi",
"avatar": null
},
"links": {
"self": "http://api.dbljump.com/users/1"
}
}
],
"meta": {
"keywords": "action, genre, dbljump, video games, pc games, gaming",
"description": "Find action-genre games at Dbljump, the video game reference.",
"created_at": "2017-04-17T09:17:07.870Z",
"updated_at": "2017-04-17T09:17:07.870Z"
}
}
Retrieve a single genre record. Genres are publicly available. No sign-in is required.
- User authentication: not required
- Authorization level: n/a
HTTP request
GET /genres/{slug} (replace {slug} with record slug)
Success HTTP response code
200 OK
Response attributes
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| name | string | Y | Genre name. Unique, up to 50 chars. |
| short_name | string | Short name. Unique, up to 10 chars. | |
| also_known_as | array | Array of alias names, each up to 50 chars. | |
| slug | string | Y | A record ID based on the name. |
Relationships
| Association | Record type | Relationship type |
|---|---|---|
| created_by | users | belongs_to |
Meta
The meta section of the JSON response includes keywords, description, created_at and updated_at attributes.
Create a new genre
Request body |
POST /genres
{
"data": {
"type": "genres",
"attributes": {
"name": "hog racing",
"short_name": "hogs",
"also_known_as": ["alias"]
}
}
}
Response body |
HTTP 201
{
"data": {
"id": "64",
"type": "genres",
"attributes": {
"name": "hog racing",
"short_name": "hogs",
"also_known_as": [
"alias"
],
"slug": "hog-racing"
},
"relationships": {
"created_by": {
"data": {
"id": "2",
"type": "users"
},
"links": {
"related": "http://api.dbljump.com/users/2"
}
}
},
"links": {
"self": "http://api.dbljump.com/genres/hog-racing"
}
},
"included": [
{
"id": "2",
"type": "users",
"attributes": {
"username": "neil",
"role": "admin",
"given_names": "Neil",
"family_name": "W",
"avatar": "https://dbljumpheroku.s3.amazonaws.com/uploads/user_avatar/2/1704170916.jpg"
},
"links": {
"self": "http://api.dbljump.com/users/2"
}
}
],
"meta": {
"keywords": "hog racing, hogs, alias, genre, dbljump, video games, pc games, gaming",
"description": "Find hog racing-genre games at Dbljump, the video game reference.",
"created_at": "2017-04-19T11:17:21.829Z",
"updated_at": "2017-04-19T11:17:21.829Z"
}
}
Create a new genre. User must be an admin.
- User authentication: required
- Authorization level: admin
HTTP request
POST /genres
Request attributes
Attribute values should be lowercase except for proper nouns. For example, ‘action’ and 'Japanese RPG’ are correct; 'Action’ is incorrect.
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| name | string | Y | Genre name. Unique, up to 50 chars. |
| short_name | string | Short name. Unique, up to 10 chars. | |
| also_known_as | array | Array of alias names, each up to 50 chars. |
Success HTTP response code
201 Created
Update a genre record
Request body |
PATCH /genres/action
{
"data": {
"type": "genres",
"id": "action",
"attributes": {
"name": "updated name",
"short_name": "updated",
"also_known_as": ["aka"]
}
}
}
Response body |
HTTP 200
{
"data": {
"id": "1",
"type": "genres",
"attributes": {
"name": "updated name",
"short_name": "updated",
"also_known_as": [
"aka"
],
"slug": "updated-name"
},
"relationships": {
"created_by": {
"data": {
"id": "1",
"type": "users"
},
"links": {
"related": "http://api.dbljump.com/users/1"
}
}
},
"links": {
"self": "http://api.dbljump.com/genres/updated-name"
}
},
"included": [
{
"id": "1",
"type": "users",
"attributes": {
"username": "tikithekiwi",
"role": "admin",
"given_names": "Tiki",
"family_name": "the Kiwi",
"avatar": null
},
"links": {
"self": "http://api.dbljump.com/users/1"
}
}
],
"meta": {
"keywords": "updated name, updated, aka, genre, dbljump, video games, pc games, gaming",
"description": "Find updated name-genre games at Dbljump, the video game reference.",
"created_at": "2017-04-17T09:17:07.870Z",
"updated_at": "2017-04-19T11:22:21.345Z"
}
}
Update an existing genre record. The user must be an admin.
- User authentication: required
- Authorization level: admin
HTTP request
PATCH /genres/{slug} (replace {slug} with record slug)
Request attributes
Attribute values should be lowercase except for proper nouns. For example, ‘action’ and 'Japanese RPG’ are correct; 'Action’ is incorrect.
| Attribute | Type | Req’d? | Description |
|---|---|---|---|
| name | string | Y | Genre name. Unique, up to 50 chars. |
| short_name | string | Short name. Unique, up to 10 chars. | |
| also_known_as | array | Array of alias names, each up to 50 chars. |
Success HTTP response code
200 OK
Delete a genre record
Delete an existing genre record. User must be an admin.
- User authentication: required
- Authorization level: admin
HTTP request
DELETE /genres/{slug} (replace {slug} with record slug)
Success HTTP response code
204 No Content
Errors
Errors specific to creating and updating genre records.
| HTTP code | Error code | Pointer | Title |
|---|---|---|---|
| 400 | GENRE_NAME_BLANK | name | Name is required. |
| 400 | GENRE_NAME_TAKEN | name | Name has already been taken. |
| 400 | GENRE_NAME_TOO_SHORT | name | Name must be at least 2 characters. |
| 400 | GENRE_NAME_TOO_LONG | name | Name cannot be more than 50 characters. |
| 400 | GENRE_SHORT_NAME_TAKEN | short_name | Short name has already been taken. |
| 400 | GENRE_SHORT_NAME_TOO_SHORT | short_name | Short name must be at least 2 characters. |
| 400 | GENRE_SHORT_NAME_TOO_LONG | short_name | Short name cannot be more than 10 characters. |
| 400 | GENRE_ALSO_KNOWN_AS_TOO_SHORT | also_known_as | Also-known-as tags must be at least 2 characters. |
| 400 | GENRE_ALSO_KNOWN_AS_TOO_LONG | also_known_as | Also-known-as tags cannot be more than 50 characters. |
Errors
General errors not specific to one part of the application.
Authorization errors
| HTTP code | Error code | Pointer | Title |
|---|---|---|---|
| 401 | USER_ACTIVATION_REQUIRED | n/a | User not yet activated. |
| 401 | USER_CREDENTIALS_INVALID | n/a | Invalid email and password combination. |
| 401 | USER_LOGIN_EXPIRED | n/a | The JWT in the header has expired. |
| 401 | USER_LOGIN_TOKEN_INVALID | n/a/ | User login token invalid. |
| 401 | USER_UNAUTHORIZED | n/a | User not authorized. |
GET errors
| HTTP code | Error code | Pointer | Title |
|---|---|---|---|
| 400 | CANNOT_SEARCH | 400 | Search is not supported for this type of record. |
| 404 | RECORD_NOT_FOUND | n/a | Record not found. |