Overview

The Dungeons of Kollchap from What Is Dungeons & Dragons? published 1982

HTTP verbs

RESTful Kollchap tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage

Verb	Usage
`GET`	Used to retrieve a resource
`POST`	Used to create a new resource
`PATCH`	Used to update an existing resource, including partial updates
`DELETE`	Used to delete an existing resource

GET

Used to retrieve a resource

POST

Used to create a new resource

PATCH

Used to update an existing resource, including partial updates

DELETE

Used to delete an existing resource

HTTP status codes

RESTful characters tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code Usage

Status code	Usage
`200 OK`	The request completed successfully
`201 Created`	A new resource has been created successfully. The resource’s URI is available from the response’s `Location` header
`204 No Content`	An update to an existing resource has been applied successfully
`400 Bad Request`	The request was malformed. The response body will include an error providing further information
`404 Not Found`	The requested resource did not exist

200 OK

The request completed successfully

201 Created

A new resource has been created successfully. The resource’s URI is available from the response’s Location header

204 No Content

An update to an existing resource has been applied successfully

400 Bad Request

The request was malformed. The response body will include an error providing further information

404 Not Found

The requested resource did not exist

Headers

Every response has the following header(s):

Name Description

Name	Description
`Content-Type`	The Content-Type of the payload `application/hal+json`

Content-Type

The Content-Type of the payload application/hal+json

Errors

Whenever an error response (status code >= 400) is returned, the body will contain a JSON object that describes the problem. The error object has the following structure:

Path Type Description

Path	Type	Description
`error`	`String`	The HTTP error that occurred, e.g. `Bad Request`
`path`	`String`	The path to which the request was made
`status`	`Number`	The HTTP status code, e.g. `400`
`timestamp`	`String`	The time, in milliseconds, at which the error occurred

error

String

The HTTP error that occurred, e.g. Bad Request

path

String

The path to which the request was made

status

Number

The HTTP status code, e.g. 400

timestamp

String

The time, in milliseconds, at which the error occurred

For example, a request that attempts to apply a non-existent tag to a character will produce a 400 Bad Request response:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 101

{"timestamp":"2023-07-09T11:48:46.936+00:00","status":400,"error":"Bad Request","path":"/characters"}

RESTful Kollchap uses hypermedia and resources include links to other resources in their responses. Responses are in Hypertext Application Language (HAL) format. Links can be found beneath the _links key. Users of the API should not create URIs themselves, instead they should use the above-described links to navigate from resource to resource.

Resources

Path	Type	Description
`_links`	`Object`	Links to other resources

Object

Links to other resources

Example response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
Content-Length: 239

{
  "_links" : {
    "characters" : {
      "href" : "http://localhost:8080/characters"
    },
    "rooms" : {
      "href" : "http://localhost:8080/rooms"
    },
    "profile" : {
      "href" : "http://localhost:8080/profile"
    }
  }
}

Links

Relation Description

Relation	Description
`characters`	The Characters resource
`rooms`	The Rooms resource
`profile`	The ALPS resource

characters

The Characters resource

rooms

The Rooms resource

profile

The ALPS resource

Path	Type	Description
`_embedded.characters`	`Array`	An array of Character resources
`_links`	`Object`	Links to other resources

Array

An array of Character resources

_links

Object

Links to other resources

Example request

$ curl 'http://localhost:8080/characters' -i -X GET \
    -H 'Accept: application/hal+json'

Example response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
Content-Length: 5521

