Today, we're releasing version 0.9.0 of Apigility! You can grab and test it using one of the following two methods:
composer create-project zfcampus/zf-apigility-skeleton apigility 0.9.0
This release brings in our last planned feature for the upcoming 1.0.0 stable release: the ability to document your APIs, and then provide that documentation to your end-users!
An API is useless without documentation.
The Apigility admin UI now allows you to capture narrative documentation for your services, collections, entities, and operations. You can document what the request and response bodies should look like. You can document each field you configure.
Apigility then merges this documentation with what it knows of your services: what Accept headers are allowed, what Content-Types are allowed, what response status codes may be expected, what fields are available, whether or not authorization is required, and more. The admin UI provides a visualization of this information for you.
We provide several more visualizations, too. The zf-apigility-documentation module is enabled now by default in the zf-apigility-skeleton, providing both JSON and HTML representations of the documentation at the URI /apigility/documentation (the representation will depend on the Accept header value you provide -- Apigility's own content negotiation at work!).
You can also opt in to the new zf-apigility-documentation-swagger module, which will allow you to either seed an existing Swagger UI installation, or, if you visit the /apigility/swagger URI, provide the Swagger UI itself.
To see what's possible, Introduction to Documentation video on the Apigility website!
If you are already using Apigility, you will need to add the new modules to your application. Add the following dependencies to your composer.json:
After running composer update, add the modules to your
This release has been a little over two months in the making, and has a ton of changes. The following is a list of important changes for existing users.
/apigility/documentation, based on the Accept header value present. zf-apigility-documentation-swagger provides an additional JSON visualization for the mediatype
application/vnd.swagger+json, for seeding a Swagger UI installation; additionally, it provides the Swagger UI via
zf-apigility-documentation is enabled by default in zf-apigility-skeleton; zf-apigility-documentation-swagger is an opt-in module.
/welcomeroutes are now removed! The admin UI now uses
/apigility/ui, and the welcome screen uses
/apigility/welcome. New routes for documentation are also available, as detailed above.
ZF\Apigility\Provider\ApigilityProviderInterface, which replaces
Zend\Apigility\ApigilityModuleInterface(and thus prevents the necessity of installing all Apigility modules just to implement the interface!).
Applicationmodule. We removed the functionality from the skeleton, and added a dependency on the new module.
service_namekey in the configuration for each service. While efforts have been made to ensure existing configuration still works, we recommend adding this key to each service. The value should be the short name representation for the service, usually the name you provided when creating the service.
ZF\Hal\Resourcewas renamed to
resourcein the zf-mvc-auth configuration is now
resource_http_methodsin zf-rest is now
resource_classin zf-rest is now
resource_identifier_namein zf-rest is now
entity_identifier_name. (This change only affects those who have been using latest master, but have not updated since late-January 2014.)
db-connectedconfiguration is now
status_id-- and another in your entity class -- e.g.,
id. zf-hal will fallback to the
Additionally, zf-apigility's assets were updated, and a Grunt + Bower toolchain provided for keeping them up-to-date.
ResourceEvent, allowing developers to retrieve it via
Additionally, support for
patchList was added to the
ApiProblemobjects directly previously, you may need to alter your code.
At this point, we turn our attention to stabilizing Zend Framework 2.3.0, on which Apigility will depend, due to features added to that upcoming version.
Once Zend Framework 2.3.0 is released, we will begin the beta cycle for Apigility 1.0.0. During that timeframe, we will due some additional improvements to the UI, and work to ensure the engine is stable. Additionally, we will document the project, providing documentation for each module, as well as for how the modules work together as a whole. We hope to provide "recipes" for a number of common practices and development and deployment situations.
Subscribe to this blog via RSS.