WIP: feat/rest

[griendt]

Description

All of the backend endpoint logic has been changed from a single endpoint with a type field to distinguish the intended action, to a RESTful implementation of the database resources. This will allow users/admins greater control over how to fetch information as well as how to save and update it, as it follows a universal and hierarchically logical standard. GET requests get information, POST requests post information, and so on, and the URLs indicate what (type of) resource is to be mutated.

You can list an overview of all endpoints generated by the current routes file by logging into the container and running:

php artisan route:list

Some of these routes, such as deleting a chat group, currently make no sense (as there is no system admin roles or such yet). Therefore they will always return a 403 Unauthorized response, despite existing for future purposes.

Type of change

• [ ] Bug fix (non-breaking change which fixes an issue)
• [x] New feature (non-breaking change which adds functionality)
• [x] Breaking change (fix or feature that would cause existing functionality to not work as expected)
• [x] This change requires a documentation update
• [ ] New dependencies/packages

Testing

I have called all endpoints manually through Insomnia (an alternative to Postman) and tested several scenarios. I absolutely wish to add automated unit tests (they will need to be added sooner or later anyway). At request I will add them, even for this PR!

• [ ] I have created automated tests for any new features
• [x] All automated tests pass (all out of 0 lol)
• [x] I have performed manual tests

Checklist:

• [x] I have performed a self-review of my own code
• [x] I have commented my code
• [ ] I have documented any new API endpoints in the postman collection
• [ ] I have added examples in postman for all status codes.
• [x] I have made corresponding changes to the README (if required)
• [ ] My changes generate no new warnings and do not break existing endpoints

Questions / Discussion

Before this PR could be merged, I'd like for the following to be answered:

• Is this format of the routes in order? I followed my own instincts and current knowledge of how to group the routes and what they should represent. Note the distinction between the terms room (referring to a game) and group (referring to a chat group).
• Considering messages are implemented as a sub-route of groups (which makes sense since they are inherently tied to a group), perhaps we should make groups a sub-route of rooms (since a chat group is inherently tied to a room!). This would imply the following URI template to get to messages:

  /api/rooms/{room}/groups/{group}/messages

  I only realised this while submitting this PR, so perhaps there are other things I missed that could be implemented better. See php artisan route:list for a full list of URI templates.

  • When a resource is created, this will result in an empty 201 Created response with a Location header with a URL as its value. This URL is the URL to send a GET request to, to get the state of the resource. From it, the internal id can be found. This follows the REST guidelines, but perhaps we wish to respond with the resource right away in the response to the POST request. This reduces the amount of calls needed, but also sends data each time which may be discarded most of the time.
  • When an id is used in a route template for a resource that doesn't'exist, a 404 Not Found response is given. This includes the scenario for which two resource ids are present in one URL, which both exist individually, but are not linked together. As an example, consider this request to delete a planned event:

    DELETE /api/rooms/23/events/34

    If room with id 23 exists and an event with id 34 exists, but the event does not belong to the room, a 404 Not Found is still thrown. The idea behind this is that we could (maybe) use identifiers rather than ids in the future and so a certain id may be reused (for example the first event in each room could have "1" as its identifier). There is a bit of Laravel magic in place to do this validation automatically, feel free to ask me about the details if the diff doesn't clarify sufficiently.

  • The join, leave and early-start endpoints are currently POST requests to /api/rooms/{room}/join, /api/rooms/{room}/leave and /api/rooms/{room}/start respectively. However there is no request body needed other than the session, and from a technical perspective it is an update to the room resource, in which case perhaps PUT is a better HTTP verb? Or is that too nitpicky?
• I have deliberatelly not yet updated the Postman documentation considering these are a lot of breaking changes and I want the proposed changes to be finalized and approved before putting them in Postman.

[QuinnBast]

Comments:

The REST URL updates are great. All endpoints appear to be working as expected with the exception of the PUT, PATCH, and DELETE methods which will return "401 Unauthorized" even when the user is authorized. Additionally, POST actions for for all endpoints except for the "register account" endpoint will throw the following error (but the trace varies based on which controller sends the response).

{
    "message": "Call to undefined function App\\Http\\Responses\\resource_url()",
    "exception": "Error",
    "file": "/var/www/app/Http/Responses/CreatedResponse.php",
    "line": 23,
    "trace": [
        {
            "file": "/var/www/app/Http/Controllers/RoomController.php",
            "line": 131,
            "function": "__construct",
            "class": "App\\Http\\Responses\\CreatedResponse",
            "type": "->"
        },
        {
            "function": "store",
            "class": "App\\Http\\Controllers\\RoomController",
            "type": "->"
        },
        {
            "file": "/var/www/vendor/laravel/framework/src/Illuminate/Routing/Controller.php",
            "line": 54,
            "function": "call_user_func_array"
        },

QoL changes

It may be useful to have the groups endpoint be a subset of the rooms. Something like api/rooms/2/groups which returns a list of groups in room 2 that the player is in. Having /api/groups we will likely need to filter out groups from other games the player is in.

In /api/room/#/events I think the filter and filter_arg parameters should not be required. If not set, just assume the user wants all events from the beginning of the room.