Build a full CRUD surface without resources

The explicit variant: four controllers, four requests, four responses for a single entity. Use this when you need full control over request/response shape, or the endpoints don’t all map to the same payload.

The resource-based approach is the default for CRUD. This guide is for the cases where it doesn’t fit — e.g. endpoints don’t share the same payload shape, you need custom request bodies per operation, or you need custom response envelopes.

We’ll build CRUD for a Pet: Create, View, Update, Delete. That’s 4 controllers + 4 requests + 4 responses = 12 classes. (List is a natural fifth — add it the same way.)

Directory layout

src/Http/
├── Controller/Pet/
│   ├── CreatePetController.php
│   ├── ViewPetController.php
│   ├── UpdatePetController.php
│   └── DeletePetController.php
├── Request/Pet/
│   ├── CreatePetRequest.php
│   ├── ViewPetRequest.php
│   ├── UpdatePetRequest.php
│   └── DeletePetRequest.php
└── Response/Pet/
    ├── CreatePetResponse.php
    ├── ViewPetResponse.php
    ├── UpdatePetResponse.php
    └── DeletePetResponse.php

Shared pieces

Everything below assumes JWT auth using the same BearerAuth scheme across all four routes — swap in your authenticator of choice.

use apivalk\apivalk\Security\RouteAuthorization;

$readAuth   = new RouteAuthorization('BearerAuth', ['pet'], ['pet:read']);
$writeAuth  = new RouteAuthorization('BearerAuth', ['pet'], ['pet:write']);
$deleteAuth = new RouteAuthorization('BearerAuth', ['pet'], ['pet:delete']);

In real code these would live inline in the controller’s getRoute() method — they’re split out here to keep the snippets compact.

Create

CreatePetRequest

<?php

declare(strict_types=1);

namespace App\Http\Request\Pet;

use apivalk\apivalk\Documentation\ApivalkRequestDocumentation;
use apivalk\apivalk\Documentation\Property\EnumProperty;
use apivalk\apivalk\Documentation\Property\FloatProperty;
use apivalk\apivalk\Documentation\Property\SimpleArrayProperty;
use apivalk\apivalk\Documentation\Property\StringProperty;
use apivalk\apivalk\Http\Request\AbstractApivalkRequest;

class CreatePetRequest extends AbstractApivalkRequest
{
    public static function getDocumentation(): ApivalkRequestDocumentation
    {
        $doc = new ApivalkRequestDocumentation();
        $doc->addBodyProperty(new StringProperty('name', 'Pet name'));
        $doc->addBodyProperty(new EnumProperty('species', 'Species', ['cat', 'dog', 'fish']));
        $doc->addBodyProperty((new FloatProperty('weight', 'Weight in kg'))->setIsRequired(false));
        // One-dimensional scalar array — accepts ["Rex", "Buddy"], validates each element is a string
        $doc->addBodyProperty(
            (new SimpleArrayProperty('nicknames', 'Alternate names', SimpleArrayProperty::TYPE_STRING))
                ->setIsRequired(false)
        );

        return $doc;
    }
}

CreatePetResponse

<?php

declare(strict_types=1);

namespace App\Http\Response\Pet;

use apivalk\apivalk\Documentation\ApivalkResponseDocumentation;
use apivalk\apivalk\Documentation\Property\SimpleArrayProperty;
use apivalk\apivalk\Documentation\Property\StringProperty;
use apivalk\apivalk\Http\Response\AbstractApivalkResponse;

class CreatePetResponse extends AbstractApivalkResponse
{
    /** @var array{pet_uuid: string, name: string, species: string, nicknames: string[]} */
    private $pet;

    public function __construct(array $pet)
    {
        $this->pet = $pet;
    }

    public static function getStatusCode(): int
    {
        return self::HTTP_201_CREATED;
    }

    public static function getDocumentation(): ApivalkResponseDocumentation
    {
        $doc = new ApivalkResponseDocumentation();
        $doc->setDescription('The newly created pet.');
        $doc->addProperty(new StringProperty('pet_uuid', 'Unique identifier'));
        $doc->addProperty(new StringProperty('name', 'Pet name'));
        $doc->addProperty(new StringProperty('species', 'Species'));
        $doc->addProperty(new SimpleArrayProperty('nicknames', 'Alternate names', SimpleArrayProperty::TYPE_STRING));

        return $doc;
    }

