Overview

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

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

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

Content-Type

The Content-Type of the payload, e.g. 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

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":"2022-07-19T13:11:32.697+00:00","status":400,"error":"Bad Request","path":"/characters"}

Hypermedia

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

Index

The index provides the entry point into the service.

Accessing the index

A GET request is used to access the index

Response fields

Path Type Description

_links

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: 171

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

characters

The Characters resource

profile

The ALPS resource

Characters

The Characters resources is used to create and list characters

Listing characters

A GET request will list all of the service’s characters.

Response fields

Path Type Description

_embedded.characters

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: 2573

{
  "_embedded" : {
    "characters" : [ {
      "name" : "Slammer Kyntire",
      "background" : "First-level Fighter searching for the Sword of the Sorcerer.",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/characters/1"
        },
        "gameCharacter" : {
          "href" : "http://localhost:8080/characters/1"
        }
      }
    }, {
      "name" : "Hotfa Nap",
      "background" : "First-level Sorceress from a nomad tribe in the Mesta Desert.",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/characters/2"
        },
        "gameCharacter" : {
          "href" : "http://localhost:8080/characters/2"
        }
      }
    }, {
      "name" : "Gripper 'The Skin' Longshank",
      "background" : "First-level Thief from a tribe on the Albine empire border.",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/characters/3"
        },
        "gameCharacter" : {
          "href" : "http://localhost:8080/characters/3"
        }
      }
    }, {
      "name" : "Zhod Thobi",
      "background" : "First-level Cleric joins party as N.P.C and receives equal share of treasure.",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/characters/4"
        },
        "gameCharacter" : {
          "href" : "http://localhost:8080/characters/4"
        }
      }
    }, {
      "name" : "Belisarius",
      "background" : "First-level Thief N.P.C survivor. Currently hiding, if located will join party.",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/characters/5"
        },
        "gameCharacter" : {
          "href" : "http://localhost:8080/characters/5"
        }
      }
    }, {
      "name" : "Rosa Dobbit",
      "background" : "First-level Fighter, N.P.C survivor. Currently captive, if released will join party.",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/characters/6"
        },
        "gameCharacter" : {
          "href" : "http://localhost:8080/characters/6"
        }
      }
    }, {
      "name" : "Bobert",
      "background" : "Merchant in the dungeon",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/characters/7"
        },
        "gameCharacter" : {
          "href" : "http://localhost:8080/characters/7"
        }
      }
    } ]
  },
  "_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 null

background

String

Background history and motivation

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"}'

Example response

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

Character

The Character resource is used to retrieve, update, and delete individual characters

Relation Description

self

This character

gameCharacter

Link to the gameCharacter resource

Retrieve a character

A GET request will retrieve the details of a character

Response fields

Path Type Description

name

String

Full name of character

background

String

Background history and motivation

_links

Object

Links to other resources

Example request

$ curl 'http://localhost:8080/characters/1' -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: 289

{
  "name" : "Slammer Kyntire",
  "background" : "First-level Fighter searching for the Sword of the Sorcerer.",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/characters/1"
    },
    "gameCharacter" : {
      "href" : "http://localhost:8080/characters/1"
    }
  }
}

Update a Character

A PATCH request is used to update a Character

Request fields

Path Type Description Constraints

name

String

Full name of character

Must not be null

background

String

Background history and motivation

Example request

$ curl 'http://localhost:8080/characters/8' -i -X PATCH \
    -H 'Content-Type: application/hal+json;charset=UTF-8' \
    -d '{"name":"Update name","background":"Update background"}'

Example response

HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers