REST practices

The SynergyCP API is laid out in a RESTful format. Below are some helpful recommendations for sticking to this format. It will help to familiarize yourself with the Directory Structure first.

By default, the package is accessible via the API at /api/pkg/<package>. When creating a new RESTful resource, it should have its own directory like Report. You can generate this directory using php artisan pkg:dev:scaffold:api from the Developer Package. Don't forget to add the ServiceProvider from that directory to the ServiceProvider of the parent directory if there is one, or to the provides/Providers.php file otherwise. Once php artisan route:cache is run, the following RESTful API will be available (using Report as an example, starting from /api/pkg/abuse)

GET /report: List Abuse Reports

• ?server=<server ID> etc. filters the results
• ReportListRequest validate the List request, enact user-requested ordering of the result
• ReportFilterService filters the viewable Reports and query-level filtering (?server= etc)
• ReportTransformer outputs the resulting items in array form

POST /report: Create an Abuse Report

• ReportFilterService->viewable() is run which can verify authentication
• ReportUpdateService checks relevant permissions and sets the attributes of the Report
• ReportTransformer outputs the result object

GET /report/1: Show specific Abuse Report

• ReportFilterService filters to viewable Reports
• ReportTransformer outputs the result object

PATCH /report/1,2,3: Update one or multiple Abuse Reports (comma-separated)

• ReportFilterService filters to viewable Reports
• ReportPatchRequest validates the request
• ReportUpdateService checks relevant permissions and updates the attributes of the Report(s)

DELETE /report/1,2,3: Delete one or multiple Abuse Reports (comma-separated)

• ReportFilterService filters to viewable Reports
• ReportDeleteService checks permissions and deletes the Report(s).

Lists

ListRequests extend App\Http\Requests\ListRequest which handles validation of the request and ordering of the list. It can also be used for simple filtering. To add an order, add an item to the $this->orders in the boot() method of the extended class (see ReportListRequest from the Abuse Package for an example).

$this->orders = [
    // nickname input will be ordered as 'nickname' column automatically.
    'nickname',
    
    // 'client' order will run the Closure:
    'client' => function ($query, $order) {
        // You could do a join here, for instance.
        $query->orderBy('client_id', $order);
    },
];