cttools.apib

FORMAT: 1A
HOST: http://127.0.0.1:8000/api/v1

# CT Tools (v1) API

CT Tools is a simple API for generating and managing Classic Traveller (CT) role playing game data.

This API conforms to the default Laravel [Eloquent: API Resources](https://laravel.com/docs/5.5/eloquent-resources) format introduced in Laravel 5.5.

> **Note** to render this API documentation as HTML from the source  blueprint (.apib) file use `aglio --theme-variables slate -i cttools.apib -o cttools.html`.

# Group Characters

Resources related to player and non-player characters. Provides for the
* automatic generation or character data for non-player characters (NPC),
* storage of pre-generated character data for players,
* update and deletion of stored character data, and
* retrieval of all character data in bulk as well as indavidually for generation of character data sheets.

<table>
  <tr>
    <th>URL</th><th>GET<br>read</th><th>POST<br>create</th><th>PUT<br>update</th><th>DELETE</th>
  </tr>
  <tr>
    <td>/characters</td><td>Returns a list of characters</td><td>Create a new character</td><td>(405)</td><td>(405)</td>
  <tr>
    <td>/characters/{id}</td><td>Returns a specific character</td><td>(405)</td><td>Updates a specific character</td><td>Deletes a specific character</td>
  </tr>
</table>

## Character Collection [/characters]

### List All Characters [GET]

List full detail on all characters.
The universal personality profile (UPP) is represented by an integer from 1 to 15.

+ Response 200 (application/json)
    + Attributes (object)
        + data (array[Character Detail])

### Generate a New Character [POST]

You may generate new characters using this action.
This action takes a JSON payload, specifying the name and sex of the character, as part of the request.
The response header contains the location of the newly generated character.
The response body contains full character data;
* new unique id,
* name and sex given in the request,
* a noble title based on the character's social standing,
* randomly generated (2D roll) universal personality profile (UPP) with initial values from 2 to 12.

+ Request (application/json)
  + Attributes (array[Character])

+ Response 201 (application/json)

    + Headers

            Location: /characters/2

    + Attributes (object)
        + data (Character Detail)


### 405 Method Not Supported [PUT]

+ Response 405 (application/json)
  + Attributes (Error405)

### 405 Method Not Supported [DELETE]

+ Response 405 (application/json)
  + Attributes (Error405)


## Character [/characters/{id}]

+ Parameters
    + id (number) - ID of the Character in the form of an integer.

### View a Character's Detail [GET]

+ Response 200 (application/json)
    + Attributes (object)
        + data (Character Detail)

### 405 Method Not Supported [POST]

+ Response 405 (application/json)
  + Attributes (Error405)

### Update a Character's Detail [PUT]

+ Parameters
    + id (number) - ID of the Character in the form of an integer

+ Response 200 (application/json)
    + Attributes (object)
        + data (Character Detail)


### Delete a Character [DELETE]

+ Parameters
    + id (number) - ID of the Character in the form of an integer

+ Response 204  (application/json)


# Data Structures

## Character (object)
The minimum required values when specifying a new character.

### Properties

+ id: `2` (number, required) - The unique identifier for a character.
+ name: `El Barto` (string, required) - Name of the character.

## Character Detail (Character)
Optional details of a character.

### Properties

+ title: `Duke` (string) - Hereditary title.
+ sex: `M` (string) - Sex of the character. ISO/IEC 5218. NULL, M, F, X.

## Attribute (object)
An attribute of a character, either a skill, item, or characteristic.

### Properties

+ id: `1` (number, required) - The unique identifier for a attribute.
+ type: `UPP` (string, required) - The type of the attribute.
+ name: `dexterity` (string, required) - The name of the attribute.
+ description: `Dexterity measures physical coordination.` (string) - The short description of the attribute.
+ notes: `` (string) - Long form extra notes describing the attribute if required.
+ datatype: `number` (string) - The datatype of the attribute. One of: number, string.
+ `min_value`: `0` (number) - For numeric attributes, the minimum value this attribute can take.
+ `max_value`: `15` (number) - For numeric attributes, the maximum value this attribute can take.
+ weight: `500` (number) - Weight in grams.
+ cost: `10` (number) - Cost in credits.
+ tl: `9` (number) - Technology level.


## Error400 (object)

+ errors (array)
  + status: `400` (string, required) - HTTP status code
  + code: `1400` (string, required) - specific error code
  + title: `Bad Request` (string, required) - specific error message
  + detail: `The request could not be understood by the server due to malformed syntax.` (string, required) - specific detail message

## Error404 (object)

+ errors (array)
  + status: `404` (string, required)
  + code: `1404` (string, required)
  + title: `Not Found` (string, required)
  + detail: `The requested resource could not be found but may be available in the future.` (string, required) - specific detail message

## Error405 (object)

+ errors (array)
  + status: 405 (string, required)
  + code: 1405 (string, required)
  + title: Method Not Supported (string, required)
  + detail: The method specified in the Request Line is not allowed for the resource identified by the Request-URI. (string, required) - specific detail message