Getting Started

Minimal Steps to First Use

Installation:

composer require bagisto/bagisto-api
php artisan bagisto-api-platform:install

Verify APIs at /api, /api/shop/docs, and /api/graphiql.

First API Call (REST): Fetch shop products via:

curl -X GET "https://your-domain.com/api/shop/products" \
  -H "Authorization: Bearer pk_storefront_xxxxxxxxxxxxxxxxxxxxxxxxxx"

First GraphQL Query: Use the GraphiQL playground at /api/graphiql to run:

query {
  products {
    edges {
      node {
        id
        name
        sku
        price
      }
    }
  }
}

First Use Case: Product Catalog Integration

REST: Fetch products with filters:

curl -X GET "https://your-domain.com/api/shop/products?filter[category]=electronics&filter[price][from]=50"

GraphQL: Query product variants:

query {
  product(id: "PRODUCT_ID") {
    name
    variants {
      sku
      price
      stock
    }
  }
}

Implementation Patterns

Common Workflows

1. REST API Integration

Pagination: Use ?page[size]=20&page[number]=1 for paginated responses.
Filtering: Apply filters like filter[price][from]=50 or filter[status]=enabled.
Sorting: Sort by sort=-price (descending) or sort=name.
Embedding: Fetch related data via ?fields[products]=name,variants.price.

Example: Fetch Orders with Embedded Data

curl -X GET "https://your-domain.com/api/admin/orders?fields[orders]=items,addresses,payment" \
  -H "Authorization: Bearer id|generated-token"

2. GraphQL for Complex Queries

Batch Fetching: Query multiple resources in one request:

query {
  products {
    edges {
      node {
        id
        name
        variants {
          sku
          price
        }
      }
    }
  }
  categories {
    edges {
      node {
        id
        name
        products {
          edges {
            node {
              name
            }
          }
        }
      }
    }
  }
}

Mutations: Use for write operations (e.g., checkout):

mutation {
  placeOrder(input: {
    cartId: "CART_ID",
    paymentMethod: { code: "credit_card" },
    shippingMethod: { code: "flat_rate" }
  }) {
    orderId
    order {
      id
      number
    }
  }
}

3. Admin API Workflows

Token-Based Auth: Generate tokens via Settings → Integration in the admin panel.
Bulk Operations: Use CSV exports (?format=csv) for large datasets (e.g., orders, products).
Audit Logs: Track API changes via Integration → History.

Example: Bulk Update Product Status

curl -X PATCH "https://your-domain.com/api/admin/products?filter[status]=disabled" \
  -H "Authorization: Bearer id|generated-token" \
  -H "Content-Type: application/json" \
  -d '{"data": {"status": "enabled"}}'

4. Real-Time Updates

Webhooks: Extend the package to emit events (e.g., order.placed) via Laravel's events system.
Polling: Implement client-side polling for critical updates (e.g., order status).

Integration Tips

Laravel Service Integration

Dependency Injection: Inject Webkul\BagistoApi\Services\ApiService into controllers/services:
```
public function __construct(private ApiService $apiService) {}
```

Custom API Routes: Extend routes in routes/api.php:

Route::middleware('auth:api')->group(function () {
    Route::apiResource('custom-endpoint', CustomController::class);
});

Middleware: Use api.auth for shop endpoints and api.admin for admin endpoints.

Extending API Responses

Custom Fields: Add fields to serializers (e.g., ProductSerializer):

public function getCustomField($entity, string $format = null, array $context = [])
{
    return $entity->customField;
}

Overriding Resources: Publish and extend API resources:
```
php artisan vendor:publish --tag=api-resources
```
Then override in app/ApiResources.

Performance Optimization

Caching: Leverage Laravel's cache for frequent queries:

$products = Cache::remember("api_products_{$category}", 3600, function () {
    return $this->apiService->getProducts(['filter[category]' => $category]);
});

Rate Limiting: Configure in .env:

STOREFRONT_RATE_LIMIT=60
ADMIN_RATE_LIMIT=30

Gotchas and Tips

Pitfalls

1. Authentication Issues

Shop API: Requires a storefront key (pk_storefront_...). Ensure API_PLAYGROUND_AUTO_INJECT_STOREFRONT_KEY=true in .env.
Admin API: Tokens are one-time-use after generation. Use Regenerate if lost.
Token Scoping: Admin tokens inherit the user's role permissions. Test with a restricted admin account to avoid over-permissioning.

2. GraphQL vs. REST Quirks

GraphQL Nulls: Some fields (e.g., formattedPrice) may return null if not configured. Use if in queries:
```
price: product { price }
formattedPrice: product { formattedPrice }
```
REST Filtering: Complex filters (e.g., nested objects) may require multiple requests or custom endpoints.
Pagination: GraphQL uses edges and pageInfo, while REST uses page[size] and page[number].

3. Data Consistency

Concurrent Writes: Use optimistic locking (_method=PATCH with ETag) for critical updates.
Soft Deletes: Admin APIs respect soft-deleted models (e.g., ?filter[deleted_at][null]=true).

4. CSV Export Limitations

Filtering: CSV exports honor REST filters but may exclude complex GraphQL filters.
Large Datasets: Use chunking or background jobs for exports >10,000 records.

Debugging Tips

1. API Errors

422 Unprocessable Entity: Validate input data (e.g., missing required fields like vatId in addresses).
401 Unauthorized: Verify tokens/keys and middleware.
500 Internal Server Error: Check Laravel logs (storage/logs/laravel.log) for exceptions.

2. GraphQL Debugging

Introspection: Use the GraphiQL docs explorer to inspect types and fields.

Variables: Pass variables for dynamic queries:

query GetProduct($id: ID!) {
  product(id: $id) {
    name
    price
  }
}

{ "id": "PRODUCT_ID" }

3. Performance Bottlenecks

N+1 Queries: Use ?fields[products]=name,variants.price to embed data.
Slow Queries: Profile with Laravel Debugbar or telescope:install.

Extension Points

1. Custom API Endpoints

REST: Create a custom controller and route:

// app/Http/Controllers/Api/CustomController.php
public function customEndpoint()
{
    return $this->apiService->customLogic();
}

GraphQL: Extend the schema:

// app/GraphQL/Mutations/CustomMutation.php
class CustomMutation extends Mutation
{
    public function mutate()
    {
        // Logic here
    }
}

2. Overriding Serializers

Publish and extend serializers:
```
php artisan vendor:publish --tag=api-serializers
```
Then override in app/Serializers.

3. Adding Custom Fields

Extend the Product model and update the serializer:

// app/Models/Product.php
public function getCustomFieldAttribute()
{
    return $this->custom_field;
}

// app/Serializers/ProductSerializer.php
public function getCustomField($entity)
{
    return $entity->custom_field;
}

4. Webhooks for Real-Time Updates

Listen to Bagisto events and emit API calls:

Bagisto Api Laravel Package