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 |
---|---|
|
Used to retrieve a resource |
|
Used to create a new resource |
|
Used to update an existing resource, including partial updates |
|
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 |
---|---|
|
The request completed successfully |
|
A new resource has been created successfully. The resource’s URI is available from the response’s
|
|
An update to an existing resource has been applied successfully |
|
The request was malformed. The response body will include an error providing further information |
|
The requested resource did not exist |
Headers
Every response has the following header(s):
Name | Description |
---|---|
|
The Content-Type of the payload, e.g. |
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 |
---|---|---|
|
|
The HTTP error that occurred, e.g. |
|
|
The path to which the request was made |
|
|
The HTTP status code, e.g. |
|
|
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 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"
}
}
}
Links
Relation | Description |
---|---|
|
|
|
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 |
---|---|---|
|
|
An array of Character resources |
|
|
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
Retrieve a character
A GET
request will retrieve the details of a character
Response fields
Path | Type | Description |
---|---|---|
|
|
Full name of character |
|
|
Background history and motivation |
|
|
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