README

!(http://engeni.com/emails/signature/logo.png)

Engeni API Tools is a set of classes that are meant to unify API development of microservices.

• Context and API Context handling
• Standardized JSON responses via response macros
• HTTP middleware and Laravel service providers
• And more...

Please note that you need an Engeni API Key to access all Engeni API resources. Please, get in contact with Engeni at: info@engeni.com.

Installation

Install composer first. Then:

composer require engeni/api-tools

TokenAuth middleware

Use this middleware to authenticate the user for a lumen/laravel api protected by an oauth2 server (Passport) /Http/Middleware/TokenAuth.php.

You can use it directly or extend from it and add or override functionality.

Response Macros

To standardize API responses, we provide response macros through the ResponseMacroServiceProvider. This simplifies returning consistent, well-formatted JSON responses with appropriate HTTP status codes.

Registration

Register the service provider in your config/app.php:

'providers' => [
    // Other service providers...
    Engeni\ApiTools\Providers\ResponseMacroServiceProvider::class,
],

Available Macros

The service provider adds several macros to Laravel's response() helper:

Success Responses (2xx)

• success() - Returns data with 200 status
• created() - Returns data with 201 status
• accepted() - Returns data with 202 status
• partialContent() - Returns data with 206 status

Error Responses (4xx, 5xx)

• error(), unauthorized(), forbidden(), notFound(), etc.
• All error responses return appropriate status codes with an error message
• For validation errors, use unprocessableEntity() with validation errors array

No Content Responses

• resetContent() - Returns 205 status with no content
• notModified() - Returns 304 status with no content

Examples

// Success response
return response()->success(['user' => $user]);

// Created response after storing a resource
return response()->created(['id' => $newResource->id]);

// Error response
return response()->notFound('The requested resource was not found');

// Validation error with details
return response()->unprocessableEntity(
    'The given data was invalid.',
    ['email' => ['The email field is required']]
);

In development environments, error responses will include debug information when app.debug is enabled.

Enjoy. The Engeni Team. https://engeni.com