{
  "_embedded" : {
    "characters" : [ {
      "name" : "Slammer Kyntire",
      "background" : "First-level Fighter searching for the Sword of the Sorcerer.",
      "race" : "Human",
      "class" : "Fighter",
      "alignment" : "Lawful",
      "level" : 1,
      "armourClass" : 3,
      "hitPoints" : 7,
      "characteristics" : {
        "str" : 18,
        "int" : 10,
        "wis" : 10,
        "dex" : 9,
        "con" : 11,
        "chr" : 10
      },
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/characters/S3OT4QlQgTX6"
        },
        "gameCharacter" : {
          "href" : "http://localhost:8080/characters/S3OT4QlQgTX6"
        }
      }
    }, {
      "name" : "Hotfa Nap",
      "background" : "First-level Sorceress from a nomad tribe in the Mesta Desert.",
      "race" : "Human",
      "class" : "MagicUser",
      "alignment" : "Neutral",
      "level" : 1,
      "armourClass" : 9,
      "hitPoints" : 5,
      "characteristics" : {
        "str" : 5,
        "int" : 10,
        "wis" : 8,
        "dex" : 18,
        "con" : 13,
        "chr" : 9
      },
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/characters/72FSiCMDE11b"
        },
        "gameCharacter" : {
          "href" : "http://localhost:8080/characters/72FSiCMDE11b"
        }
      }
    }, {
      "name" : "Gripper 'The Skin' Longshank",
      "background" : "First-level Thief from a tribe on the Albine empire border.",
      "race" : "Halfling",
      "class" : "Thief",
      "alignment" : "Neutral",
      "level" : 1,
      "armourClass" : 4,
      "hitPoints" : 5,
      "characteristics" : {
        "str" : 5,
        "int" : 10,
        "wis" : 8,
        "dex" : 18,
        "con" : 13,
        "chr" : 9
      },
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/characters/0OE2tYmFNn86"
        },
        "gameCharacter" : {
          "href" : "http://localhost:8080/characters/0OE2tYmFNn86"
        }
      }
    }, {
      "name" : "Zhod Thobi",
      "background" : "First-level Cleric N.P.C joins party and receives equal share of treasure.",
      "race" : "Human",
      "class" : "Cleric",
      "alignment" : "Lawful",
      "level" : 1,
      "armourClass" : 3,
      "hitPoints" : 6,
      "characteristics" : {
        "str" : 11,
        "int" : 14,
        "wis" : 15,
        "dex" : 10,
        "con" : 7,
        "chr" : 10
      },
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/characters/3keCCPdJU1Al"
        },
        "gameCharacter" : {
          "href" : "http://localhost:8080/characters/3keCCPdJU1Al"
        }
      }
    }, {
      "name" : "Belisarius",
      "background" : "First-level Thief N.P.C survivor. Currently hiding, if located will join party.",
      "race" : "Halfling",
      "class" : "Thief",
      "alignment" : "Neutral",
      "level" : 1,
      "armourClass" : 7,
      "hitPoints" : 2,
      "characteristics" : {
        "str" : 5,
        "int" : 10,
        "wis" : 8,
        "dex" : 18,
        "con" : 13,
        "chr" : 9
      },
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/characters/xl9FfHCXO6UC"
        },
        "gameCharacter" : {
          "href" : "http://localhost:8080/characters/xl9FfHCXO6UC"
        }
      }
    }, {
      "name" : "Rosa Dobbit",
      "background" : "First-level Fighter N.P.C survivor. Currently captive, if released will join party.",
      "race" : "Halfling",
      "class" : "Fighter",
      "alignment" : "Lawful",
      "level" : 1,
      "armourClass" : 9,
      "hitPoints" : 4,
      "characteristics" : {
        "str" : 8,
        "int" : 9,
        "wis" : 8,
        "dex" : 14,
        "con" : 13,
        "chr" : 12
      },
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/characters/nmo4lNJX5Qzc"
        },
        "gameCharacter" : {
          "href" : "http://localhost:8080/characters/nmo4lNJX5Qzc"
        }
      }
    }, {
      "name" : "Odric",
      "background" : "Third-level Cleric N.P.C enemy. Currently in possession of the stolen Statue of Tranfax.",
      "race" : "Human",
      "class" : "Cleric",
      "alignment" : "Chaotic",
      "level" : 1,
      "armourClass" : 3,
      "hitPoints" : 9,
      "characteristics" : {
        "str" : 5,
        "int" : 10,
        "wis" : 8,
        "dex" : 18,
        "con" : 13,
        "chr" : 9
      },
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/characters/on32sMVRJ48W"
        },
        "gameCharacter" : {
          "href" : "http://localhost:8080/characters/on32sMVRJ48W"
        }
      }
    }, {
      "name" : "Bobert",
      "background" : "Merchant in the dungeon",
      "race" : "Human",
      "class" : "Thief",
      "alignment" : "Neutral",
      "level" : 2,
      "armourClass" : 3,
      "hitPoints" : 6,
      "characteristics" : {
        "str" : 13,
        "int" : 17,
        "wis" : 18,
        "dex" : 12,
        "con" : 12,
        "chr" : 17
      },
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/characters/sQua7xtze2Dq"
        },
        "gameCharacter" : {
          "href" : "http://localhost:8080/characters/sQua7xtze2Dq"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/characters"
    },
    "profile" : {
      "href" : "http://localhost:8080/profile/characters"
    }
  }
}

Creating a character

A POST request is used to create a character.

Request fields

Path	Type	Description	Constraints
name	String	Full name of character	Must not be blank
background	String	Background history and motivation	Must not be blank
race	String	One of Dwarf, Elf, Halfling, Human	Must not be null
class	String	One of Cleric, Fighter, MagicUser, Thief	Must not be null
level	Number	Experience and abilities scale. Higher is better	Must be at least 1 and at most 20
armourClass	Number	Armour and hit protection scale. Lower is better	Must be at least 0 and at most 9
hitPoints	Number	Damage a character can take. Higher is better	Must be at least 0
alignment	String	One of Chaotic, Lawful, Neutral	Must not be null
characteristics	Object	STR INT WIS DEX CON CHR	Must not be null

Path

Type

Description

Constraints

name

String

Full name of character

Must not be blank

background

String

Background history and motivation

Must not be blank

race

String

One of Dwarf, Elf, Halfling, Human

Must not be null

class

String

One of Cleric, Fighter, MagicUser, Thief

Must not be null

level

Number

Experience and abilities scale. Higher is better

Must be at least 1 and at most 20

armourClass

Number

Armour and hit protection scale. Lower is better

Must be at least 0 and at most 9

hitPoints

Number

Damage a character can take. Higher is better

Must be at least 0

alignment

String

One of Chaotic, Lawful, Neutral

Must not be null

characteristics

Object

STR INT WIS DEX CON CHR

Must not be null

Example request

$ curl 'http://localhost:8080/characters' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"name":"Bobert","background":"Merchant in the dungeon","race":"Human","class":"Thief","alignment":"Neutral","level":2,"armourClass":3,"hitPoints":6,"characteristics":{"str":13,"int":17,"wis":18,"dex":12,"con":12,"chr":17}}'

Example response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: http://localhost:8080/characters/sQua7xtze2Dq

Characteristics

Request fields-characteristics

Path	Type	Description	Constraints
str	Number	Strength attribute	Must be at least 3 and at most 18
int	Number	Intelligence attribute	Must be at least 3 and at most 18
wis	Number	Wisdom attribute	Must be at least 3 and at most 18
dex	Number	Dexterity attribute	Must be at least 3 and at most 18
con	Number	Constitution attribute	Must be at least 3 and at most 18
chr	Number	Charisma attribute	Must be at least 3 and at most 18

Path

Type

Description

Constraints

str

Number

Strength attribute