Response

The Apiato\Support\Facades\Response facade is a powerful tool to create API responses. It extends Spatie\Fractal\Fractal and enhances its functionality by adding methods for resource key management, meta-information, and standardized HTTP responses.

Further Reading

For more detailed information, please refer to Fractal and Laravel Fractal Wrapper documentations.

Here are some examples of how to use the Response facade:

Response::create($user)->transformWith(UserTransformer::class)->json(null, 200);
Response::create()->transformWith(UserTransformer::class)->ok($user);
Response::create($user, UserTransformer::class)->created();
Response::create($user, UserTransformer::class)->parseIncludes(['permissions'])->toArray();
Response::ok();

Filtering

When using the Response facade, you can filter the response data using the fields query parameter. This allows you to specify which fields you want to include in the response.

The fields query parameter is structured as follows:

fields[ResourceKey]=field1,field2

Where ResourceKey is the key of the resource you want to filter, and field1, field2 are the fields you want to include in the response.

Let's say we have an endpoint that returns a user resource with the following structure:

{
  "data": {
    "type": "User",
    "id": "0one37vjk49rp5ym",
    "email": "[email protected]",
    "products": {
      "data": [
        {
          "type": "Product",
          "id": "bmo7y84xpgeza06k",
          "status": "pending"
        },
        {
          "type": "Product",
          "id": "o0wzxbg0q4k7jp9d",
          "status": "fulfilled"
        }
      ]
    },
    "store": {
      "data": {
        "type": "Store",
        "id": "r6lbekg8rv5ozyad"
      }
    },
    "recipients": {
      "data": [
        {
          "type": "Recipient",
          "id": "r6lbekg8rv5ozyad",
          "contact": {
            "data": {
              "type": "Contact",
              "address": "123 Main St",
              "city": "Gotham"
            }
          }
        }
      ]
    }
  }
}

If we specify the following query parameters in our request:

api.apiato.test/v1/users?fields[User]=type,email,products,recipients&fields[Product]=status&fields[Recipient]=id,contact&fields[Contact]=address,city

The response will be filtered to include only the specified fields:

{
  "data": {
    "type": "User",
    "email": "[email protected]",
    "products": {
      "data": [
        {
          "status": "pending"
        },
        {
          "status": "fulfilled"
        }
      ]
    },
    "recipients": {
      "data": [
        {
          "id": "r6lbekg8rv5ozyad",
          "contact": {
            "address": "123 Main St",
            "city": "Gotham"
          }
        }
      ]
    }
  }
}

Configuration

You can configure the filter settings in the config/fractal.php file.

'auto_fieldsets' => [
    'enabled' => true,
    'request_key' => 'fields',
],

Response Macros

If you would like to define a custom response that you can re-use in a variety of your routes and controllers, you may use the macro method on the Response facade. Typically, you should call this method from the boot method of one of your application's service providers, such as the App\Ship\Providers\ShipServiceProvider service provider:

use Apiato\Support\Facades\Response;
use App\Ship\Parents\Providers\ServiceProvider as ParentServiceProvider;

class ShipServiceProvider extends ParentServiceProvider
{
    public function boot(): void
    {
        Response::macro('caps', function (string $value) {
            return Response::make(strtoupper($value));
        });
    }
}