Apigility 1.2.0 and 1.3.0 Released!

Today, we released two new versions of Apigility:

Apigility 1.2.0 brings in a number of new features, including Docker support,
API Blueprint support, better error handling, and new features for REST and
RPC services.

Apigility 1.3.0 is exactly the same as 1.2.0, but with one key difference: it
updates the minimum supported PHP version from 5.3.23 to 5.5.

For existing users, you can update your applications using composer:

If you are new to Apigility, or just want to try out the new features, visit our download page for installation instructions:

You can install via composer as well:

Apigility 1.2.0

Apigility 1.2.0 builds on version 1.1.0, released in April, fixing many issues and shortcomings in our authentication system, primarily with OAuth2. Additionally, it provides a number of requested features in both our REST and RPC implementations, and better error handling.

Things of specific interest include:

  • New API Blueprint capabilities. Our friends at apiary.io generously donated a new module, zfcampus/zf-apigility-documentation-apiblueprint, for rendering documentation in API Blueprint, which can then be directly used within Apiary’s platform. The module is optional, and definitely worth giving a try!

  • Docker support. A contributor provided Docker files for our skeleton that allow you to quickly launch Docker containers for both development and production!

  • Error handling. We had several issues pertaining to error handling that we resolved for this release.

    • In particular, we realized there’s a fundamental difference in error handling of controller exceptions vs MVC listener exceptions; the latter are never caught, which can lead to difficult to identify issues in your APIs. We now have an extension of the ZF2 Application class that wraps the route event in a try/catch block, ensuring your exceptions are handled gracefully by Apigility. If you wish to make use of this feature in your existing application, change the last line of your public/index.php to replace Zend\Mvc\Application with ZF\Apigility\Application.

    • Additionally, zf-api-problem was not properly casting exception codes that fell outside the HTTP status code range to valid HTTP status codes. It now casts these to status 500.

  • Content negotiation.

    • We now trim whitespace from JSON payloads to correct for some bad behavior on clients, ensuring JSON can be properly deserialized.

    • We now return 400 statuses for malformed multipart request bodies.

  • REST.

    • We now return a 400 status for invalid payloads for the various collection methods, as well as for invalid page values or page size values.

    • You can now return zf-hal Entity and Collection instances, allowing you to tailor them to your specific needs instead of relying on the default workflow.

  • RPC.

    • You can now specify RPC callbacks that are services in either the ControllerManager or ServiceManager.

  • Authentication.

    • The default zf-oauth2 configuration is merged with the user-specified API-specific configuration now, ensuring that all adapters work as they did pre-1.1.

    • We now use 401 and 403 status codes returned from oauth2-server-php.

    • You can now specify custom HTTP resolvers for your HTTP authentication via configuration.

    • zf-mvc-auth listeners are only attached during HTTP requests now.

    • We’ve fixed the content negotiation rules for the zf-oauth2 controller, ensuring it will respond correctly now based on requested mediatype.

On top of all this, we’ve also done a ton of work on the admin UI and API to fix reported issues.

We encourage you to read the full changelog to get an idea of fixes made. In particular, a number of fixes on the skeleton application will require you make changes to your application if you want to take advantage of them (e.g. Docker support, error handling, and separating your module list into a separate configuration).

One final note: the 1.2 series is the last series that will contain PHP 5.3 support.

If you are on PHP 5.3 or 5.4, you can install version 1.2.0 using our installer:

or via composer’s create-project command, using the version identifier:

Apigility 1.3.0

Apigility 1.3.0 has one fundamental change from 1.2.0: it drops support for PHP 5.3 and PHP 5.4, making PHP 5.5 the minimum supported version. This was done for two reasons:

  • Per the official PHP supported versions page, support for PHP 5.3 ended in July 2014, and PHP 5.4 support ends in September 2015; 5.4 is only receiving security fixes at this time. PHP 5.5 itself is no longer under active support, but will continue to receive security fixes until next year. It would be irresponsible to continue support for PHP versions that are no longer officially supported.
  • Zend Framework itself only supports PHP 5.5 starting with the 2.5 release of its components. For Apigility to continue to evolve with ZF2, it must adopt the same minimum requirements.

If you are already on PHP 5.5 or above, when you update, you’ll automatically get this latest version.

Summary

Apigility is continually evolving, and does so only with the help of contributors; many thanks to all who assisted with this release!

From here, we plan to work towards version 2, which will build on top of PSR-7 and the new ZF middleware component, Stratigility. Look for updates in the near future!