Standardise APIResource structures

Throughout the database, objects contain references to other objects in the database. Most commonly, references have the following structure:

{
    "name": "Name of Referenced Resource",
    "url": "/api/.../..."
}

However, elsewhere, we several variations on this structure, for example, in some attributes of Class objects, we have cases like this:

"starting_equipment": {
    "url": "/api/starting-equipment/1",
    "class": "Barbarian"
},

In this case, the class attribute is pointless, as starting_equipment is a property of the Class object, which already contains it’s own name. Only the url attribute is useful here.

When querying collections using the API, we get an array of references of the following format:

{
    "index": "resource-index",
    "name": "Resource Name",
    "url": "/api/resource/url"
}

I believe this is the ideal structure for references, and should be implemented across the database, for these reasons:

• The url is provided in order to fetch the resource from the API - this is the most important part of the reference - it needs to stay
• index is useful for managing the data client-side. For example, it can be used to fetch the resource from a local cache, as a key for the resource in a collection, etc.
  • This is useful as the index does not always correspond with the final element of the url, so cannot be reliably parsed from the url attribute. e.g. /api/classes/monk/levels - the index of the referenced resource is nowhere to be seen in the URL.
• The name is provided as a human-readable identifier of the resource. This comes in handy if displaying a list of objects to the user in a meaningful way, without having to fetch each object from the API.
  • name should be optional, as there are scenarios where it is less useful or non-applicable, for example Starting Equipment and Level strctures lack a name attribute.

[ogregoire]

My quick personal take here (because I have a lot on my plate in private life at the moment) is that I don’t see why levels and starting_equipment are separate from the class. They’re strongly linked to the classes and they should probably be better in the class.json file. So far I was always thinking that if we can make it work like this, why not, if we can’t, we should merge. In my view, it was always a nonsense that they’re in their own file.

So if someone finds there’s too much inconsistency, I’m of the advice that we merge class_levels.json and starting_equipment.json into class.json (and maybe include the spells_list.json for good measure).

[fergcb]

keep your eyes peeled for the PR!