How to Build a Modern Public API with Laravel

Creating a public API is a fantastic way to empower your community and enable integrations and automation for your application or service. Here’s a look at how you can architect and launch a robust public API using modern PHP practices and the Laravel framework, with practical code examples.

Foundation: Laravel and PHP

Start with a reliable framework. Laravel is a top choice for PHP applications, offering expressive routing, robust middleware, and built-in support for RESTful APIs. Its resource classes and Eloquent ORM make serialization and structuring responses straightforward

routes/api.php

 Route::prefix('api/v1')->group(function () {
    Route::get('/items', [ItemController::class, 'index']);
    Route::get('/item/{id}/versions', [ItemVersionController::class, 'index']);
    Route::get('/app/versions', [AppVersionController::class, 'index']);
});

Versioning and Structure

Organize endpoints by version, e.g., app/Http/Controllers/Api/V1/, to allow for future changes without breaking existing integrations. Use dedicated controllers for resource groups.

app/Http/Controllers/Api/V1/ItemController.php

namespace App\Http\Controllers\Api\V1;

use App\Http\Controllers\Controller;
use App\Http\Resources\ItemResource;
use App\Models\Item;

class ItemController extends Controller
{
    public function index()
    {
        return ItemResource::collection(Item::paginate(15));
    }
}

app/Http/Resources/ItemResource.php

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\JsonResource;

class ItemResource extends JsonResource
{
    public function toArray($request)
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'created_at' => $this->created_at,
            // ...other fields
        ];
    }
}

Automated API Documentation

Use Scribe, a Laravel package that generates API documentation from code annotations. This produces interactive, always-up-to-date documentation at a /docs endpoint, with code samples and a downloadable Postman collection.

Example Endpoints

• GET /api/v1/items — List all items
• GET /api/v1/item/{id}/versions — Retrieve version history for a specific item
• GET /api/v1/app/versions — List platform versions

Consistent Response Format

Use Laravel’s helpers or custom response classes to ensure your API responses are consistent. Always return structured data, pagination metadata, and standardized error responses.

Example of a standard API response

{
  "success": true,
  "data": [
    { "id": 1, "name": "Widget" },
    { "id": 2, "name": "Gadget" }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 5
  }
}

Developer Features

• Versioned API: Protects consumers from breaking changes.
• Auto-generated Docs: Reduces maintenance and increases reliability.
• Try-It-Out Tools: Let developers experiment directly in the docs.
• Postman/OpenAPI Support: Facilitates quick onboarding.

Conclusion

Building a public API with Laravel and PHP means leveraging powerful tools for routing, serialization, and documentation. With proper structure, robust documentation, and a commitment to consistency, you can deliver an API that accelerates innovation and enables your project’s ecosystem to grow.

Whether you’re supporting mobile apps, third-party integrations, or community-built tools, this approach ensures your API is modern, maintainable, and developer-friendly.