Setup & Configuration

Get the Bagisto API up and running in just a few minutes. Choose the installation method that works best for your setup.

Prerequisites

Before installing, ensure you have:

• Bagisto v2.0 or higher (Bagisto Installation Guide)
• Composer 2.0+

Installation Methods

Method 1: Quick Start (Composer Installation – Recommended)

The fastest way to get started:

# 1. Install the Bagisto API package
composer require bagisto/bagisto-api

# 2. Run the installer
php artisan bagisto-api-platform:install

Your APIs are now ready! Access them at:

• API Documentation: https://your-domain.com/api
  (e.g., https://api-demo.bagisto.com/api)

Method 2: Manual Installation

Use this method if you need more control over the setup.

Step 1: Download and Extract

1. Download the BagistoApi package from GitHub
2. Extract it to: packages/Webkul/BagistoApi/

Step 2: Register Service Provider

Edit bootstrap/providers.php:

<?php

return [
    // ...existing providers...
    Webkul\BagistoApi\Providers\BagistoApiServiceProvider::class,
    // ...rest of providers...
];

Step 3: Update Autoloading

Edit composer.json and update the autoload section:

{
  "autoload": {
    "psr-4": {
      "Webkul\\BagistoApi\\": "packages/Webkul/BagistoApi/src"
    }
  }
}

Step 4: Install Dependencies

Install the required API Platform packages, pinned to a consistent, tested set so the install completes cleanly:

composer require \
  api-platform/laravel:v4.1.25 \
  api-platform/graphql:v4.2.3 \
  api-platform/metadata:v4.3.1 \
  api-platform/serializer:v4.3.1 \
  api-platform/state:v4.3.1 \
  api-platform/jsonld:v4.3.1 \
  api-platform/hydra:v4.3.1 \
  api-platform/openapi:v4.3.1 \
  api-platform/json-schema:v4.3.1 \
  api-platform/json-api:v4.3.1 \
  api-platform/documentation:v4.3.1

Step 5: Run the installation

composer dump-autoload
php artisan bagisto-api-platform:install

Step 6: Environment Setup (Update in the .env)

STOREFRONT_DEFAULT_RATE_LIMIT=100
STOREFRONT_CACHE_TTL=60
STOREFRONT_KEY_PREFIX=storefront_key_
STOREFRONT_PLAYGROUND_KEY=pk_storefront_vxLIYv5PIp7jkujPNGLFQoDvIdsh2RMF 
API_PLAYGROUND_AUTO_INJECT_STOREFRONT_KEY=true

Access Points

Once verified, access the APIs at:

• API Documentation: https://your-domain.com/api
• REST API (Shop): https://your-domain.com/api/shop
• REST API (Admin): https://your-domain.com/api/admin
• GraphQL Endpoint: https://your-domain.com/api/graphql
• GraphQL Playground: https://your-domain.com/api/graphiql

Troubleshooting

Provider Not Found

Error: Class 'Webkul\BagistoApi\Providers\BagistoApiServiceProvider' not found

Solution:

composer dump-autoload
php artisan cache:clear
php artisan config:clear

404 Errors on API Endpoints

Error: API endpoints return 404 Not Found

Solutions:

1. Ensure routes are published: php artisan vendor:publish --tag=routes
2. Clear route cache: php artisan route:clear
3. Check .htaccess file is present in your web root
4. Verify APP_URL in .env matches your domain

Database Connection Errors

Error: SQLSTATE[HY000]: General error: 1030 Got error

Solutions:

1. Verify database credentials in .env
2. Run migrations: php artisan migrate
3. Check database encoding: utf8mb4
4. Ensure sufficient disk space

Rate Limiting Issues

Error: 429 Too Many Requests

Rate limits are per credential, not a global .env value:

• Storefront (Shop API) — each Storefront Key carries its own limit. Raise it when generating the key with --rate-limit (default 100/min, up to 5000, or null for unlimited), or rotate to a higher-limit key:

  php artisan bagisto-api:generate-key --name="High-Traffic App" --rate-limit=1000

  See API Key Management and the Rate Limiting Guide.
• Admin API — each Integration token has a per-minute and per-day limit set in the Integration menu of the admin panel. Edit the token there (or issue a new one) to change its limits.

CORS Errors in Browser

Error: Access to XMLHttpRequest blocked by CORS policy

Solutions:

1. Verify CORS is configured in config/cors.php
2. Check FRONTEND_URL environment variable
3. Ensure supports_credentials is set properly
4. Clear browser cache

Performance Optimization

Ensure the application is running in a production environment and that APP_DEBUG is set to false.

# Clear the API Platform metadata cache (run after adding or changing an endpoint)
php artisan bagisto-api-platform:clear-cache

# Rebuild + warm all caches for fast responses (run after every deploy or endpoint change)
php artisan bagisto-api-platform:optimize

What's Next?

Ready to start using the APIs?

• 🔐 Authentication Guide - Learn about authentication methods
• 🔗 REST API Guide - Explore REST API endpoints
• ⚡ GraphQL API Guide - Discover GraphQL capabilities
• 🔑 API Key Management - Generate and manage API keys