    public function toArray(): array
    {
        return $this->pet;
    }
}

CreatePetController

<?php

declare(strict_types=1);

namespace App\Http\Controller\Pet;

use apivalk\apivalk\Http\Controller\AbstractApivalkController;
use apivalk\apivalk\Http\Request\ApivalkRequestInterface;
use apivalk\apivalk\Http\Response\AbstractApivalkResponse;
use apivalk\apivalk\Router\Route\Route;
use apivalk\apivalk\Security\RouteAuthorization;
use App\Domain\Pet\PetRepository;
use App\Http\Request\Pet\CreatePetRequest;
use App\Http\Response\Pet\CreatePetResponse;

final class CreatePetController extends AbstractApivalkController
{
    /** @var PetRepository */
    private $repository;

    public function __construct(PetRepository $repository)
    {
        $this->repository = $repository;
    }

    public static function getRoute(): Route
    {
        return Route::post('/api/v1/pets')
            ->summary('Create a pet')
            ->routeAuthorization(new RouteAuthorization('BearerAuth', ['pet'], ['pet:write']));
    }

    public function __invoke(CreatePetRequest $request): AbstractApivalkResponse
    {
        $pet = $this->repository->create([
            'name'      => $request->body()->name,
            'species'   => $request->body()->species,
            'weight'    => $request->body()->weight,
            // already validated and cast to string[] by the time it reaches here
            'nicknames' => $request->body()->nicknames ?? [],
        ]);

        return new CreatePetResponse($pet);
    }
}

The route is the only thing the controller declares. The request class is read from the __invoke() parameter and the documented responses from the new expressions its body returns, so 403 and 422 land in the spec without being listed here. Build a response anywhere but in __invoke() and it is left out of the spec. See Controller.

View

ViewPetRequest

No request-specific properties needed — the path parameter is declared on the route.

<?php

declare(strict_types=1);

namespace App\Http\Request\Pet;

use apivalk\apivalk\Http\Request\AbstractApivalkRequest;

class ViewPetRequest extends AbstractApivalkRequest
{
}

ViewPetResponse

<?php

declare(strict_types=1);

namespace App\Http\Response\Pet;

use apivalk\apivalk\Documentation\ApivalkResponseDocumentation;
use apivalk\apivalk\Documentation\Property\FloatProperty;
use apivalk\apivalk\Documentation\Property\StringProperty;
use apivalk\apivalk\Http\Response\AbstractApivalkResponse;

class ViewPetResponse extends AbstractApivalkResponse
{
    /** @var array<string, mixed> */
    private $pet;

    public function __construct(array $pet)
    {
        $this->pet = $pet;
    }

    public static function getStatusCode(): int
    {
        return self::HTTP_200_OK;
    }

    public static function getDocumentation(): ApivalkResponseDocumentation
    {
        $doc = new ApivalkResponseDocumentation();
        $doc->addProperty(new StringProperty('pet_uuid', 'Unique identifier'));
        $doc->addProperty(new StringProperty('name', 'Pet name'));
        $doc->addProperty(new StringProperty('species', 'Species'));
        $doc->addProperty((new FloatProperty('weight', 'Weight in kg'))->setIsRequired(false));

        return $doc;
    }

    public function toArray(): array
    {
        return $this->pet;
    }
}

ViewPetController

<?php

declare(strict_types=1);

namespace App\Http\Controller\Pet;

use apivalk\apivalk\Documentation\Property\StringProperty;
use apivalk\apivalk\Http\Controller\AbstractApivalkController;
use apivalk\apivalk\Http\Request\ApivalkRequestInterface;
use apivalk\apivalk\Http\Response\AbstractApivalkResponse;
use apivalk\apivalk\Http\Response\NotFoundApivalkResponse;
use apivalk\apivalk\Router\Route\Route;
use apivalk\apivalk\Security\RouteAuthorization;
use App\Domain\Pet\PetRepository;
use App\Http\Request\Pet\ViewPetRequest;
use App\Http\Response\Pet\ViewPetResponse;

