Rest Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ibexa/rest
   

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

2. Enable API: Add the bundle to your config/packages/ibexa_rest.yaml:

   ibexa_rest:
       enabled: true
       api_version: 'v2'
   

3. First Use Case: Test the API with a simple content fetch:

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

Key Starting Points

• Official Docs: REST API Reference
• Endpoints: /api/v2/content, /api/v2/search, /api/v2/languages
• Authentication: Token-based via /api/v2/session (POST with credentials).

Implementation Patterns

Core Workflows

1. Content Management:

   • Fetch Content:

     $client = new \GuzzleHttp\Client();
     $response = $client->get('api/v2/content/1', [
         'headers' => ['Authorization' => 'Bearer YOUR_TOKEN']
     ]);
     

   • Create Draft:

     $response = $client->post('api/v2/content/1/draft', [
         'json' => ['fields' => [...]],
         'headers' => ['Authorization' => 'Bearer YOUR_TOKEN']
     ]);
     

2. Search Integration:

   • Use /api/v2/search with query parameters:

     $response = $client->get('api/v2/search', [
         'query' => [
             'query' => 'title:example',
             'criterion' => json_encode(['ContentType' => ['identifier' => 'article']])
         ]
     ]);
     

3. Authentication:

   • Login:

     $response = $client->post('api/v2/session', [
         'json' => ['username' => 'admin', 'password' => 'password']
     ]);
     

   • Logout:

     $response = $client->delete('api/v2/session', [
         'headers' => ['Authorization' => 'Bearer YOUR_TOKEN']
     ]);
     

Laravel-Specific Patterns

1. Service Integration: Use Laravel's HTTP client to wrap API calls:

   use Illuminate\Support\Facades\Http;
   
   $content = Http::withHeaders([
       'Authorization' => 'Bearer ' . $token
   ])->get('api/v2/content/1')->json();
   

2. Middleware for API Calls: Create middleware to inject tokens:

   public function handle($request, Closure $next) {
       $request->headers->set('Authorization', 'Bearer ' . auth()->user()->api_token);
       return $next($request);
   }
   

3. Event-Driven Workflows: Listen to Ibexa events (e.g., ContentPublish) and trigger API calls:

   Ibexa\Core\Event\Content\PublishEvent::class => function ($event) {
       Http::post('api/v2/content/' . $event->getContent()->id . '/publish');
   }
   

4. Custom Endpoints: Extend Ibexa's API by creating custom controllers:

   namespace App\Http\Controllers;
   
   use Ibexa\Rest\Server\Controller\Content;
   use Symfony\Component\HttpFoundation\Request;
   
   class CustomContentController extends Content {
       public function customAction(Request $request) {
           // Extend logic here
       }
   }
   

Gotchas and Tips

Pitfalls

1. Authentication Quirks:

   • Token Handling: Tokens expire; implement refresh logic:

     $response = Http::post('api/v2/session/refresh', [
         'headers' => ['Authorization' => 'Bearer EXPIRED_TOKEN']
     ]);
     

   • Header Mismatch: Ensure X-Expected-User matches the authenticated user.

2. Content-Type Issues:

   • Media Types: Use supported_media_types flag for file uploads:

     $response = Http::post('api/v2/content/1/fields/image', [
         'headers' => [
             'Content-Type' => 'image/jpeg',
             'supported_media_types' => 'image/*'
         ]
     ]);
     

3. Deprecated Routes:

   • Avoid ibexa.rest.refresh_session; use ibexa.rest.check_session instead.

4. Nested Objects:

   • ENCODER_CONTEXT may appear in responses; filter it out if needed:

     $data = array_filter($response->json(), fn($key) => $key !== 'ENCODER_CONTEXT', ARRAY_FILTER_USE_KEY);
     

Debugging Tips

1. Enable API Debugging: Set IBEXA_REST_DEBUG=1 in your environment to log requests/responses.

2. Common Errors:

   • 403 Forbidden: Check token validity and user permissions.
   • 404 Not Found: Verify content IDs and endpoint paths.
   • 500 Internal Server Error: Enable Symfony's error logging (APP_DEBUG=1).

3. Postman Collection: Use the Ibexa REST API Postman Collection for testing.

Extension Points

1. Custom Input Parsers: Extend Ibexa\Rest\Input\Parser\CriterionParserInterface for custom criteria:

   namespace App\Rest\Input\Parser;
   
   use Ibexa\Rest\Input\Parser\CriterionParserInterface;
   use Ibexa\Rest\Input\Parser\CriterionParser;
   
   class CustomCriterionParser extends CriterionParser implements CriterionParserInterface {
       public function parse($value) {
           // Custom logic
       }
   }
   

2. Override Serialization: Extend Ibexa\Rest\Output\Visitor\ValueObjectVisitor for custom field serialization.

3. Firewall Configuration: Customize security in config/packages/security.yaml:

   firewalls:
       api:
           pattern: ^/api/v2
           stateless: true
           provider: ibexa_rest.token_provider
           entry_point: ibexa_rest.token_authenticator
   

4. Event Listeners: Subscribe to Ibexa events (e.g., ContentCreateEvent) to react to API changes:

   Ibexa\Core\Event\Content\CreateEvent::class => function ($event) {
       // Trigger custom logic
   }
   

Performance Tips

1. Pagination: Use limit and offset for large datasets:

   $response = Http::get('api/v2/search', [
       'query' => ['limit' => 10, 'offset' => 20]
   ]);
   

2. Caching: Cache frequent API responses in Laravel:

   $content = Cache::remember("content_{$id}", 3600, function () use ($id) {
       return Http::get("api/v2/content/{$id}")->json();
   });
   

3. Batch Operations: Use /api/v2/content/batch for bulk updates/deletes.