Api Suite Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require actinoids/api-suite-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Actinoids\ApiSuiteBundle\ActinoidsApiSuiteBundle::class => ['all' => true],
   ];
   

2. Configuration: Define API endpoints in config/packages/actinoids_api_suite.yaml:

   actinoids_api_suite:
       services:
           my_api:
               url: 'https://api.example.com'
               auth: 'oauth1a'
               credentials:
                   consumer_key: 'your_key'
                   consumer_secret: 'your_secret'
   

3. First Use Case: Fetch data from an authenticated API in a controller:

   use Actinoids\ApiSuiteBundle\Service\ApiService;
   
   class MyController extends AbstractController
   {
       public function index(ApiService $apiService)
       {
           $response = $apiService->get('my_api', '/endpoint');
           return $this->json($response->getData());
       }
   }
   

Implementation Patterns

Core Workflows

1. Service Integration:

   • Inject ApiService into controllers/services to interact with APIs.
   • Use dependency injection for configuration (e.g., oauth1a credentials).

2. Request Handling:

   • GET/POST/PUT/DELETE:

     $apiService->get('service_name', '/path', ['param' => 'value']);
     $apiService->post('service_name', '/path', ['data' => 'payload']);
     

   • Headers:

     $apiService->setHeaders('service_name', ['X-Custom-Header' => 'value']);
     

3. OAuth1a Authentication:

   • Configure in YAML (see above).
   • Automatically signs requests with oauth1a signature.

4. Response Processing:

   • Access raw response:

     $response = $apiService->get('service_name', '/path');
     $rawBody = $response->getBody();
     

   • Parse JSON:

     $data = $response->getData(); // Auto-decodes JSON
     

Advanced Patterns

1. Custom Curl Options:

   • Override defaults via configuration:

     actinoids_api_suite:
         services:
             my_api:
                 curl_options:
                     CURLOPT_TIMEOUT: 30
                     CURLOPT_SSL_VERIFYPEER: false
     

2. Event Listeners:

   • Extend behavior by subscribing to api.request and api.response events:

     // src/EventListener/MyApiListener.php
     public function onApiRequest(ApiRequestEvent $event) {
         $event->setOption('CURLOPT_HTTPHEADER', ['X-My-Header: value']);
     }
     

3. Service Factories:

   • Dynamically create API services:

     $apiService->createService('dynamic_name', [
         'url' => 'https://dynamic.example.com',
         'auth' => 'oauth1a',
         // ...
     ]);
     

Gotchas and Tips

Pitfalls

1. Deprecated Symfony2:

   • Bundle targets Symfony 2.x (not compatible with Laravel or Symfony 3+).
   • Use with Symfony 2.3–2.8 only. For Laravel, consider alternatives like guzzlehttp/guzzle.

2. OAuth1a Quirks:

   • Timestamp Sensitivity: OAuth1a requires precise timestamps. If requests fail, verify:

     $apiService->setOption('service_name', CURLOPT_TIMEOUT, 10); // Ensure time sync
     

   • Nonce Collisions: Regenerate nonces if reusing the same request (e.g., in tests).

3. Response Handling:

   • Auto-Decoding: getData() assumes JSON. For XML/other formats, use getBody() and parse manually.
   • Error Responses: Check $response->isSuccess() before accessing data:

     if (!$response->isSuccess()) {
         throw new \RuntimeException($response->getError());
     }
     

4. Configuration Overrides:

   • Priority: CLI config overrides config/packages/. Use environment variables for sensitive data:

     # config/packages/actinoids_api_suite.yaml
     credentials:
         consumer_secret: "%env(API_SECRET)%"
     

Debugging Tips

1. Enable Curl Debugging:

   actinoids_api_suite:
       debug: true
       curl_options:
           CURLOPT_VERBOSE: true
   

   Logs appear in Symfony’s dev.log.

2. Validate OAuth Signatures:

   • Use OAuth1a tools to manually verify signatures:

     curl --oauth_consumer_key KEY --oauth_consumer_secret SECRET ...
     

3. Common Errors:

   • 401 Unauthorized: Check OAuth credentials or timestamps.
   • Connection Timeout: Increase CURLOPT_TIMEOUT or verify endpoint URLs.
   • SSL Errors: Disable verification temporarily for testing (not production):

     curl_options:
         CURLOPT_SSL_VERIFYPEER: false
     

Extension Points

1. Custom Auth Methods:

   • Extend Actinoids\ApiSuiteBundle\Service\Auth\AuthInterface for new auth schemes (e.g., OAuth2):

     class MyAuth implements AuthInterface {
         public function signRequest(Request $request) { ... }
     }
     

   • Register in services:

     services:
         my_auth:
             class: App\Service\MyAuth
             tags: ['actinoids_api.auth']
     

2. Response Transformers:

   • Override Actinoids\ApiSuiteBundle\Response\Response to customize parsing:

     $response->setTransformer(function ($body) {
         return json_decode($body, true)['custom_key'];
     });
     

3. Middleware:

   • Add request/response middleware via events:

     // src/EventSubscriber/MyMiddleware.php
     public static function getSubscribedEvents() {
         return [
             KernelEvents::REQUEST => 'onKernelRequest',
         ];
     }
     public function onKernelRequest(GetResponseEvent $event) {
         if ($event->isMasterRequest()) {
             $event->getRequest()->headers->set('X-My-Middleware', 'value');
         }
     }