Custom Entity Api Endpoint Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Run:

   composer require diglin/custom-entity-api-endpoint-bundle:1.*
   

   Ensure Composer updates composer.json and installs dependencies.

2. Enable the Bundle Add to config/bundles.php (Laravel 5.4+) or AppKernel.php (Symfony/Laravel <5.4):

   Diglin\Bundle\ApiRefDataBundle\DiglinApiRefDataBundle::class => ['all' => true],
   

3. Route Configuration Add to routes/api.php (Laravel) or routing.yml (Symfony):

   diglin_api_ref_data:
       resource: "@DiglinApiRefDataBundle/Resources/config/routing.yml"
       prefix: /api
   

   For Laravel, ensure the prefix aligns with your API routes (e.g., /api/rest/v1).

4. First Use Case Fetch reference data for a custom entity (e.g., color):

   GET /api/rest/v1/reference-data/color
   

   Fetch a specific item (e.g., code=RED):

   GET /api/rest/v1/reference-data/color/RED
   

Implementation Patterns

Workflows

1. Fetching Reference Data Lists Use the api_ref_data_reference_data_list endpoint to retrieve all items for a custom entity:

   $response = Http::get('/api/rest/v1/reference-data/color');
   $data = $response->json();
   

   • Pagination: If Akeneo’s CustomEntityBundle supports pagination, leverage query params (?page=1&limit=20).
   • Filtering: Extend the bundle (see Gotchas) to add filters (e.g., ?locale=en_US).

2. Fetching Single Items Use api_ref_data_reference_data_get for specific items:

   $response = Http::get('/api/rest/v1/reference-data/color/RED');
   $item = $response->json();
   

3. Integration with Akeneo

   • Dependency: Ensure akeneo-labs/custom-entity-bundle is installed and configured.
   • Entity Mapping: Verify custom entities (e.g., color, size) are defined in Akeneo’s PIM.

4. Laravel-Specific Patterns

   • Service Layer: Create a service to abstract API calls:

     class ReferenceDataService {
         public function getList(string $referenceName): array {
             return Http::get("/api/rest/v1/reference-data/{$referenceName}")->json();
         }
     }
     

   • DTOs: Map responses to Laravel DTOs for type safety:

     class ReferenceDataDTO {
         public string $code;
         public string $label;
         // ...
     }
     

5. Testing

   • Unit Tests: Mock Http client responses for isolated testing.
   • Feature Tests: Use Laravel’s actingAs() to test authenticated requests if Akeneo requires API keys.

Gotchas and Tips

Pitfalls

1. Routing Conflicts

   • Issue: The bundle’s /api/rest/v1 prefix may clash with existing Laravel API routes.
   • Fix: Override the route prefix in config/packages/diglin_api_ref_data.yaml (if supported) or extend the bundle’s routing:

     # config/routes/api.php
     diglin_api_ref_data:
         resource: "@DiglinApiRefDataBundle/Resources/config/routing.yml"
         prefix: /akeneo/api/v1  # Custom prefix
     

2. Authentication

   • Issue: Akeneo’s API may require authentication (e.g., API keys or OAuth).
   • Fix: Add middleware to the route:

     Route::middleware(['auth:api'])->group(function () {
         // Existing routes...
     });
     

     Or configure HTTP client defaults:

     Http::macro('akeneo', fn ($url) =>
         Http::withHeaders(['Authorization' => 'Bearer ' . config('akeneo.api_token')])->get($url)
     );
     

3. Custom Entity Not Found

   • Issue: 404 when querying non-existent custom entities (e.g., /api/rest/v1/reference-data/invalid).
   • Fix: Validate entity names against Akeneo’s configured custom entities:

     public function isValidReferenceEntity(string $name): bool {
         return in_array($name, config('akeneo.custom_entities'));
     }
     

4. Caching

   • Issue: Frequent API calls may hit Akeneo’s rate limits.
   • Fix: Cache responses in Laravel’s cache layer:

     $cacheKey = "ref_data_{$referenceName}";
     return Cache::remember($cacheKey, now()->addHours(1), function () use ($referenceName) {
         return Http::get("/api/rest/v1/reference-data/{$referenceName}")->json();
     });
     

Tips

1. Extending Functionality

   • Add Query Parameters: Override the bundle’s controller to support filtering:

     // src/Controller/ReferenceDataController.php
     public function listAction(Request $request, $referenceName) {
         $query = $request->query->all();
         // Add custom logic (e.g., filter by locale)
         return parent::listAction($request, $referenceName);
     }
     

   • Custom Endpoints: Create additional routes for complex queries (e.g., bulk updates).

2. Error Handling

   • Akeneo-Specific Errors: Handle Akeneo’s error formats (e.g., {"error": "Not found"}):

     try {
         $response = Http::get('/api/rest/v1/reference-data/color/INVALID');
         $response->throw();
     } catch (HttpException $e) {
         if ($e->response->json()['error'] === 'Not found') {
             // Custom logic
         }
     }
     

3. Performance

   • Batch Requests: For large datasets, use Akeneo’s batch endpoints if available.
   • Lazy Loading: Implement lazy loading for nested reference data.

4. Documentation

   • Swagger/OpenAPI: Annotate routes for API documentation:

     /**
      * @OA\Get(
      *     path="/api/rest/v1/reference-data/{referenceName}",
      *     summary="Get reference data list",
      *     @OA\Parameter(
      *         name="referenceName",
      *         in="path",
      *         required=true,
      *         @OA\Schema(type="string")
      *     )
      * )
      */
     

5. Bundle Updates

   • Monitor Changes: Star the repo and watch for updates to akeneo-labs/custom-entity-bundle or this bundle.
   • Forking: If critical features are missing, fork and extend the bundle.