fuzz / api-server
A framework for rapid REST API development.
Installs: 19 260
Dependents: 0
Suggesters: 0
Security: 0
Stars: 6
Watchers: 23
Forks: 2
Open Issues: 2
Requires
- php: >=7.0
- fuzz/http-exception: 1.0.*
- fuzz/laravel-data: 1.0.x
- fuzz/laravel-oauth: 1.1.x-dev as 1.1
- fuzz/magic-box: 1.2.x-dev as 1.2
- laravel/framework: 5.3.*
- league/csv: ^7.2@dev
- lucadegasperi/oauth2-server-laravel: 5.2.*
- maatwebsite/excel: ^2.1
Requires (Dev)
- mockery/mockery: 0.9.*
- orchestra/testbench: 3.3.*
- phpunit/phpunit: ~5.6
- dev-master
- 1.4.x-dev
- 1.4.3.x-dev
- 1.4.2.x-dev
- 1.4.2.1-dev
- 1.4.1.x-dev
- 1.3.x-dev
- 1.2.x-dev
- 1.1.x-dev
- 1.0.2
- 1.0.1
- 1.0.0-p1
- 1.0
- dev-1.4.2-6.0
- dev-1.4.2-5.8
- dev-feature_entity_cache
- dev-refactor_throttling
- dev-feature_developer_notifications
- dev-feature_elastic_search_logger
- dev-feature_request_trace
- dev-feature_new_http_exceptions
- dev-feature_pull_in_auth_lib
- dev-feature_composite_calls
- dev-bug_1.2_bug_fixes
- dev-feature_action_logs
- dev-feature_model_transformers
- dev-feature_remove_redis_dependency
- dev-feature_throttles
- dev-feature_split_docs
- dev-replace_serialization_transformation
- dev-feature-1.1-exception-handler
- dev-feature-1.1-repository-helper-trait
- dev-feature-1.1-cleaning-legacy-debt
- dev-feature-1.1-healthcheck-controller
- dev-feature_support_laravel_53
- dev-pb-1.0
This package is not auto-updated.
Last update: 2024-11-12 12:42:59 UTC
README
A framework for rapid REST API development.
Installation
- Require the repository in your
composer.json
- Add the
ApiServerServiceProvider
to your application and publish its configartisan vendor:publish --provider="Fuzz\ApiServer\Providers\ApiServerServiceProvider"
. - 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
{
// ...
}
Usage
Basic usage
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');
ResourceControllers
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');
Returning that sweet, sweet, data
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');
CORS Middleware
Configuring the CORS middleware is as simple as adding Fuzz\ApiServer\Routing\CorsMiddleware
to the $middleware
array in app/Http/Kernel.php
.