Dingo Api Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require api-ecosystem-for-laravel/dingo-api
   

   Publish the config and migrations:

   php artisan vendor:publish --provider="Dingo\Api\Provider\LaravelServiceProvider"
   php artisan migrate
   

2. Register the Service Provider Add to config/app.php under providers:

   Dingo\Api\Provider\LaravelServiceProvider::class,
   

3. Define Your First Route In routes/api.php:

   $api->version('v1', function ($api) {
       $api->get('users', 'App\Http\Controllers\UserController@index');
   });
   

4. First Controller

   namespace App\Http\Controllers;
   
   use Dingo\Api\Routing\Helpers;
   use App\Models\User;
   
   class UserController extends Controller
   {
       use Helpers;
   
       public function index()
       {
           return $this->response->array(User::all());
       }
   }
   

5. Test the API Use tools like Postman or cURL:

   curl http://your-app.test/api/v1/users
   

Where to Look First

• Documentation: Dingo API Docs (or legacy Dingo docs as reference).
• Config File: config/dingo.php for API versioning, middleware, and routing defaults.
• Middleware: app/Http/Middleware/ for custom API middleware.
• Route Definitions: routes/api.php for API-specific routes.

First Use Case: Versioned API Endpoint

Create a versioned endpoint with custom middleware:

// routes/api.php
$api->version('v1', ['middleware' => 'auth.api'], function ($api) {
    $api->get('protected-data', 'App\Http\Controllers\ProtectedController@index');
});

Implementation Patterns

1. API Versioning

• URL Versioning: Default (/api/v1/endpoint).
• Header Versioning: Configure in config/dingo.php:

  'versioning' => [
      'accept_header' => true,
  ],
  

• Route Grouping: Use version() method for logical grouping.

2. Middleware Integration

• Global Middleware: Register in config/dingo.php:

  'middleware' => [
      'api' => \App\Http\Middleware\CheckForApiToken::class,
  ],
  

• Route-Specific Middleware: Pass as an array in route definitions:

  $api->get('admin', ['middleware' => 'admin'], 'AdminController@index');
  

3. Request/Response Handling

• Custom Responses: Extend Dingo\Api\Http\Response:

  namespace App\Http\Controllers;
  
  use Dingo\Api\Http\Response;
  
  class UserController extends Controller
  {
      protected $response;
  
      public function __construct(Response $response)
      {
          $this->response = $response;
      }
  
      public function show($id)
      {
          return $this->response->created('/users/' . $id, ['id' => $id]);
      }
  }
  

• Request Validation: Use Laravel’s built-in validation or Dingo’s Request class:

  use Dingo\Api\Request;
  
  public function store(Request $request)
  {
      $validated = $request->validate([
          'name' => 'required|string|max:255',
      ]);
  }
  

4. Authentication & Authorization

• Token-Based Auth: Use auth:api middleware (Laravel Passport integration):

  $api->get('profile', ['middleware' => 'auth:api'], 'ProfileController@show');
  

• Custom Guards: Configure in config/auth.php and reference in routes:

  $api->get('admin', ['middleware' => 'auth:admin-api'], 'AdminController@dashboard');
  

5. Error Handling

• Custom Error Responses: Override app/Exceptions/Handler.php:

  public function register()
  {
      $this->renderable(function (\Symfony\Component\HttpKernel\Exception\HttpException $e) {
          return response()->json([
              'error' => [
                  'message' => $e->getMessage(),
                  'status_code' => $e->getStatusCode(),
              ],
          ], $e->getStatusCode());
      });
  }
  

• API-Specific Errors: Use Dingo’s ApiException:

  throw new \Dingo\Api\Exception\StoreResourceFailedException('User not found');
  

6. Testing

• HTTP Tests: Use Laravel’s Http facade:

  $response = $this->get('/api/v1/users');
  $response->assertStatus(200);
  

• Mocking Requests: Use Dingo’s Request class in tests:

  $request = \Dingo\Api\Request::createFromGlobals();
  $this->app->instance('request', $request);
  

7. Integration with Laravel Features

• Eloquent Models: Use as-is in controllers.
• Events & Listeners: Trigger Laravel events from Dingo controllers:

  event(new UserCreated($user));
  

• Queues: Dispatch jobs:

  dispatch(new SendWelcomeEmail($user));
  

Gotchas and Tips

Pitfalls

1. Middleware Order Matters

   • Dingo middleware runs after Laravel middleware. Ensure api middleware is registered in config/dingo.php after Laravel’s global middleware in app/Http/Kernel.php.
   • Example: If auth:api fails, check if the api middleware group is misconfigured.

2. Route Caching Conflicts

   • Clear route cache after adding new routes:

     php artisan route:clear
     

   • Avoid caching routes during development ('cache' => env('API_ROUTES_CACHE', false) in config/dingo.php).

3. Versioning Headers vs. URLs

   • If using accept_header versioning, ensure the Accept: application/vnd.yourapi.v1+json header is sent. Mixing URL and header versioning can cause conflicts.

4. CSRF Protection

   • Dingo APIs are typically stateless. Disable CSRF for API routes in app/Http/Middleware/VerifyCsrfToken.php:

     protected $except = [
         'api/*',
     ];
     

5. Dependency Injection

   • Dingo uses Laravel’s IoC container. If a service isn’t bound, you’ll get BindingResolutionException. Ensure all dependencies are properly registered.

Debugging Tips

1. Route Debugging

   • List all API routes:

     php artisan route:list --path=api
     

   • Use dd($api->getRoutes()) in routes/api.php to inspect routes dynamically.

2. Middleware Debugging

   • Temporarily log middleware execution:

     public function handle($request, Closure $next)
     {
         \Log::info('Middleware executed', ['path' => $request->path()]);
         return $next($request);
     }
     

3. Request/Response Logging

   • Enable Dingo’s request/response logging in config/dingo.php:

     'debug' => env('APP_DEBUG', false),
     'log_request' => true,
     'log_response' => true,
     

4. Common Errors

   • 404 Not Found: Verify the route exists and the version is correct.
   • 500 Internal Server Error: Check Laravel logs (storage/logs/laravel.log) for exceptions.
   • 422 Unprocessable Entity: Validate request data matches the expected schema.

Configuration Quirks

1. Default Response Format

   • Override the default JSON response format in config/dingo.php:

     'default' => [
         'format' => 'json',
         'json' => [
             'encoding' => 'UTF-8',
             'options' => JSON_PRETTY_PRINT,
         ],
     ],
     

2. CORS Configuration

   • Configure CORS in config/dingo.php:

     'cors' => [
         'paths' => ['api/*'],
         'allowed_methods' => ['*'],
         'allowed_origins' => ['*'],
         'allowed_headers' => ['*'],
     ],
     

   • For production, restrict allowed_origins to specific domains.

3. Rate Limiting

   • Use Laravel’s rate limiting middleware:

     $api->middleware(['throttle:60,1']);
     $api->get('rate-limited', 'RateLimitedController@index');
     

Extension Points

1. **Custom