eoneopay/api-formats

Package for working with API requests and responses in different formats

API Formats

Installation

Use Composer to install the package in your project:, _(*1)

composer require eoneopay/apiformats

Formats

By default the package handle JSON (application/json) and XML (application/xml, text/xml) formats. If you want to handle different formats or want to implement your own JSON/XML encoding logic, the only thing you need to do is creating your encoder implementing \EoneoPay\ApiFormats\Interfaces\RequestEncoderInterface and tell the package to use it, with which Mime types as explained in the Configuration section., _(*2)

Integration

Laravel

To integrate the package into your Laravel or Lumen you need to register the following service provider and middleware:, _(*3)

• ServiceProvider: \EoneoPay\ApiFormats\Bridge\Laravel\Providers\ApiFormatsServiceProvider
• Middleware: \EoneoPay\ApiFormats\Bridge\Laravel\Middlewares\ApiFormatsMiddleware

That's it! Your application is now able to easily receive requests and generate responses in several formats., _(*4)

Formatted Api Response

If you want to customise the generated response as its status code or headers without handling body encoding yourself, the package provides the \EoneoPay\ApiFormats\Bridge\Laravel\Responses\FormattedApiResponse object you can return from your controllers/middlewares. The FormattedApiResponse accept three parameters through its constructor as following:, _(*5)

• $content (mixed): array or object able to be cast as an array
• $statusCode (int): status code of response, default as 200
• $headers (array): headers of response, default as empty array

Configuration

The philosophy of the package is to map encoders to a list of MIME types that they can handle through an array as following:, _(*6)

$formats = [
    <RequestEncoderInterface> => [<mime_type>, <mime_type>, ...]
];

Each MIME type can be the exact name as application/json or a Regex used to match multiple MIME types as application/vnd.eoneopay.v[0-9]+\+json., _(*7)

Laravel

To configure supported formats in your application, create a api-formats.php config file with a formats array using the encoders class as key and array of associated Mime types as value:, _(*8)

// config/api-formats.php

return [
    'formats' => [
        JsonRequestEncoder::class => ['application/json'],
        XmlRequestEncoder::class => ['(application|text)/xml'],
        YourCustomerEncoder::class => ['you-custom-mime-type']
    ]
];