Responses

• Apiato Response
• Default Apiato Responses Payload
• Change the default Response payload
• Resource Keys
• Error Responses formats
• Building a Responses from the Controller

Apiato Response

In Apiato you can define your own response payload or use one of the supported serializers.

Currently, the supported serializers are (ArraySerializer, DataArraySerializer and JsonApiSerializer). As provided by Fractal.

By default, Apiato uses DataArraySerializer. Below is an example of the response payload.

Default Apiato Responses Payload:

DataArraySerializer response payload looks like this:

{
  "data": [
    {
      "id": 100,
      ...
      "relation 1": {
        "data": [ // multiple data
          {
            "id": 11,
              ...
          }
        ]
      },
      "relation 2": {
        "data": { // single data
          "id": 22,
          ...
          }
        }
      }
    },
    ...
  ],
  "meta": {
    "include": [ // what can be included
      "xxx",
      "yyy"
    ],
    "custom": [],
    "pagination": {
      "total": 999,
      "count": 999,
      "per_page": 999,
      "current_page": 999,
      "total_pages": 999,
      "links": {
        "next": "http://api.apiato.test/v1/accounts?page=999"
      }
    }
  }
}

Paginated response:

When data is paginated the response payload will contain a meta description about the pagination.

{
  "meta": {
    "include": [
      "xxx",
      "yyy"
    ],
    "custom": [],
    "pagination": { // pagination meta
      "total": 999,
      "count": 999,
      "per_page": 999,
      "current_page": 999,
      "total_pages": 999,
      "links": {
        "next": "http://api.apiato.test/v1/accounts?page=999"
      }
    }
  }
}

Includes:

Informs the User about what relationships can be included in the response. Example: ?include=tags,user

For more details read the Relationships section in the Query Parameters page.

Change the default Response payload:

The default response format (specification) is the DataArray Fractal Serializer (League\Fractal\Serializer\DataArraySerializer).

To change the default Fractal Serializer open the app/Ship/Configs/fractal.php file and change the

'default_serializer' => League\Fractal\Serializer\DataArraySerializer::class,

The Supported Serializers are

• ArraySerializer
• DataArraySerializer
• JsonApiSerializer

More details can be found at Fractal and Laravel Fractal Wrapper.

In case of returning JSON Data (JsonApiSerializer), you may wish to check some JSON response standards:

• JSEND (very basic)
• JSON API (very popular and well documented)
• HAL (useful in case of hypermedia)

Resource Keys

The transformer allows appending a ResourceKey to the transformed resource. You can set the ResourceKey in your response payload in 2 ways:

1. Manually set it via the respective parameter in the $this->transform() call. Note that this will only set the top level resource key and does not affect the resource keys from included resources!
2. Specify it on the respective Model. By overriding $resourceKey, (protected $resourceKey = 'FooBar';). If no $resourceKey is defined at the Model, the ShortClassName is used as key. For example, the ShortClassName of the App\Containers\AppSection\User\Models\User::class is User.

Error Responses formats

Visit each feature, e.g. the Authentication and there you will see how an unauthenticated response looks like, same for Authorization, Validation and so on.

Building a Responses from the Controller:

Checkout the Controller response builder helper functions.