README
!!! Project abandoned. See cloudcreativity/laravel-json-api for a great alternative.
JSON API helpers for Laravel 5
Make it a breeze to create a jsonapi.org compliant API with Laravel 5.
This library strives to be up to date with the latest JSON API updates—as the spec is still a work in progress. If you notice that something is missing, please contribute!
Installation
-
Add echo-it/laravel-jsonapi to your composer.json dependency list (version 2.0.0 at the minimum for laravel 5 support)
-
Run composer update.
Requirements
Using laravel-jsonapi
This library is made with the concept of exposing models in mind, as found in the RESTful API approach.
In few steps you can expose your models:
-
Create a route to direct the requests
In this example, we use a generic route for all models and HTTP methods:
Route::any('{model}/{id?}', 'ApiController@handleRequest');
-
Create your controller to handle the request
Your controller is responsible to handling input, instantiating a handler class and returning the response.
fulfillRequest();
} catch (ApiException $e) {
return $e->response();
}
return $res->toJsonResponse();
}
// If a handler class does not exist for requested model, it is not considered to be exposed in the API
return new ApiErrorResponse(404, 404, 'Entity not found');
}
}
```
3. **Create a handler for your model**
A handler is responsible for exposing a single model.
In this example we have create a handler which supports the following requests:
* GET /users (ie. handleGet function)
* GET /users/[id] (ie. handleGet function)
* PUT /users/[id] (ie. handlePut function)
Requests are automatically routed to appropriate handle functions.
```php
handleGetDefault($request, new User);
}
/**
* Handles PUT requests.
* @param EchoIt\JsonApi\Request $request
* @return EchoIt\JsonApi\Model|Illuminate\Support\Collection|EchoIt\JsonApi\Response
*/
public function handlePut(ApiRequest $request)
{
//you can use the default PUT functionality, or override with your own
return $this->handlePutDefault($request, new User);
}
}
```
> **Note:** Extend your models from `EchoIt\JsonApi\Model` rather than `Eloquent` to get the proper response for linked resources.
Current features
-----
According to [jsonapi.org](
http://jsonapi.org):
* [Resource Representations](
http://jsonapi.org/format/#document-structure-resource-representations) as resource objects
* [Resource Relationships](
http://jsonapi.org/format/#document-structure-resource-relationships)
* Only through [Inclusion of Linked Resources](
http://jsonapi.org/format/#fetching-includes)
* [Compound Documents](
http://jsonapi.org/format/#document-structure-compound-documents)
* [Sorting](
http://jsonapi.org/format/#fetching-sorting)
* [Filtering](
http://jsonapi.org/format/#fetching-filtering)
* [Pagination] (
http://jsonapi.org/format/#fetching-pagination)
The features in the Handler class are each in their own function (eg. handlePaginationRequest, handleSortRequest, etc.), so you can easily override them with your own behaviour if desired.
Wishlist
-----
* Nested requests to fetch relations, e.g. /users/[id]/friends
* [Resource URLs](
http://jsonapi.org/format/#document-structure-resource-urls)
* Requests for multiple [individual resources](
http://jsonapi.org/format/#urls-individual-resources), e.g. `/users/1,2,3`
* [Sparse Fieldsets](
http://jsonapi.org/format/#fetching-sparse-fieldsets)
* Some kind of caching mechanism
