API development rules

API development best practices

Naming

Endpoints

Name of resource endpoint, need to be in plural

api/users
api/orders/{id}
api/stores/{id}/customers

Actions

Standard Laravel controller methods for base actions

index   - get list of resource;
show    - get single resource;
store   - save resource to database;
update  - update resource;
destroy - delete resource;

Actions Handled By Resource Controller

HTTP method	URI	Controller method	Route name
GET	/api/users	index	users.index
GET	/api/users/{id}	show	users.show
POST	/api/users	store	users.store
PUT/PATCH	/api/users/{id}	update	users.update
DELETE	/api/users/{id}	destroy	users.destroy

HTTP PATCH requests are to make a partial update on a resource.

The PATCH method is not a replacement for the POST or PUT methods. It applies a delta (diff) rather than replacing the entire resource.

Example:

HTTP GET /api/users
HTTP GET /api/users/123/address
HTTP GET /api/users/123/comments
HTTP GET /api/users?size=20&page=5
HTTP POST /api/users
HTTP PUT /api/users/123
HTTP PATCH /api/users/123/status-update
HTTP DELETE /api/users/123

Grouping and using names for resource endpoints

use App\Http\Controllers\UserController;

Route::controller(UserController::class)->group(function () {
    Route::get('/users/{id}', 'show')->name('users.show');
    Route::post('/users', 'store')->name('users.store');
    Route::put('/users/{id}', 'update')->name('users.update');
    Route::patch('/users/{id}/status-update', 'statusUpdate')->name('users.status-update');
    Route::delete('/users/{id}', 'destroy')->name('users.destroy');
});

Route prefixes

use App\Http\Controllers\UserController;

Route::prefix('admin')->group(function () {
    Route::controller(UserController::class)->group(function () {
        Route::get('/users/{id}', 'show')->name('users.show');
        Route::post('/users', 'store')->name('users.store');
    });
});

Response

Response need to be in JSON format
You can use ApiResponser trait for response
We need to use eloquent resource for response

Eloquent: API Resources

Example:

<?php

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\JsonResource;

class UserResource extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return array
     */
    public function toArray($request)
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            'created_at' => $this->created_at,
            'updated_at' => $this->updated_at,
        ];
    }
}

The main response codes

HTTP method	CRUD	Response code	Action
GET	Read	200 (OK), 404 (Not Found)	index/show
POST	Create	201 (Created)	store
PUT	Update/Replace	200 (OK), 204 (No Content), 404 (Not Found)	update
PATCH	Partial Update/Modify	200 (OK), 204 (No Content), 404 (Not Found)	update
DELETE	Delete	204 (OK), 404 (Not Found)	destroy

Please note: this is main response codes. We need to use the appropriate response code for the specific case like as 400(Bad request), 401(Unauthorized), 403(Forbidden), etc...