final class ViewPetController extends AbstractApivalkController
{
    /** @var PetRepository */
    private $repository;

    public function __construct(PetRepository $repository)
    {
        $this->repository = $repository;
    }

    public static function getRoute(): Route
    {
        return Route::get('/api/v1/pets/{pet_uuid}')
            ->summary('Get a pet by UUID')
            ->pathProperty(new StringProperty('pet_uuid', 'Pet identifier'))
            ->routeAuthorization(new RouteAuthorization('BearerAuth', ['pet'], ['pet:read']));
    }

    public function __invoke(ViewPetRequest $request): AbstractApivalkResponse
    {
        $pet = $this->repository->findByUuid($request->path()->pet_uuid);
        if ($pet === null) {
            return new NotFoundApivalkResponse();
        }

        return new ViewPetResponse($pet);
    }
}

Update

UpdatePetRequest

Only body properties live in the request class. The path parameter is declared on the route.

<?php

declare(strict_types=1);

namespace App\Http\Request\Pet;

use apivalk\apivalk\Documentation\ApivalkRequestDocumentation;
use apivalk\apivalk\Documentation\Property\FloatProperty;
use apivalk\apivalk\Documentation\Property\StringProperty;
use apivalk\apivalk\Http\Request\AbstractApivalkRequest;

class UpdatePetRequest extends AbstractApivalkRequest
{
    public static function getDocumentation(): ApivalkRequestDocumentation
    {
        $doc = new ApivalkRequestDocumentation();

        // Patch semantics — every body field is optional
        $doc->addBodyProperty((new StringProperty('name', 'Pet name'))->setIsRequired(false));
        $doc->addBodyProperty((new FloatProperty('weight', 'Weight in kg'))->setIsRequired(false));

        return $doc;
    }
}

UpdatePetResponse

<?php

declare(strict_types=1);

namespace App\Http\Response\Pet;

use apivalk\apivalk\Documentation\ApivalkResponseDocumentation;
use apivalk\apivalk\Documentation\Property\StringProperty;
use apivalk\apivalk\Http\Response\AbstractApivalkResponse;

class UpdatePetResponse extends AbstractApivalkResponse
{
    /** @var array<string, mixed> */
    private $pet;

    public function __construct(array $pet)
    {
        $this->pet = $pet;
    }

    public static function getStatusCode(): int
    {
        return self::HTTP_200_OK;
    }

    public static function getDocumentation(): ApivalkResponseDocumentation
    {
        $doc = new ApivalkResponseDocumentation();
        $doc->addProperty(new StringProperty('pet_uuid', 'Unique identifier'));
        $doc->addProperty(new StringProperty('name', 'Pet name'));

        return $doc;
    }

    public function toArray(): array
    {
        return $this->pet;
    }
}

UpdatePetController

<?php

declare(strict_types=1);

namespace App\Http\Controller\Pet;

use apivalk\apivalk\Documentation\Property\StringProperty;
use apivalk\apivalk\Http\Controller\AbstractApivalkController;
use apivalk\apivalk\Http\Request\ApivalkRequestInterface;
use apivalk\apivalk\Http\Response\AbstractApivalkResponse;
use apivalk\apivalk\Http\Response\NotFoundApivalkResponse;
use apivalk\apivalk\Router\Route\Route;
use apivalk\apivalk\Security\RouteAuthorization;
use App\Domain\Pet\PetRepository;
use App\Http\Request\Pet\UpdatePetRequest;
use App\Http\Response\Pet\UpdatePetResponse;

final class UpdatePetController extends AbstractApivalkController
{
    /** @var PetRepository */
    private $repository;

    public function __construct(PetRepository $repository)
    {
        $this->repository = $repository;
    }

    public static function getRoute(): Route
    {
        return Route::patch('/api/v1/pets/{pet_uuid}')
            ->summary('Update a pet')
            ->pathProperty(new StringProperty('pet_uuid', 'Pet identifier'))
            ->routeAuthorization(new RouteAuthorization('BearerAuth', ['pet'], ['pet:write']));
    }

