Dingo API

The Dingo API package provides a suite of tools for building robust APIs in Laravel. Key features include:

• Content Negotiation: Handle different response formats.
• Authentication: Support for multiple authentication adapters.
• Versioning: Manage multiple API versions.
• Rate Limiting: Control request frequency.
• Transformers & Formatters: Transform and format API responses.
• Error Handling: Standardized error and exception handling.
• Internal Requests: Ability to make requests within the application.
• Documentation: Support for API Blueprint documentation.

If you cannot find answers in the Wiki documentation, use the following channels:

1. Slack: Join the dedicated Slack room and mention specialtactics to ensure notification.
2. GitHub Discussions: Start a new discussion in the Q&A category.

This repository is an official fork of the original dingo/api package. To migrate, you only need to update your composer.json file. All namespaces and project aspects remain identical, ensuring a seamless transition.

Note: Lumen support is not actively maintained. It is recommended to migrate to Laravel if you are currently using Lumen.

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

You can restrict access to specific routes using OAuth 2.0 scopes. Use the scopes key in the route action to define the required scopes.

If the controller uses the Dingo\Api\Helpers\Helpers trait, you can also define scopes via controller methods (e.g., getScopes()). The route will merge these properties. You can further refine scope application using only or except filters within the scope definition to target specific controller methods.

Dingo API provides mechanisms to limit request rates on a per-route basis. You can configure this using the following keys in the route action:

• limit: The maximum number of requests allowed.
• expires: The duration (in minutes) before the limit resets.
• throttle: A specific throttle class or instance.

If the controller uses the Dingo\Api\Helpers\Helpers trait, you can also define these via controller methods like getRateLimit(), getThrottles(), etc. Throttles defined via the throttle key take precedence over standard rate limits.

When defining routes in Dingo API, you can pass specific keys within the route action array to configure API-specific behaviors. These properties can be set directly in the route definition or via the controller if the controller uses the Dingo\Api\Helpers\Helpers trait.

Available action keys:

• version: An array of API versions this route responds to.
• conditionalRequest: Boolean indicating if the request is conditional (defaults to true).
• middleware: Array of middleware to apply.
• throttle: A throttle instance or a string representing the throttle class.
• scopes: Array of OAuth 2.0 scopes required for the route.
• providers: Array of authentication providers.
• limit: The rate limit integer.
• expires: The rate limit expiration time.
• scopeStrict: Boolean determining if the route requires all scopes or just any valid scope.

The authorize() method in a FormRequest determines if the current user is permitted to perform the requested action.

• If authorize() returns true, validation proceeds.
• If authorize() returns false, a Dingo\Api\Exception\AccessDeniedHttpException is thrown.

This is useful for checking ownership or specific permissions before even checking if the input data is valid.

public function authorize()
{
    // Example: Only allow the owner of a post to update it
    return $this->user()->can('update', $this->route('post'));
}

You can define specific options for different response formats globally.

• setFormatsOptions(array $formatsOptions): Sets an associative array where keys are format names and values are their respective option arrays.
• getFormatsOptions($format): Retrieves the options for a specific format.
• hasOptionsForFormat($format): Checks if options have been defined for a format.

use Dingo\Api\Http\Response;

Response::setFormatsOptions([
    'json' => ['indent' => 4, 'encode_ascii' => true],
    'xml'  => ['version' => '1.0'],
]);

When extending Dingo\Api\Http\FormRequest, you can override several methods to customize how data is validated and how errors are presented:

• rules(): Defines the validation logic.
• messages(): Returns an associative array of custom error messages (e.g., ['field.rule' => 'Custom message']).
• attributes(): Returns an associative array of custom attribute names (e.g., ['email' => 'email address']) to make error messages more readable.
• validationData(): Overriding this allows you to change the data source being validated (defaults to $this->all()).

public function rules()
{
    return ['username' => 'required'];
}

public function messages()
{
    return ['username.required' => 'Please provide a username.'];
}

public function attributes()
{
    return ['username' => 'user handle'];
}

You can inject custom data into the error response by using setReplacements. This allows you to add extra fields to the generic error response that are not covered by the default placeholders.

$handler->setReplacements([
    ':extra_info' => 'some-value',
]);