Getting Started

Minimal Setup

Installation
```
composer require apie/rest-api
```
Ensure your Laravel project meets the package's PHP version requirements (check composer.json or README.md for specifics).
Basic Initialization The package is designed to work with Apie's ecosystem. Start by integrating it with Apie's core library (if not already installed):
```
composer require apie/apie
```
Initialize Apie in your Laravel service provider (e.g., AppServiceProvider):
```
use Apie\Apie;

public function boot()
{
    Apie::init();
}
```

First Use Case: Creating a REST API Resource Define a resource class (e.g., app/Http/Resources/UserResource.php):

use Apie\RestApi\Resource;

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

Use it in a controller:

use App\Http\Resources\UserResource;
use Apie\RestApi\Response;

public function show(User $user)
{
    return Response::resource(new UserResource($user));
}

Implementation Patterns

Core Workflows

Resource Transformation Extend Apie\RestApi\Resource to transform Eloquent models or collections into API responses:

class PostResource extends Resource
{
    public function toArray($request)
    {
        return [
            'title' => $this->title,
            'content' => Str::limit($this->content, 200),
            'author' => new UserResource($this->user),
        ];
    }
}

Use nested resources for relationships (e.g., UserResource inside PostResource).
Leverage Laravel's HasMany, BelongsTo relationships directly in toArray.

API Response Handling Use Apie\RestApi\Response for consistent API responses:

// Single resource
Response::resource(new UserResource($user));

// Collection
Response::collection(UserResource::collection($users));

// Custom response
Response::make([
    'success' => true,
    'data' => new UserResource($user),
]);

Request Validation Integrate with Laravel's validation by extending Apie\RestApi\Request:

use Apie\RestApi\Request;
use Illuminate\Support\Facades\Validator;

class StoreUserRequest extends Request
{
    public function rules()
    {
        return [
            'name' => 'required|string|max:255',
            'email' => 'required|email|unique:users',
        ];
    }
}

Use in controllers:

public function store(StoreUserRequest $request)
{
    // Validation handled automatically
    $user = User::create($request->validated());
}

API Versioning Apie supports versioning via middleware or route prefixes. Example middleware:

use Apie\RestApi\Versioning\VersionMiddleware;

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

Error Handling Customize error responses by extending Apie\RestApi\Exceptions\Handler:

use Apie\RestApi\Exceptions\Handler as ExceptionHandler;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

class CustomExceptionHandler extends ExceptionHandler
{
    public function render($request, NotFoundHttpException $exception)
    {
        return Response::error('Resource not found', 404);
    }
}

$this->app->singleton(ExceptionHandler::class, CustomExceptionHandler::class);

Integration Tips

Laravel Mix/Inertia: Use resources to transform data before sending to Inertia:

return Inertia::render('User/Show', [
    'user' => fn() => new UserResource($user),
]);

API Documentation: Pair with spatie/laravel-api-documentation to auto-generate OpenAPI specs from resources.

Testing: Mock resources in PHPUnit:

$resource = new UserResource(new User(['id' => 1, 'name' => 'John']));
$this->assertEquals('John', $resource->name);

Gotchas and Tips

Pitfalls

Missing Apie Core Dependency
- Issue: The apie/rest-api package relies on apie/apie. Forgetting to install it will cause autoloading errors.
- Fix: Always install both packages:
```
composer require apie/apie apie/rest-api
```
Resource Instantiation
- Issue: Resources must be instantiated with the underlying model/data. Passing null or incorrect data types will throw errors.
- Fix: Validate data before passing to resources:
```
if (!$user) {
    throw new NotFoundHttpException();
}
return Response::resource(new UserResource($user));
```
Circular References
- Issue: Nested resources with circular relationships (e.g., User has Post, Post has User) can cause infinite loops.
- Fix: Use ->toArray() explicitly or lazy-load relationships:
```
'author' => $this->whenLoaded('user', fn() => new UserResource($this->user)),
```
Middleware Order
- Issue: Apie's middleware (e.g., VersionMiddleware) must be placed before Laravel's VerifyCsrfToken or TrimStrings to avoid conflicts.
- Fix: Order middleware in app/Http/Kernel.php:
```
protected $middleware = [
    // ...
    \Apie\RestApi\Versioning\VersionMiddleware::class,
    \Illuminate\Foundation\Http\Middleware\VerifyCsrfToken::class,
];
```
Configuration Overrides
- Issue: Apie's default configurations (e.g., response formats) may conflict with Laravel's settings.
- Fix: Publish and customize the config:
```
php artisan vendor:publish --provider="Apie\RestApi\RestApiServiceProvider"
```
  Then override in config/apie.php.

Debugging Tips

Enable Apie Logging Add to config/apie.php:
```
'debug' => env('APP_DEBUG', false),
```
Logs will appear in storage/logs/laravel.log.

Dump Resources Use Laravel's dd() or dump() to inspect resource data:

$resource = new UserResource($user);
dd($resource->toArray(new Illuminate\Http\Request()));

Check HTTP Headers Apie may add custom headers (e.g., X-API-Version). Verify with:
```
$request->header('X-API-Version');
```

Extension Points

Custom Response Formats Extend Apie\RestApi\Response to add new formats (e.g., GraphQL):

class GraphQLResponse extends Response
{
    public static function graphql($data)
    {
        return response()->json(['data' => $data]);
    }
}

Dynamic Resource Fields Use Laravel's appends or accessors to add dynamic fields:

class UserResource extends Resource
{
    public function toArray($request)
    {
        return array_merge(parent::toArray($request), [
            'full_name' => $this->name . ' ' . $this->surname,
        ]);
    }
}

API Rate Limiting Integrate with Laravel's rate limiting by extending Apie's middleware:

use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\RateLimiter;

class CustomThrottleMiddleware
{
    public function handle(Request $request, Closure $next)
    {
        RateLimiter::hit($request->user()?->id ?? 'guest');
        return $next($request);
    }
}

Webhook Support Use resources to transform webhook payloads:

class WebhookResource extends Resource
{
    public function toArray($request)
    {
        return [
            'event' => $this->event,
            'payload' => $this->payload,
            'metadata' => $this->metadata,
        ];
    }
}

Rest Api Laravel Package