Download the PHP package vinelab/api-manager without Composer

API Manager

A simple API response formatter and handler for Laravel. Beautify and unify your responses with the least effort possible.

Install

Via composer:

Add the service provider to the providers array in app/config/app.php:

Configuration

Publish the package config file:

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)

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.

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

Mapper Usage

Mapper Examples

Here are some examples implementing a mapper called PostsMapper

Array Mapping

Model Mapping

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 calling paginate()
• 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.

When $total and $page are null they won't be included in the response.

Pagination

Response

Model

Response

Collection

Response

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.

$exception can be either a string (the exception message) or an inheritance of either Exception or RuntimeException

Erorr with Exception

• 401 will be the HTTP response code
• 1001 is the error code (specific to the API)

Response

Error with Message

Response

Contributing

Please see CONTRIBUTING for details.

License

The package is open-sourced software licensed under the MIT license.