vinelab / api-manager
Laravel API Manager Package - beatify and unify your responses with the least effort possible.
Installs: 2 058
Dependents: 1
Suggesters: 0
Security: 0
Stars: 39
Watchers: 11
Forks: 7
Open Issues: 2
Requires
- php: >=5.4.0
- illuminate/config: 5.*
- illuminate/http: 5.*
- illuminate/routing: 5.*
- illuminate/support: 5.*
Requires (Dev)
- illuminate/pagination: 5.*
- mockery/mockery: 0.9.0
- phpunit/phpunit: 4.2.*
README
API Manager
A simple API response formatter and handler for Laravel. Beautify and unify your responses with the least effort possible.
Install
Via composer:
{ "require": { "vinelab/api-manager": "*" } }
Add the service provider to the providers
array in app/config/app.php
:
'providers' => array( ... 'Vinelab\Api\ApiServiceProvider', ),
Configuration
Publish the package config file:
php artisan config:publish vinelab/api-manager
It is now located at app/config/packages/vinelab/api-manager/api.php
Namespace
The mappers is where you specify your mappers base namespace (See Mappers Terminology for more on mappers)
'mappers' => 'Lib\Api\Mappers\\',
You may use Api::setMapperNamespace('\New\Namespace\\');
to override the configured namespace.
Limit
The limit is where you set the maximum number of data to be returned with any endpoint request.
'limit' => '50',
Setup
This package expects to have Mapper class for each model you want to return via the API.
Mappers
A Mapper is a class that transforms any supported data type (i.e. Model) into a suitable array for an API response with the attributes of your choice.
By default the Api Manager will call the method map
on the given mapper
unless indicated differently by passing [$mapper, $method]
where $mapper
is either the actual instance of the class name as a string.
Example:
Mapper Class
class PostMapper { public function map(Post $post) { return [ 'id' => (int) $post->id, 'title' => $post->title, 'body' => $post->body, 'published' => (boolean) $post->published ]; } }
Mapper Usage
$post = Post::create([ 'title' => 'Some Title', 'body' => 'Things and spaces', 'published' => true ]); $mapper = new PostMapper; return $mapper->map($post);
Mapper Examples
Here are some examples implementing a mapper called PostsMapper
Array Mapping
<?php namespace Lib\Api\Mappers; class PostsMapper implements PostsInterface { public function map(array $data) { return [ 'id' => (int) $data['id'], 'title' => $data['title'], 'text' => $data['text'], 'active' => (boolean) $data['active'] ]; } }
Model Mapping
<?php namespace Lib\Api\Mappers; class PostsMapper implements PostsInterface { public function map(Post $post) { return [ 'id' => (int) $post->id, 'title' => $post->title, 'text' => $post->text, 'active' => (boolean) $post->active ]; } }
Usage and Responses
From your controller you can use the Api
Facade Class that contains these 2 important functions respond
and error
.
Data Types
The Api::respond($mapper, $data)
accepts the following data types for $data
- array
- Eloquent Model
Illuminate\Pagination\Paginator
which is the result of callingpaginate()
Illuminate\Database\Eloquent\Collection
of model objects which is when fetching multiple records, i.e.get()
The responses returned by this package follows the conventions of a json api and the standards recommended by the book Build APIs You Won't Hate.
Api::respond($mapper, $data, $total = null, $page = null, $status = 200, $headers = [], $options = 0)
When
$total
and$page
arenull
they won't be included in the response.
Pagination
return Api::respond('PostsMapper', Post::paginate(3));
Response
{ "status": 200, "total": 3, "page": 1, "data": [ { "id": 1, "title": "Ex veniam et voluptatibus est. Enim provident tempore reiciendis qui qui. Aut soluta ipsum voluptatem repellat quod explicabo.", "text": "Voluptatem dolorum eum sequi maiores quo facere dolor. Molestiae corrupti rem quo sed. Quibusdam ut voluptate consequatur.", "active": false }, { "id": 2, "title": "Qui aperiam aut voluptatem repellat est. Minima dolor qui rem sint cum debitis. Ab quia neque quasi laboriosam.", "text": "Ea et quae facere fugiat non est eveniet. Veniam quas doloremque repellat esse nihil qui qui voluptas. Laboriosam voluptate rerum et perferendis adipisci deleniti. Quae quam nisi facilis quia dolore.", "active": false }, { "id": 3, "title": "Aspernatur voluptas id ratione rerum et quis. Repellendus dolorem nihil sint maxime. Dolorum ex dolorum sit est recusandae.", "text": "Sit voluptatem voluptatem corporis. Excepturi eligendi quia maiores nesciunt quia. Ipsum voluptatem autem aspernatur pariatur.", "active": false } ] }
Model
return Api::respond('PostsMapper',Post::first());
Response
{ "status": 200, "data": { "id": 1, "title": "Ex veniam et voluptatibus est. Enim provident tempore reiciendis qui qui. Aut soluta ipsum voluptatem repellat quod explicabo.", "text": "Voluptatem dolorum eum sequi maiores quo facere dolor. Molestiae corrupti rem quo sed. Quibusdam ut voluptate consequatur.", "active": false } }
Collection
$data = Post::where('active', '0')->get(); $total = $data->count(); $page = 2; return Api::respond('PostsMapper', $data, $total, $page);
Response
{ "status": 200, "total": 15, "page": 2, "data": [ { "id": 1, "title": "Ex veniam et voluptatibus est. Enim provident tempore reiciendis qui qui. Aut soluta ipsum voluptatem repellat quod explicabo.", "text": "Voluptatem dolorum eum sequi maiores quo facere dolor. Molestiae corrupti rem quo sed. Quibusdam ut voluptate consequatur.", "active": false }, { "id": 2, "title": "Qui aperiam aut voluptatem repellat est. Minima dolor qui rem sint cum debitis. Ab quia neque quasi laboriosam.", "text": "Ea et quae facere fugiat non est eveniet. Veniam quas doloremque repellat esse nihil qui qui voluptas. Laboriosam voluptate rerum et perferendis adipisci deleniti. Quae quam nisi facilis quia dolore.", "active": false }, { "id": 14, "title": "Illo quia minima ut est praesentium assumenda explicabo. Facilis ipsam minus et rerum perspiciatis illo. Voluptas distinctio et possimus non iste doloremque dolor.", "text": "Corporis quos dignissimos voluptas tempora quo perspiciatis nesciunt. Corrupti soluta ad eos tenetur debitis. Aut quia atque molestiae delectus et.", "active": false }, { "id": 15, "title": "Labore sequi molestiae quisquam nostrum. Esse nisi in non aut praesentium occaecati. Suscipit exercitationem necessitatibus eos quis nulla. Necessitatibus nisi nostrum non ducimus aspernatur quod.", "text": "Officiis odio cumque est expedita. Qui atque veniam eos saepe. Architecto corrupti quis quia modi voluptatem.", "active": false } ] }
Request Data Limit
Part of the api is the limit you would like to enforce on the clients that request your API. To make it easier
and more centralized you may use the Api
to set and get the limit value, aso configure a ceiling (max) value
which cannot be exceeded by the requesting client.
The value is read from the limit
query parameter. i.e. http://api.com/?limit=20
To get the requested limit use Api::limit()
which will automatically verify that the requested limit does not exceed your maximum specified limit value.
To override the limit value (configured limit) within your code you can use Api::setLimit(100)
.
Error Handling
For an error response use the Api::error
function.
Api::error($exception, $code = 0, $status = 500, $headers = [], $options = 0);
$exception
can be either a string (the exception message) or an inheritance of eitherException
orRuntimeException
Erorr with Exception
try { throw WhateverCustomException('You deserve it, this is your fault.', 1001); } catch (WhateverCustomException $e) { return Api::error($e, $e->getCode(), 401); }
- 401 will be the HTTP response code
- 1001 is the error code (specific to the API)
Response
{ "status": 401, "error": { "code": 1001, "message": "You deserve it, this is your fault." } }
Error with Message
return Api::error('Something is wrong!!!', 1000, 505);
Response
{ "status": 505, "error": { "code": 1000, "message": "Something is wrong!!!" } }
Contributing
Please see CONTRIBUTING for details.
License
The package is open-sourced software licensed under the MIT license.