Jdd Api Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require coredump/jdd-api
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       Coredump\JddApi\JddApiServiceProvider::class,
   ],
   

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="Coredump\JddApi\JddApiServiceProvider"
   

   Update .env with your JDD API credentials:

   JDD_API_KEY=your_api_key_here
   JDD_API_SECRET=your_api_secret_here
   

3. First Use Case: Fetching a Product

   use Coredump\JddApi\Facades\JddApi;
   
   $product = JddApi::product()->find(12345);
   dd($product);
   

Key Classes to Explore

• Facade: Coredump\JddApi\Facades\JddApi (main entry point)
• API Client: Coredump\JddApi\Client (handles HTTP requests)
• Resource Classes: Coredump\JddApi\Resources\Product, Order, etc. (model responses)

Implementation Patterns

Common Workflows

1. CRUD Operations

• Fetch a single resource (e.g., product, order):

  $product = JddApi::product()->find($id);
  

• List resources (with pagination):

  $products = JddApi::product()->all(['limit' => 10, 'page' => 1]);
  

• Create/Update (if API supports it):

  $created = JddApi::product()->create([
      'name' => 'New Product',
      'price' => 99.99,
  ]);
  

2. Handling API Responses

Use the Resource classes to access structured data:

$order = JddApi::order()->find($orderId);
$customerName = $order->customer->name; // Nested access

3. Error Handling

Wrap API calls in try-catch:

try {
    $data = JddApi::product()->find($id);
} catch (\Coredump\JddApi\Exceptions\ApiException $e) {
    Log::error('JDD API Error: ' . $e->getMessage());
    // Fallback logic
}

4. Integration with Laravel Models

Attach API data to Eloquent models:

public function getJddProductAttribute()
{
    return JddApi::product()->find($this->jdd_id);
}

5. Custom Endpoints

Extend the client for unsupported endpoints:

$response = JddApi::client()->get('/custom-endpoint', ['param' => 'value']);

Integration Tips

Queueing API Calls

Offload heavy API calls to queues:

dispatch(new FetchJddProducts($productIds))->onQueue('jdd-api');

Caching Responses

Cache API responses to reduce calls:

$product = Cache::remember("jdd_product_{$id}", now()->addHours(1), function () use ($id) {
    return JddApi::product()->find($id);
});

Logging API Activity

Log requests/responses for debugging:

JddApi::client()->setLogger(function ($request, $response) {
    Log::debug('JDD API Request', [
        'url' => $request->getUri(),
        'method' => $request->getMethod(),
        'response' => $response->getBody(),
    ]);
});

Gotchas and Tips

Pitfalls

1. Deprecated Package

   • Last release in 2021; verify API compatibility with JDD’s current endpoints.
   • Check for breaking changes in the JDD API docs (if available).

2. No Official Documentation

   • Rely on the source code for undocumented features.
   • Example: Resource classes may not cover all API fields—extend them if needed:

     namespace App\Extensions\JddApi;
     use Coredump\JddApi\Resources\Product as BaseProduct;
     
     class Product extends BaseProduct
     {
         public function getCustomFieldAttribute()
         {
             return $this->attributes['custom_field'] ?? null;
         }
     }
     

3. Authentication Issues

   • Ensure JDD_API_KEY and JDD_API_SECRET are correct and not hardcoded.
   • Test with a sandbox environment first.

4. Rate Limiting

   • The package doesn’t handle rate limits by default. Implement retries:

     use Symfony\Component\HttpClient\RetryableHttpClient;
     
     $client = new RetryableHttpClient(
         JddApi::client()->getHttpClient(),
         [
             'max_retries' => 3,
             'delay' => 100,
             'max_delay' => 1000,
             'multiplier' => 2,
         ]
     );
     

5. Nested Resource Access

   • Some nested data (e.g., $order->customer) may require lazy loading:

     $customer = $order->load('customer')->customer;
     

Debugging Tips

1. Enable Verbose Logging

   JddApi::client()->setDebug(true);
   

   Check logs for raw API responses.

2. Inspect HTTP Client Replace the default client for debugging:

   JddApi::setClient(function () {
       return \Symfony\Component\HttpClient\HttpClient::create([
           'debug' => true,
           'headers' => ['User-Agent' => 'Laravel Debugger'],
       ]);
   });
   

3. Validate API Responses Use Laravel’s validate() to ensure responses match expectations:

   $product = JddApi::product()->find($id);
   $validator = Validator::make($product->toArray(), [
       'id' => 'required|integer',
       'name' => 'required|string',
   ]);
   

Extension Points

1. Custom Resources Override resource classes to add methods or fields:

   namespace App\Resources\JddApi;
   use Coredump\JddApi\Resources\Product;
   
   class Product extends \Coredump\JddApi\Resources\Product
   {
       public function isOnSale()
       {
           return $this->price < $this->original_price;
       }
   }
   

   Bind the custom class in a service provider:

   JddApi::extend('product', function () {
       return new App\Resources\JddApi\Product();
   });
   

2. Middleware for API Requests Add middleware to modify requests/responses:

   JddApi::client()->addMiddleware(function (callable $next) {
       $request = $next(function () {
           return new \Symfony\Component\HttpClient\MockHttpClient([
               new \Symfony\Component\HttpClient\MockResponse('{}'),
           ]);
       });
       // Modify request/response here
       return $request;
   });
   

3. Event Listeners Listen for API events (if the package emits them):

   JddApi::client()->on('request', function ($request) {
       Log::info('API Request:', $request->getUri());
   });