Ezplatform Rest Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ezsystems/ezplatform-rest
   

   Ensure your config/bundles.php includes Ibexa\Rest\IbexaRestBundle.

2. Enable REST API: Add the bundle to your config/packages/ibexa_rest.yaml (auto-generated if missing):

   ibexa_rest:
       enabled: true
       security:
           firewalls:
               - main
   

3. First Use Case: Test the API by accessing the content endpoint:

   curl -X GET http://your-site.com/api/ezplatform/v2/content -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
   

   (Obtain tokens via /api/ezplatform/v2/jwt/login with valid credentials.)

Key Documentation

• Official Ibexa REST API Docs
• REST API Reference

Implementation Patterns

Core Workflows

1. Content Management:

   • Create/Update Content:

     curl -X POST http://your-site.com/api/ezplatform/v2/content -H "Content-Type: application/json" -d '{"name": "Test", "contentInfo": {"mainLocationId": 2}}'
     

   • Fetch Content with Fields:

     curl -X GET http://your-site.com/api/ezplatform/v2/content/123?fields=title,body
     

2. Authentication:

   • JWT Login:

     curl -X POST http://your-site.com/api/ezplatform/v2/jwt/login -d '{"username": "admin", "password": "password"}'
     

   • Token-Based Auth: Include Authorization: Bearer <token> in headers.

3. Search:

   • Query Content:

     curl -X GET "http://your-site.com/api/ezplatform/v2/search?query=test&limit=10"
     

4. Media Handling:

   • Upload Assets:

     curl -X POST http://your-site.com/api/ezplatform/v2/content/123/fields/image -H "Content-Type: image/jpeg" --data-binary "@image.jpg"
     

Integration Tips

• Custom Endpoints: Extend the API by creating custom controllers and routing them under /api/ezplatform/v2/. Example:

  # config/routes.yaml
  api_custom:
      path: /api/ezplatform/v2/custom
      controller: App\Controller\CustomApiController::index
  

• Field Processors: Override default field serialization via ibexa.rest.field_type.processor services.

  # config/services.yaml
  services:
      App\Rest\FieldType\CustomFieldProcessor:
          tags:
              - { name: ibexa.rest.field_type.processor, fieldType: 'ezrichtext' }
  

Gotchas and Tips

Common Pitfalls

1. Authentication Issues:

   • Ensure ezpublish_rest_session is configured in your firewall (see IBX-6239).
   • Fix: Add to config/packages/security.yaml:

     firewalls:
         main:
             pattern: ^/api/ezplatform
             stateless: true
             ezpublish_rest_session:
                 provider: ezpublish_rest_auth_provider
     

2. Field Serialization:

   • Custom field types may require manual processor registration. Use ibexa.rest.field_type.processor tag.
   • Debug: Check var/log/dev.log for FieldTypeProcessor errors.

3. Deprecated Services:

   • Avoid ezpublish_rest.field_type_processor (deprecated in v1.3.2). Use ibexa.rest.field_type.processor instead.

4. Empty Responses:

   • Endpoints like /languages/{code} may return 404 if the language doesn’t exist. Validate codes first:

     curl -X GET http://your-site.com/api/ezplatform/v2/languages
     

Debugging Tips

• Enable API Debug Mode:

  # config/packages/ibexa_rest.yaml
  ibexa_rest:
      debug: true
  

  Logs detailed requests/responses to var/log/ibexa_rest.log.

• Postman Collection: Import the Ibexa REST API Postman Collection for testing.

Extension Points

1. Custom Criteria: Extend search with DateMetadataCriterion (added in v1.3.4):

   // In a custom controller
   $criterion = new DateMetadataCriterion();
   $criterion->setDateRange('2023-01-01', '2023-12-31');
   $searchService->findContent($criterion);
   

2. CSRF Protection: Disable for specific endpoints in config/packages/security.yaml:

   access_control:
       - { path: ^/api/ezplatform/v2/unsafe-endpoint, roles: PUBLIC_ACCESS }
   

3. Performance:

   • Use ?fields=... to limit payload size.
   • Cache responses with ezplatform_rest.cache (Symfony Cache component).