A framework for rapid REST API development.
- Require the repository in your
composer.json
- Extend the packaged route provider for your app:
<?php
namespace MyApp\Providers;
use Fuzz\ApiServer\Providers\RouteServiceProvider as ServiceProvider;
class RouteServiceProvider extends ServiceProvider
{
// ...
}
- Extend the packaged exception handler for your app:
<?php
namespace MyApp\Exceptions;
use Fuzz\ApiServer\Exception\Handler as ExceptionHandler;
class Handler extends ExceptionHandler
{
// ...
}
Register a base controller extending Fuzz\ApiServer\Routing\Controller:
<?php
class MyBaseController extends Fuzz\ApiServer\Routing\Controller {}
Register routes pointing to extensions of your base controller. Make a catch-all route to send all other requests through your base controller.
<?php
class MySpecificController extends MyBaseController
{
public function someEndpoint() {
return $this->succeed('Foobar!');
}
}
Route::get('some-endpoint', 'MySpecificController@someEndpoint');
// ...
Route::controller(null, 'MyBaseController');
Resource controllers extend functionality of fuzz/magic-box
repositories and provide CRUD and authorization functionality out of the box.
Your application should extend the base fuzz/api-server
Resource controller:
<?php
namespace MyApp\Http\Controllers;
use Fuzz\ApiServer\Routing\ResourceController as BaseResourceController;
class ResourceController extends BaseResourceController
{
// ...
}
And to define a route for a resource in your routes.php
: $router->restful('User');
. The restful
route macro is defined in Fuzz\ApiServer\Providers\RouteServiceProvider
.
If any resources need to override the default functionality, you can create a specific ResourceController by extending your application's base ResourceController:
app/Http/Controllers/Resources/Users.php
:
<?php
namespace MyApp\Http\Controllers\Resources;
use Illuminate\Http\Request;
use Fuzz\MagicBox\Contracts\Repository;
use MyApp\Http\Controllers\ResourceController;
class Users extends ResourceController
{
public function index(Repository $repository, Request $request)
{
// custom index...
{
}
You can then point your restful route to your custom ResourceController:
in routes.php
: $router->restful('Run', 'Resources\Users');
Send mixed data:
<?php
return $this->succeed(['foo' => 'bar']);
Send any arrayable data:
<?php
return $this->succeed(Model::all());
Send any paginated data:
<?php
return $this->succeed(Model::paginate($this->getPerPage(Model::DEFAULT_PER_PAGE)));
Send RESTful errors with error codes and optional data:
<?php
$this->badRequest('That button does not do what you think it does.');
$this->forbidden('Maybe next time.');
$this->notFound();
Raise RESTful error exceptions outside of the controller context:
<?php
throw new Symfony\Component\HttpKernel\Exception\ConflictHttpException;
throw new Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
throw new Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
throw new Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
Require the user to provide certain parameters:
<?php
// Magically works with either JSON or form data
list($foo, $bar) = $this->requireParameters('foo', 'bar');
Read a list of certain parameters:
<?php
list($foo, $bar) = $this->suggestParameters('foo', 'bar');
Special handling (with de-duplication) for reading arrays:
<?php
$stuff = $this->requireArrayParameter('stuff');
Handles nested JSON and form properties just fine:
<?php
// Corresponds with {"foo": {"bar": {"id": 9}}}
list($foo, $bar_id) = $this->requireParameters('foo', 'foo.bar.id');
Configuring the CORS middleware is as simple as adding Fuzz\ApiServer\Routing\CorsMiddleware
to the $middleware
array in app/Http/Kernel.php
.
fuzz/api-server
wraps league/fractal to serialize data output. Fuzz\ApiServer\Routing\ResourceController
uses the Fuzz\ApiServer\Utility\SerializesData
trait so any ResourceController extending it will do so as well. You can use serialization in any controller by including the trait and using it's methods.
Fuzz\ApiServer\Utility\SerializesData
exposesserialize
for single items andserializeCollection
for collections. They will both accept anIlluminate\Pagination\AbstractPaginator
or a simple array for data, a transformer as a string or\Closure
, and a format (defaults to json).- Controllers extending
Fuzz\ApiServer\Routing\ResourceController
can useFuzz\ApiServer\Routing\ResourceController@modelTransformer
to resolve a model class' transformer. A transformer is defined in a public model propertymodel_transformer
and can be of any type accepted byserialize
andserializeCollection
fuzz/api-server
provides some basic transformers out of the box:
use Fuzz\Data\Serialization\FuzzModelTransformer; // array -> json
use Fuzz\Data\Serialization\FuzzExportableModelTransformer; // array -> csv
And some serializers:
use Fuzz\Data\Serialization\FuzzDataArraySerializer; // to array (and eventually to json)
use Fuzz\Data\Serialization\FuzzCsvDataArraySerializer; // to csv