Api Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require carloschininin/api-bundle
   

   Add to config/app.php under providers:

   CarlosChininin\ApiBundle\ApiServiceProvider::class,
   

   Publish the config (if available):

   php artisan vendor:publish --provider="CarlosChininin\ApiBundle\ApiServiceProvider"
   

2. First Use Case: Basic API Request Register a new API client in config/api.php:

   'clients' => [
       'example' => [
           'base_uri' => 'https://api.example.com',
           'timeout' => 30,
       ],
   ],
   

   Use the facade in a controller or service:

   use CarlosChininin\ApiBundle\Facades\Api;
   
   $response = Api::client('example')->get('/endpoint');
   $data = $response->json();
   

3. Key Files to Review

   • config/api.php (configuration)
   • src/Facades/Api.php (facade usage)
   • src/ApiServiceProvider.php (service registration)

Implementation Patterns

Workflows

1. Request/Response Handling Use the facade for HTTP methods:

   $response = Api::client('example')->post('/users', ['name' => 'John']);
   $response->status(); // 201
   $response->json();   // Decoded JSON
   

2. Authentication Attach auth headers globally in config:

   'clients' => [
       'authenticated' => [
           'base_uri' => 'https://api.example.com',
           'headers' => [
               'Authorization' => 'Bearer token123',
           ],
       ],
   ],
   

   Or dynamically:

   Api::client('example')->withHeaders(['X-API-Key' => 'secret'])->get('/secure');
   

3. Error Handling Use middleware or exceptions:

   try {
       $response = Api::client('example')->get('/fail');
   } catch (\CarlosChininin\ApiBundle\Exceptions\ApiException $e) {
       Log::error($e->getMessage());
   }
   

4. Integration with Laravel Services Bind the client to a service container:

   $this->app->bind('api.example', function ($app) {
       return Api::client('example');
   });
   

   Inject into controllers:

   public function __construct(\CarlosChininin\ApiBundle\ApiClient $client) {
       $this->client = $client;
   }
   

5. Testing Mock the facade in tests:

   Api::shouldReceive('client')->andReturn($mockClient);
   

Gotchas and Tips

Pitfalls

1. No Built-in Retry Logic

   • Manually implement retry logic for transient failures:

     $retry = 3;
     while ($retry--) {
         try {
             $response = Api::client('example')->get('/endpoint');
             break;
         } catch (\Exception $e) {
             if ($retry === 0) throw $e;
             sleep(1);
         }
     }
     

2. Config Overrides

   • Ensure config/api.php is published and merged correctly. Use php artisan config:clear if changes aren’t reflected.

3. Facade vs. Direct Client

   • Prefer dependency injection for testability:

     // Bad: Facade in constructor
     public function __construct() {
         $this->client = Api::client('example'); // Tight coupling
     }
     // Good: Inject interface
     public function __construct(ApiClientInterface $client) { ... }
     

4. No Built-in Rate Limiting

   • Use Laravel’s throttle middleware or implement custom logic:

     $response = Api::client('example')
         ->withMiddleware(new \CarlosChininin\ApiBundle\Middleware\RateLimit())
         ->get('/rate-limited');
     

Tips

1. Custom Clients Extend the base client for domain-specific logic:

   namespace App\Services;
   
   use CarlosChininin\ApiBundle\ApiClient;
   
   class StripeClient extends ApiClient {
       public function createCustomer(array $data) {
           return $this->post('/customers', $data);
       }
   }
   

2. Logging Enable request/response logging in config:

   'logging' => true,
   

   Or use middleware:

   Api::client('example')->withMiddleware(new \CarlosChininin\ApiBundle\Middleware\Log());
   

3. Environment-Specific Config Use Laravel’s config caching:

   php artisan config:cache
   

   Override values in .env:

   API_EXAMPLE_BASE_URI=https://staging.example.com
   

4. Debugging

   • Dump raw responses:

     dd(Api::client('example')->get('/debug')->getBody());
     

   • Check for typos in client names (case-sensitive).

5. Performance

   • Reuse clients (they’re singleton by default):

     $client = Api::client('example'); // Reuse across requests