    public function __invoke(UpdatePetRequest $request): AbstractApivalkResponse
    {
        $uuid = $request->path()->pet_uuid;

        if (!$this->repository->exists($uuid)) {
            return new NotFoundApivalkResponse();
        }

        $patch = [];
        if ($request->body()->has('name')) {
            $patch['name'] = $request->body()->name;
        }
        if ($request->body()->has('weight')) {
            $patch['weight'] = $request->body()->weight;
        }

        $pet = $this->repository->update($uuid, $patch);

        return new UpdatePetResponse($pet);
    }
}

Delete

DeletePetRequest

No request-specific properties needed — the path parameter is declared on the route.

<?php

declare(strict_types=1);

namespace App\Http\Request\Pet;

use apivalk\apivalk\Http\Request\AbstractApivalkRequest;

class DeletePetRequest extends AbstractApivalkRequest
{
}

DeletePetResponse

For idempotent deletes you can return the built-in DeletedApivalkResponse (204) instead of writing your own. If you want to emit a confirmation payload, write one like the others:

<?php

declare(strict_types=1);

namespace App\Http\Response\Pet;

use apivalk\apivalk\Documentation\ApivalkResponseDocumentation;
use apivalk\apivalk\Documentation\Property\StringProperty;
use apivalk\apivalk\Http\Response\AbstractApivalkResponse;

class DeletePetResponse extends AbstractApivalkResponse
{
    /** @var string */
    private $uuid;

    public function __construct(string $uuid)
    {
        $this->uuid = $uuid;
    }

    public static function getStatusCode(): int
    {
        return self::HTTP_200_OK;
    }

    public static function getDocumentation(): ApivalkResponseDocumentation
    {
        $doc = new ApivalkResponseDocumentation();
        $doc->addProperty(new StringProperty('pet_uuid', 'Deleted identifier'));

        return $doc;
    }

    public function toArray(): array
    {
        return ['pet_uuid' => $this->uuid];
    }
}

DeletePetController

<?php

declare(strict_types=1);

namespace App\Http\Controller\Pet;

use apivalk\apivalk\Documentation\Property\StringProperty;
use apivalk\apivalk\Http\Controller\AbstractApivalkController;
use apivalk\apivalk\Http\Request\ApivalkRequestInterface;
use apivalk\apivalk\Http\Response\AbstractApivalkResponse;
use apivalk\apivalk\Http\Response\NotFoundApivalkResponse;
use apivalk\apivalk\Router\Route\Route;
use apivalk\apivalk\Security\RouteAuthorization;
use App\Domain\Pet\PetRepository;
use App\Http\Request\Pet\DeletePetRequest;
use App\Http\Response\Pet\DeletePetResponse;

final class DeletePetController extends AbstractApivalkController
{
    /** @var PetRepository */
    private $repository;

    public function __construct(PetRepository $repository)
    {
        $this->repository = $repository;
    }

    public static function getRoute(): Route
    {
        return Route::delete('/api/v1/pets/{pet_uuid}')
            ->summary('Delete a pet')
            ->pathProperty(new StringProperty('pet_uuid', 'Pet identifier'))
            ->routeAuthorization(new RouteAuthorization('BearerAuth', ['pet'], ['pet:delete']));
    }

    public function __invoke(DeletePetRequest $request): AbstractApivalkResponse
    {
        $uuid = $request->path()->pet_uuid;

        if (!$this->repository->exists($uuid)) {
            return new NotFoundApivalkResponse();
        }

        $this->repository->delete($uuid);

        return new DeletePetResponse($uuid);
    }
}

When to use this over a resource

Use the manual variant when:

• Payloads differ between endpoints — e.g. Create accepts species but Update doesn’t, or the view response returns an expanded shape with joined data.
• Responses need custom envelopes — {"data": ...} is fine for resources, but a legacy API might expect {"pet": ...} with metadata at the root.
• You want complete control over validation — per-endpoint getDocumentation() gives you surgical control over required/optional fields, descriptions, and examples.

For uniform entities (same shape across operations), prefer resources — the 12-class scaffold collapses to 6.