Download the PHP package libinkk/api-starter without Composer

libinkk/api-starter

A production-ready API foundation for Laravel applications with standardized responses, filtering, sorting, searching, pagination, sparse fields, relationship includes, validation, exception handling, request IDs, error codes, localization, versioning, and Artisan tooling.

It extends Laravel with opinionated best practices. It does not replace Laravel.

Table of contents

• Requirements
• Installation
• Quick start
• Response envelope
• Api facade helpers
• Exception handling
• Validation responses
• ApiQuery tutorial
  • Filtering
  • Searching
  • Sorting
  • Pagination
  • Sparse fields
  • Relationship includes
• Request ID
• Performance (response time)
• Error codes
• Localization
• API versioning
• Middleware
• Artisan commands
• Configuration reference
• End-to-end controller tutorial
• Testing
• Out of scope
• Changelog and license

Requirements

Installation

Publish config and language files:

Or publish manually:

Run the doctor to verify setup:

Register middleware (recommended)

In Laravel 11+ (bootstrap/app.php):

Or use aliases on specific routes:

Aliases registered by the package:

Quick start

Example request:

Response envelope

Success

Error

Paginated responses automatically fill meta (current page, last page, total, per page) and links (first, last, prev, next).

Optional timestamp can be enabled in config:

Api facade helpers

Method reference

Laravel API Resources and paginators are supported as $data.

Exception handling

When enabled, API requests (Accept: application/json, or paths under /api/*) receive the package envelope automatically.

Custom API exceptions

Toggle with:

Set 'debug' => true (or API_STARTER_DEBUG=true) to expose detailed exception meta in development.

Validation responses

Form request / validator failures are converted to:

You can also return validation manually:

ApiQuery tutorial

ApiQuery is an allowlist-based query pipeline for Eloquent.

Filtering

Query examples

Nested filter keys (optional):

Only allowlisted filters are applied. Unknown query keys are ignored.

Searching

Default driver is SQL LIKE across the given columns (OR).

Custom search driver:

Sorting

Disallowed sort fields are ignored.

Pagination

Also available:

Config defaults:

Helper utilities:

Sparse fields

Reduce payload size by selecting only allowlisted columns.

Notes:

• Only allowlisted fields are selected.
• Primary key is always included automatically when fields are requested.
• Disallowed fields (for example password) are ignored.

Relationship includes

Eager-load allowlisted relations only (prevents arbitrary relation loading).

Request ID

Middleware api.request-id assigns a unique ID per request.

• Generates values like REQ-8A7C9D2X when missing
• Keeps an incoming X-Request-ID when provided
• Adds the ID to the response header and response envelope request_id

Useful for debugging, logging, support tickets, and monitoring.

Performance (response time)

Middleware api.performance measures how long the request took and exposes it like 40.12ms.

Output

Header

JSON body

Setup

Register api.performance as the outermost API middleware so timing covers the full request:

Config

Error codes

Stable codes make client-side branching easier.

Built-in codes:

• VALIDATION_FAILED
• MODEL_NOT_FOUND
• UNAUTHENTICATED
• FORBIDDEN
• ROUTE_NOT_FOUND
• QUERY_EXCEPTION
• HTTP_EXCEPTION
• SERVER_ERROR
• UNSUPPORTED_API_VERSION

Add custom codes in config:

Prefer language files for localized custom codes:

Localization

Supported locales out of the box:

Set locale via (in order of priority):

1. Header X-Locale: de
2. Query ?lang=es
3. Accept-Language

Success/error messages use:

Publish and customize:

Config:

API versioning

Resolve version from:

1. Header X-API-Version: v2
2. Query ?api_version=v2
3. Path /api/v2/...

Unsupported versions return 400 with UNSUPPORTED_API_VERSION.

Example route groups:

Middleware

Each feature can be disabled independently via features.* flags.

Artisan commands

Generated classes land under app/Filters, app/Sorts, and app/Transformers by default.

Use a custom filter with ApiQuery:

Configuration reference

File: config/api-starter.php

Feature flags

Nothing is mandatory. Disable what you do not need without editing package source.

Query parameters

End-to-end controller tutorial

1. Model

2. Controller

3. Routes

4. Try it

Check the response header and body for timing:

Testing

Package tests use Orchestra Testbench + PHPUnit.

In your app tests you can assert JSON structure:

Out of scope

This package intentionally does not include:

• Authentication / Authorization / RBAC
• Payment gateways
• File uploads
• Notifications
• Queue management
• Admin panels
• Business domain logic

Keep those in dedicated packages or your application.

Design principles

• Modular and optional
• Configurable (no source edits required)
• Consistent response envelopes
• Framework-friendly (PSR-12, SOLID, DI, interfaces)
• Compatible with Laravel API Resources, config cache, and route cache

Support

• Author: Libin K K
• Website: https://www.libinkk.in
• Email: [email protected]
• Mobile: +91 77087 82197

Changelog and license

See CHANGELOG.md for release notes.

Current package version: 1.0.0

Licensed under the MIT license.