mediagone/symfony-easy-api

Quickly build JSON API using plain Symfony controllers.

1.0.0 2024-09-25 13:20 UTC

Requires

• php: ^7.4|^8.0
• ext-json: *
• symfony/http-foundation: ^4.0|^5.0|^6.0|^7.0

Requires (Dev)

• phpunit/phpunit: ^9.0

MIT

• Bruce Suire

• symfony
• json
• api

README

This package provides helper classes to build a Json API very easily from plain Symfony controllers.
Supported features :

• Single and Collection results
• Pagination for Collection results
• Out of the box support for most useful status codes (200, 201, 202, 204, 400, 401, 403, 404, 405, 409, 410, 415, 422, 429, 500 and 501).

Installation

This package requires PHP 7.4+.

Add it as Composer dependency:

$ composer require mediagone/symfony-easy-api

Introduction

This package provides several classes to handle API requests and return structured JSON responses:

• ApiPayload200Success
• ApiPayload201Created
• ApiPayload202Accepted
• ApiPayload204NoContent
• ApiPayloadError400BadRequest
• ApiPayloadError401Unauthorized
• ApiPayloadError403Forbidden
• ApiPayloadError404NotFound
• ApiPayloadError405MethodNotAllowed
• ApiPayloadError409Conflict
• ApiPayloadError410Gone
• ApiPayloadError415UnsupportedMediaType
• ApiPayloadError422UnprocessableEntity
• ApiPayloadError429TooManyRequests
• ApiPayloadError500ServerError
• ApiPayloadError501NotImplemented

Examples

The easiest way to build an API controller is to use the EasyApi class and wrap the controller code in an anonymous function, to benefit from automatic error handling.

1. Entity instance API endpoint

The EasyApi->response method accepts any callable argument that returns an ApiPayload instance.

use App\Thing\ThingRepository;
use Mediagone\Symfony\EasyApi\EasyApi;
use Mediagone\Symfony\EasyApi\Payloads\ApiPayload200Success;
use Mediagone\Symfony\EasyApi\Payloads\ApiPayloadError404NotFound;
use Symfony\Component\HttpFoundation\Response;

/**
 * @Route("/api/things/{thingId}", name="api_things", methods={"GET"})
 */
final class ApiEndpointController
{
    
    public function __invoke(int $thingId, EasyApi $easyApi, ThingRepository $thingRepository) : Response
    {
        return $easyApi->response(
            function() use ($thingId, $thingRepository) {
                // Any uncatched exception would be automatically converted into an ApiPayloadError500ServerError response's payload.
                if ($thingId < 1) {
                    throw new LogicException("Invalid `\$thingId` value ($thingId)");
                }
                
                $thing = $thingRepository->find($thingId);
                if ($thing === null) {
                    // Explicit "not found" error response's payload
                    return ApiPayloadError404NotFound::create('Thing not found (id: '.$thingId.')');
                }
                
                
                return ApiPayload200Success::createWithSingleResult($thing);
            }
        );
    }
    
}

In case of success, the previous controller will return the following JSON object:

{
    "success": true,
    "status": "ok",
    "statusCode": 200,
    "payload": {
        "result": {
            "id": 1,
            "name": "First thing"
        }
    }
}

Or a "not found" response:

{
    "success": false,
    "status": "not_found",
    "statusCode": 404,
    "error": "not_found",
    "errorDescription": "Thing not found (id: 1)",
    "errorCode": 0
}

Or a "server error" response:

{
    "success": false,
    "status": "server_error",
    "statusCode": 500,
    "error": "server_error",
    "errorDescription": "Unexpected server error: Invalid `$thingId` value (-1)",
    "errorCode": 0
}

Note: errorCode is the internal error's code of the PHP exception (0 by default). You can generally define it by passing an additional integer argument to the constructor, eg. throw new LogicException("Invalid $thingId value ($thingId)", 1234);.

2. Entity collection API endpoint

You can also return multiple results by using the ApiPayload200Success::createWithArrayResult factory method:

/**
 * @Route("/api/things", name="api_things", methods={"GET"})
 */
final class ApiEndpointController
{
    
    public function __invoke(EasyApi $easyApi, ThingRepository $thingRepository) : Response
    {
        return $easyApi->response(
            function() use ($thingRepository)
            {
                $things = $thingRepository->findAll();
                return ApiPayload200Success::createWithArrayResult($things);
            }
        );
    }
    
}

It will result in a slightly different JSON object:

{
    "success": true,
    "status": "ok",
    "statusCode": 200,
    "payload": {
        "results": [
            { "id": 1, "name": "First thing" },
            { "id": 2, "name": "Second thing" },
            { "id": 3, "name": "Third thing" }
        ],
        "resultsCount": 3,
        "resultsCountTotal": 3,
        "page": 1,
        "pageCount": 1
    }
}

3. Collection pagination

When dealing with a lot of database entries, you may want to paginate results to retrieve them chunk by chunk.
The package provides the ApiPagination class to help with that feature.

It requires two database queries: one to count the total number of results, and another to fetch the requested results:

use Mediagone\Symfony\EasyApi\EasyApi;
use Mediagone\Symfony\EasyApi\Payloads\ApiPayload;
use Mediagone\Symfony\EasyApi\Payloads\ApiPayload200Success;
use Mediagone\Symfony\EasyApi\Request\ApiPagination;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

#[Route('/api/things/{requestedPage}', name:'api_things_list')]
public function __invoke(int $requestedPage = 1, ThingRepository $thingRepository): Response
{
    return $easyApi->response(static function () use ($requestedPage, $thingRepository) : ApiPayload {
        // Count the total number of Things in the db
        $thingsCount = $thingRepository->countAll();
        
        // Create a pagination object
        $pagination = ApiPagination::create($requestedPage, 5, $thingsCount);
        
        // Query the page's results
        $things = $thingRepository->findAllPaginated($pagination);
        
        return ApiPayload200Success::createWithArrayResult($things, $pagination);
    }
}

Assuming that you have 93 rows in your database and you are requesting the 2nd page of 5 results, you'll receive the following JSON response:

{
    "success": true,
    "status": "ok",
    "statusCode": 200,
    "payload": {
        "results": [
            { "id": 6, "name": "6th thing" },
            { "id": 7, "name": "7th thing" },
            { "id": 8, "name": "8th thing" },
            { "id": 9, "name": "9th thing" },
            { "id": 10, "name": "10th thing" }
        ],
        "resultsCount": 5,
        "resultsCountTotal": 93,
        "page": 2,
        "pageCount": 19
    }
}

License

Symfony EasyAPI is licensed under MIT license. See LICENSE file.