api-manager maintained by vinelab
- php >=5.4.0
- illuminate/support 5.*
- illuminate/config 5.*
- illuminate/http 5.*
- illuminate/routing 5.*
- php >=5.4.0
- illuminate/support 5.*
- illuminate/config 5.*
- illuminate/http 5.*
- illuminate/routing 5.*
- php >=5.4.0
- illuminate/support 5.*
- illuminate/config 5.*
- illuminate/http 5.*
- illuminate/routing 5.*
- php >=5.4.0
- illuminate/support 5.*
- illuminate/config 5.*
- illuminate/http 5.*
- illuminate/routing 5.*
- php >=5.4.0
- illuminate/support 4.2.*
- illuminate/config 4.*
- illuminate/http 4.2.*
- php >=5.4.0
- illuminate/support 4.2.*
- illuminate/config 4.*
- illuminate/http 4.2.*
- php >=5.4.0
- illuminate/support 5.*
- illuminate/config 5.*
- illuminate/http 5.*
- illuminate/routing 5.*
- php >=5.4.0
- illuminate/support 5.*
- illuminate/config 5.*
- illuminate/http 5.*
- illuminate/routing 5.*
- php >=5.4.0
- illuminate/support 5.*
- illuminate/config 5.*
- illuminate/http 5.*
- illuminate/routing 5.*
- php >=5.4.0
- illuminate/support 5.*
- illuminate/config 5.*
- illuminate/http 5.*
- illuminate/routing 5.*
- php >=5.4.0
- illuminate/support 5.*
- illuminate/config 5.*
- illuminate/http 5.*
- illuminate/routing 5.*
- php >=5.4.0
- illuminate/support 5.*
- illuminate/config 5.*
- illuminate/http 5.*
- illuminate/routing 5.*
- php >=5.4.0
- illuminate/support 5.*
- illuminate/config 5.*
- illuminate/http 5.*
- illuminate/routing 5.*
- php >=5.4.0
- illuminate/support 4.2.*
- illuminate/config 4.*
- illuminate/http 4.2.*
- php >=5.4.0
- illuminate/support 4.2.*
- illuminate/config 4.*
- illuminate/http 4.2.*
- php >=5.4.0
- illuminate/support 4.2.*
- illuminate/config 4.*
- illuminate/http 4.2.*
- php >=5.4.0
- illuminate/support 4.2.*
- illuminate/config 4.*
- illuminate/http 4.2.*
- php >=5.4.0
- illuminate/support 4.2.*
- illuminate/config 4.*
- illuminate/http 4.2.*
- php >=5.4.0
- illuminate/support 4.2.*
- illuminate/config 4.*
- illuminate/http 4.2.*
- php >=5.4.0
- illuminate/support 4.2.*
- illuminate/config 4.*
- illuminate/http 4.2.*
- php >=5.4.0
- illuminate/support 4.2.*
- illuminate/config 4.*
- illuminate/http 4.2.*
- php >=5.4.0
- illuminate/support 4.2.*
- illuminate/config 4.*
- illuminate/http 4.2.*
- php >=5.4.0
- illuminate/support 4.2.*
- illuminate/config 4.*
- illuminate/http 4.2.*
comments powered by Disqus
A simple API response formatter and handler for Laravel. Beautify and unify your responses with the least effort possible.
{
"require": {
"vinelab/api-manager": "*"
}
}Add the service provider to the providers array in app/config/app.php:
'providers' => array(
...
'Vinelab\Api\ApiServiceProvider',
),Publish the package config file:
php artisan config:publish vinelab/api-managerIt is now located at app/config/packages/vinelab/api-manager/api.php
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.
The limit is where you set the maximum number of data to be returned with any endpoint request.
'limit' => '50',This package expects to have Mapper class for each model you want to return via the API.
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:
class PostMapper {
public function map(Post $post)
{
return [
'id' => (int) $post->id,
'title' => $post->title,
'body' => $post->body,
'published' => (boolean) $post->published
];
}
}$post = Post::create([
'title' => 'Some Title',
'body' => 'Things and spaces',
'published' => true
]);
$mapper = new PostMapper;
return $mapper->map($post);Here are some examples implementing a mapper called PostsMapper
<?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']
];
}
}<?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
];
}
}From your controller you can use the Api Facade Class that contains these 2 important functions respond and error.
The Api::respond($mapper, $data) accepts the following data types for $data
- array
- Eloquent Model
-
Illuminate\Pagination\Paginatorwhich is the result of callingpaginate() -
Illuminate\Database\Eloquent\Collectionof 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
$totaland$pagearenullthey won't be included in the response.
return Api::respond('PostsMapper', Post::paginate(3));{
"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
}
]
}return Api::respond('PostsMapper',Post::first());{
"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
}
}$data = Post::where('active', '0')->get();
$total = $data->count();
$page = 2;
return Api::respond('PostsMapper', $data, $total, $page);{
"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
}
]
}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).
For an error response use the Api::error function.
Api::error($exception, $code = 0, $status = 500, $headers = [], $options = 0);
$exceptioncan be either a string (the exception message) or an inheritance of eitherExceptionorRuntimeException
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)
{
"status": 401,
"error": {
"code": 1001,
"message": "You deserve it, this is your fault."
}
}return Api::error('Something is wrong!!!', 1000, 505);{
"status": 505,
"error": {
"code": 1000,
"message": "Something is wrong!!!"
}
}Please see CONTRIBUTING for details.
The package is open-sourced software licensed under the MIT license.