currently: v0.1
This package makes it easy to return HTTP API responses that fit the JSON API standard.
Via Composer
$ composer require giadc/giadc-json-response
Add the following to the providers
array of your config/app.php
Giadc\JsonApiResponse\ServiceProviders\LaravelDoctrineServiceProvider::class,
Basic Example:
use Giadc\JsonResponse\Responses\Response;
class YourClass {
_construct(Response $response) {
$this->response = $response;
}
public function jsonApiFunctions() {
return $this->response->success();
}
}
Available functions:
$response->getStatusCode(): int;
$response->setStatusCode(int $statusCode);
$response->withArray(array $array, array $headers = []): JsonResponse;
$response->withError(string $message): JsonResponse;
$response->createSuccessful( $entity = null, TransformerAbstract $transformer = null, string $resourceKey = '', array $headers = []): SymfonyResponse;
$response->withItem( $item, TransformerAbstract $transformer, string $resourceKey, array $headers = []): JsonResponse;
$response->withResourceItem( JsonApiResource $item, ResourceTransformer $transformer, array $headers = []): JsonResponse;
$response->withCollection( $collection, TransformerAbstract $transformer, string $resourceKey = ''): SymfonyResponse;
$response->noContent(array $headers = []): JsonResponse;
$response->withPaginatedCollection(PaginatedCollection $paginator, TransformerAbstract $transformer, string $resourceKey = ''): JsonResponse;
$response->withHttpException( HttpExceptionInterface $httpException): JsonResponse;
$response->errorForbidden(string $message = 'Forbidden'): JsonResponse;
$response->errorInternalError(string $message = 'Internal Error'): JsonResponse;
$response->errorNotFound(string $message = 'Not Found'): JsonResponse;
$response->errorUnauthorized(string $message = 'Unauthorized'): JsonResponse;
$response->errorValidation(string $message = 'Validation Error'): JsonResponse;
$response->errorsValidation(array $messages): JsonResponse;
$response->errorNotSearchable(string $message = 'Not Searchable'): JsonResponse;
The GIADC JSON Response packages uses league/fractal
for the withItem()
, withCollection()
, & withPaginatedCollection()
responses.
See Fractal's documentation for more information regarding Transformers.
ResourceTransformer adds the required transform
that pulls JsonApiResource's data from the required jsonSerialize
method. It also allows for automatic management of excludes
and fields
request parameters options.
Forces entities to have the following methods:
- getResourceKey: We can now reference this instead of hard coding this value very time.
- id: JsonAPI allows requires an id.
- jsonSerialize: Used in the new ResourceTransformer.
Use the JsonApiResource Item response to automatically pass $resourceKey
to the transformer.
$response->withResourceItem($item, $transformer, $headers)
not supported by JsonAPI
Attributes may be excluded from JsonApiResource's response. A decent use case for this would be removing the config/ui/tracking from Campaigns when it's not needed. This would allow us to remove some redundant routes, providing the FE with more flexibility.
Example:
/api/export/campaigns?excludes[campaigns]=config,ui
An empty value indicates that no fields should be returned. ... If a client requests a restricted set of fields for a given resource type, an endpoint MUST NOT include additional fields in resource objects of that type in its response.
Example:
/api/permissionGroups?fields[permissionGroups]=name&include=permissions&fields[permissions]=
{
"data": [
{
"type": "permissionGroups",
"id": "adops",
"attributes": { "name": "adops" },
"relationships": {
"permissions": {
"data": [{ "type": "permissions", "id": "campaigns.tracking" }]
}
}
},
],
"included": [
{ "type": "permissions", "id": "campaigns.tracking", "attributes": {} }
]
}