Nugsoft Developer Guides

API Standards

RESTful Conventions

Follow RESTful principles for API design. Use resourceful routes and controllers, and standard HTTP methods:

  • GET: Retrieve resources
  • POST: Create resources
  • PUT/PATCH: Update resources
  • DELETE: Remove resources

Example:

Route::apiResource('users', UserController::class);
  • Use singular resource names in controllers (e.g., UserController).
  • Use plural resource names in routes (e.g., /users).

Status Codes

Return appropriate HTTP status codes for all API responses:

  • 200 OK: Successful GET or PUT/PATCH
  • 201 Created: Successful POST
  • 204 No Content: Successful DELETE
  • 400 Bad Request: Invalid input
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 422 Unprocessable Entity: Validation errors
  • 500 Internal Server Error: Unexpected errors

Example:

return response()->json(['message' => 'User created'], 201);

Versioning

Prefix API routes with a version number to allow for future changes without breaking clients.

Route::prefix('v1')->group(function () {
    Route::apiResource('users', UserController::class);
});

Pagination, Filtering, Sorting

Support pagination, filtering, and sorting for endpoints that return collections.

  • Use query parameters: ?page=2&per_page=10&sort=name&filter[active]=1
  • Return pagination metadata in the response.

Example:

public function index(Request $request) {
    $users = User::where('active', 1)->paginate(10);
    return UserResource::collection($users);
}

API Resources

Use Laravel API Resource classes for consistent, structured JSON responses.

  • Transform data using Resource classes (e.g., UserResource).
  • Hide sensitive fields and format output as needed.

Example:

class UserResource extends JsonResource {
    public function toArray($request) {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
        ];
    }
}

Error Responses

Return structured error responses with a message, code, and optional details.

return response()->json([
    'error' => [
        'message' => 'Validation failed',
        'code' => 422,
        'details' => $validator->errors(),
    ]
], 422);

Best Practices

  • Document all API endpoints and request/response formats.
  • Use authentication (e.g., Sanctum) for protected endpoints.
  • Validate all input and return clear error messages.
  • Use consistent naming and structure for all endpoints.
  • Avoid exposing internal implementation details in API responses.
Back to Top