question-mark

Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

Standardise APIResource structures

See original GitHub issue

Issue Description

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.

Issue Analytics

  • State:closed
  • Created 2 years ago
  • Comments:15 (7 by maintainers)

github_iconTop GitHub Comments

2reactions
ogregoirecommented, Aug 31, 2020

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).

1reaction
fergcbcommented, Aug 26, 2020

keep your eyes peeled for the PR!

Read more comments on GitHub >

github_iconTop Results From Across the Web

Response() not respecting API resource structure - Laracasts
I have a strange (at least to my tired eyes) problem where using the response() function to return an API resource is ignoring...
Read more >
Best practices for REST API design - Stack Overflow Blog
Learn how to design REST APIs to be easy to understand for anyone, future-proof, secure, and fast since they serve data to clients...
Read more >
Standardizing REST API response structure? : r/laravel - Reddit
I find that, as my REST APIs grow in size and complexity, it's useful to have a standardized format for returning success or...
Read more >
Proper API design in Laravel - Martin Joo
JSON API gives you a standardized way to structure your resources. If you like it, you can use it as your default choice....
Read more >
Tutorial: Extending a data model entity and its API resource
In this tutorial, you will extend a base configuration data model entity with additional fields. You will then configure the corresponding API ......
Read more >

github_iconTop Related Medium Post

No results found

github_iconTop Related StackOverflow Question

No results found

github_iconTroubleshoot Live Code

Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start Free

github_iconTop Related Reddit Thread

No results found

github_iconTop Related Hackernoon Post

No results found

github_iconTop Related Tweet

No results found

github_iconTop Related Dev.to Post

No results found

github_iconTop Related Hashnode Post

No results found