Apigility Version 1.0.0beta3

This is our third -- and likely last! -- beta release of Apigility! The features in this release are mainly around stabilization.

Deployment and Console

Most of the work we've performed since beta2 was on zf-deploy, our packaging/deployment tool. We made the following changes:

• First, the tool can now be used both within an application, as well as a
  standalone phar file. When used as a standalone phar
  file, you can now self update it with the self-update command; this will
  check https://packages.zendframework.com/ for any new versions, and, if found,
  do an "in-place" update of the tool. (Note: the library we use that provides
  this functionality often emits PHP fatal errors; in practice, however, we've
  noticed that the process works even when such errors are reported.)
• Second, we were not happy with the argument handling we were using, nor with
  the strong coupling of console argument parsing logic with the logic consuming
  the arguments. We built a small microframework around Zend\Console's
  RouteMatcher subcomponent that provides more flexibility around argument
  handling, and are now shipping this in the module
  zf-console.

In addition to these architectural changes, we also implemented two new features in the tool:

• You can specify a directory with the "local" configuration you want to use in
  the deployment package via the --configs argument.
• You can specify a directory containing the ZPK skeleton you wish to use when
  creating a ZPK (Zend Server deployment package); this directory should contain
  a deployment.xml and any scripts you will be using.

With these changes, we feel that zf-deploy is ready for inclusion in a stable Apigility release!

Documentation Updates

We've received a number of documentation improvements since beta2, and added a few documents as well.

In particular:

• An error was spotted in the "HAL for RPC services" recipe that made the code
  unusable.
• We've documented how to use the Zend Server SDK to deploy ZPK packages.
• We've added a recipe for adding Apigility modules to an existing Zend
  Framework 2 application.
• We've added documentation on the new zf-console module.

Beta3 Updates

In addition to the deployment and console tooling, we made the following changes:

• We updated the SendResponse listener in zf-api-problem to merge in any
  headers set in the application response object before sending the API Problem
  response. This ensures that any previously set headers are also set -- solving
  several issues observed when using third-party modules for Cross Origin
  Resource Sharing (CORS), as well as HTTP authentication.
• The storage adapters we ship with zf-oauth now both allow you to specify
  configuration via a storage_settings key; this change allows you to specify
  custom tables for both the PDO and Mongo adapters.
• We've updated the "api.enable" service to ensure it works with current
  versions of Apigility (and no longer raises errors!).
• We no longer display a resource class in the "Source Code" tab of a service if
  a corresponding class does not exist (e.g., DB-Connected resource classes are
  virtual services).
• We've added the option to recursively delete the directory for a service to
  the Admin API; the Admin UI now presents a checkbox with this option.
• We've added the option to delete an entire API. By default, this only removes
  the API's module from application configuration; however, you have the option
  to recursively delete the API module as well (once again presented in the
  Admin UI via a checkbox).
• We now generate factories for RPC controllers and REST resource classes when
  creating new services. This simplifies the story for dependency injection of
  these classes.

Roadmap

At this time, we feel Apigility has become very stable, and that we have addressed the most pressing usability issues. We anticipate issuing a stable release next week (week of 5 May 2014).

As noted in previous beta announcements, reaching stability is only the first step, however! Features such as "Doctrine-Connected", "Mongo-Connected", and "DB-Autodiscovery" REST services are already either implemented or will be soon, and we will be debuting these in a 1.1 version in the very near future.

Apigility Version 1.0.0beta2

Documentation

The primary goal of the beta phase for the Zend Framework team is documenting
the project. We've made enormous headway at this point, but we'll let you be
the judge of that; visit the documentation yourself!

Among topics covered:

• A "Getting Started" guide, and a companion, "REST Service Tutorial".
• An API Primer
• Chapters on Authentication/Authorization, Content Validation, and the
  Documentation features.
• A module-by-module reference guide, detailing configuration options.

New Features

While the beta cycle is primarily around stabilizing the API and Admin UI, we
decided one new feature warranted inclusion in version 1: a packaging/deployment
tool, zf-deploy.

This tool allows you to create packages from your Apigility -- or any ZF2
application -- for deployment. Formats supported include zip, tar, tgz, and zpk
(the Zend Server deployment package format). We plan to integrate support for
deploying zpk packages soon as well.

Beta2 Updates

Polishing, polishing, polishing was our mantra for beta2. This included
incorporating user feedback, but also scrutinizing the UI and code for
consistency issues.

UI Updates

Following beta1, we had a number of complaints about UI responsiveness,
particularly around the "Fields" screen. We did some analysis of the UI, and a
lot of work around dynamically loading and unloading DOM in the admin based on
what should be visible. As a result, we were able to significantly improve
responsiveness. There may be more work to do, but early reports indicate that
the changes make the Admin UI usable in situations that previously crashed the
browser.

In addition to the performance improvements, we made the following updates:

• On the "Authorizations" screen for each API, if no authentication is currently
  configured, we display a message to this effect, and link to the
  authentication screen. Unfortunately, in beta1, that link was invalid; we've
  fixed this.
• The "Fields" tab received a slight overhaul. We noticed that items with
  toggles displayed "Yes/No" terminology, but "On/Off" for the actual form
  input; these now use "Yes/No" verbiage consistently. The "Help" screen could
  not be dismissed with the <Esc> key; it now can. Previously, when hitting
  <Enter> from the "Create New Field" text input, it would raise the "Help"
  screen; it now properly creates the new field. The "Description" field was
  moved to the first option displayed for each field, to promote documentation
  of fields. We also added a "Validation Failure Message" field to allow
  specifying a unified error message on failed validation (vs. one or more per
  validator); we also ensured that "blanking" out the data in this field will
  remove any such message previously set. Finally, filters are now listed before
  validators, to signal the order in which validation operations occur
  (filtering/normalization occurs before validation).
• The "Source Code" tab was not properly generating links for files; we've fixed
  this in beta2.

Engine Updates

A few improvements were made to the API engine itself:

• The UnauthorizedListener registered by the zf-apigility module was not
  registering headers set by the zf-mvc-auth module, meaning that the
  WWW-Authenticate header was not propagating. This has been corrected.
• We modified ZF\ContentNegotiation\JsonModel to check for json_encode()
  errors, and to raise an exception when one is detected. This prevents
  situations where an empty response is returned on inability to serialize to
  JSON.
• zf-apigility-documentation-swagger was not returning a Content-Type header
  value of application/vnd.swagger+json; it now does.
• We fixed the bcrypt cost in zf-oauth2 to use the defaults from Zend\Crypt.
• We updated the OAuth2 database schema in zf-oauth2 to match that of the
  upstream oauth2-server-php package.
• We now inject the ZF\Rest\ResourceEvent with the current MVC request object;
  you can retrieve it from within your resource class using
  $this->getEvent()->getRequest(). This will give you access to HTTP request
  headers, query string arguments, etc.
• We no longer allow multiple "self" relational links in zf-hal.
• When specifying route parameters for a zf-hal metadata map, you can now use
  a PHP callable as the value; zf-hal will invoke that callable with the
  object for which a link is being generated in order to get the value for that
  route parameter. This is particularly useful for deterimining identifiers for
  parent resources.
• We moved the zf-apiglity-welcome requirement to be a development-only
  requirement.

Apigility Version 1.0.0beta

This is the first beta release for Apigility. From this point forward, we will
be keeping backwards compatibility between versions. New features will be
targetted for version 1.1.0, with bugfixes and security fixes targetted for the
upcoming stable release and any subsequent maintenance releases.

New Features

All Apigility modules were updated to use a PSR-4
structure and autoloader. This flattens the packages significantly, and also
allows simplification of the PHPUnit test runner. A PSR-4 variant of the ZF2
StandardAutoloader, ZF\Apigility\Autoloader, was created to provide true
PSR-4 autoloading, including the ability to have underscores (_) in class
names, which has been a common feature request. ZF2 Module classes created for
new API modules now use the new autoloader for loading classes inside the
module.

All modules were added to Travis-CI, giving us continuous integration going
forward.

With the release of Zend Framework 2.3.0, we were able to update the ZF2
dependency to remove the -dev stability marker; this also means that packages
should start to be smaller, as we'll be able to use distribution versions of ZF2
going forward instead of git clones.

Additionally, the following features were added:

• zfcampus/zf-content-validation#8 adds the ability to provide HTTP method-specific input
  filters. This feature is not yet integrated into the Apigility Admin UI, but
  can be configured manually. To do so, add method/input filter service name
  pairs for the given controller service name; if no method-specific input
  filter exists, zf-content-validation will fallback to the input_filter key,
  if defined. As an example:

  'zf-content-validation' => array(
  'Example\V1\Rest\Status\Controller' => array(
  // This is the fallback input filter, and the one the UI
  // can define and manipulate:
  'input_filter' => 'Example\V1\Rest\Status\Validator',
  // This one will be used on POST requests only:
  'POST' => 'Example\V1\Rest\Status\NewStatusValidator',
  ),
  ),

• zfcampus/zf-mvc-auth#20
  provides a patch that injects the MvcEvent with a new key,
  ZF\MvcAuth\Identity. You can pull the discovered identity from this event
  parameter now. Additionally, in REST resources, calling $this->getIdentity()
  will retrieve the identity.

• zfcampus/zf-apigility-admin#124 and
  zfcampus/zf-apigility-admin#129
  provide initial input filters for all Apigility Admin API services, as well as
  UI integration for reporting errors. All validation errors are caught and
  reported in a single dialog within the form that raises them.

• The 'edit settings' screen for REST services now allows editing the entity
  class and collection class names.

• The 'API Overview' page now links services to their overviews. The service
  description is displayed beneath each service; if not yet defined, a link to
  the 'edit documentation' tab for the service is provided.

• A new modal will be displayed to users of the Apigility Admin UI if the API
  detects that the filesystem is not writable. The modal details what changes
  need to be made in order for the UI and API to work correctly.

• zfcampus/zf-oauth2#30 splits
  out initialization of the oauth2-server-php server from the zf-oauth2
  controller, allowing the ability to replace it, write a delegator for it, etc.

Breaking Changes

• zfcampus/zf-content-validation#10
  changes the key used by the InputFilterAbstractServiceFactory from
  input_filters to input_filter_specs. This is due to the fact that ZF 2.3.0
  introduces an InputFilterManager, which is already consuming the key
  input_filters. Wrapped in this change is the fact that the
  InputFilterAbstractServiceFactory is now registered as an abstract service
  factory with the InputFilterManager, instead of with the application service
  manager instance.

  For those updating their Apigility libraries to 1.0.0beta1, edit your
  module.config.php files to rename the input_filters key to
  input_filter_specs.

• The zf-configuration controller ZF\Configuration\Controller was moved into
  zf-apigility-admin. This URI for the service remains the same, but the
  controller itself has moved. (This change was done to consolidate all Admin
  API controllers in the same module, as well as to reduce the dependencies
  needed in the zf-configuration component.)

Fixes

• zfcampus/zf-apigility-admin#115 - Ensures
  that non-SQLite PDO OAuth2 adapters may be provided without error.

• zfcampus/zf-apigility-admin#117 - Ensure
  that the route_match is passed to the API when saving an RPC service.

• zfcampus/zf-apigility-admin#118 - Ensure
  that the Content Negotiation selector is passed to the API correctly when
  saving an RPC service.

• zfcampus/zf-apigility-admin#120 - Remove
  duplicate call to initialize the ServerUrl helper.

• zfcampus/zf-apigility-admin#122 and
  zfcampus/zf-apigility-admin#123 - Add checks
  for array keys before accessing them when building the documentation graph for
  a given service operation.

• zfcampus/zf-apigility-admin#126 - Updates
  the admin to pass the X-UA-Compatible meta tag in order to provide Internet
  Explorer compatibility.

• zfcampus/zf-apigility-admin#132 - Ensures
  that authorization data is fetched each time a new service is created, a
  service is updated, or a service is deleted, ensuring the table reflects the
  current list of available services and HTTP methods.

• zfcampus/zf-apigility-admin#133 - Updates
  the 'angular-flash' functionality to anchor flash messages to the bottom of
  the window. Additionally, any error flash messages now have a 'close' button,
  requiring user intervention for dismissal.

• Many fixes were made to the UI to improve performance, remove UI refresh
  errors, provide more consistent color schemes, ensure tabs stay focussed
  between state transitions, etc.

• The Apigility Admin API was updated to break the authentication service into
  more granular sub-services, one for each type of authentication supported.
  This simplifies validation, and allows for future expansion.

• Work was done to ensure opcode cache detection is as solid as possible. We now
  properly distinguish between APC and APCu, allowing the latter to be enabled
  when using the Admin API.

• zf-apigility-documentation was not correctly aggregating RPC documentation;
  this has been fixed.

• We reviewed the various events triggered to ensure that they were happening in
  the correct order, which we defined as:

  • Authentication
  • HTTP method negotiation (is the method called allowed for the service?)
  • Authorization (is the discovered identity allowed to perform the requested
    action?)
  • Content Negotiation (determine incoming Content-Type and marshal data from
    request body; determine if Accept and/or Content-Type are valid for the
    request)
  • Content Validation

  Several event listener priorities were updated to fit the above requirements.
  A new listener, ZF\Rest\Listener\OptionsListener, was introduced to handle
  HTTP method negotiation for REST services, and is registered at the same
  priority as the RPC OptionsListener (which previously existed).

• zf-configuration was updated to never write configuration using short-array
  notation; this was done to ensure compatibility of generated configuration
  with PHP 5.3 (as developers may use the admin API via 5.4, but deploy to 5.3).

Apigility Version 0.9.1

Fixes two critical issues in authentication/authorization reported against
0.9.0:

• zfcampus/zfoauth2#27
  reported an inability to save OAuth2 adapter details from the Apigility admin
  UI. These are now corrected.
• A report on the apigility-users mailing
  list
  indicated that authorizations performed against REST entities were not working
  correctly. This was due to an incomplete change from "resource" to "entity"
  (as noted in the 0.9.0 release notes); the situation is now corrected.

Apigility Version 0.9.0

Adds ability to provide API documentation, completing planned features for the
1.0 stable release.

• Changes minimum supported PHP version to 5.3.23, in line with the upcoming
  ZF 2.3.0. We still recommend 5.4.8 for serving the admin user interface.

• New modules, zf-apigility-documentation and
  zf-apigility-documentation-swagger,
  providing documentation visualizations of APIs created with Apigility. The
  base module provides both JSON and HTML visualizations via the URI
  /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 /apigility/swagger.

  zf-apigility-documentation is enabled by default in zf-apigility-skeleton;
  zf-apigility-documentation-swagger is an opt-in module.

• The /admin and /welcome routes 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.

• A new module was created for Apigility-specific interfaces,
  zf-apigility-provider.
  The primary use case is for composition in modules that may or may not be
  consumed by Apigility (e.g., a general-purpose module that could be composed
  into many projects). The only interface currently is
  ZF\Apigility\Provider\ApigilityProviderInterface, which replaces
  Zend\Apigility\ApigilityModuleInterface (and thus prevents the necessity of
  installing all Apigility modules just to implement the interface!).

• A new module was introduced for handling development mode,
  zf-development-mode;
  this is a fork of NFDevelopmentMode,
  which was based off the equivalent functionality in zf-apigility-skeleton's
  Application module. We removed the functionality from the skeleton, and
  added a dependency on the new module.

• zf-apigility-skeleton's layout was updated to match that of the admin UI.

• zf-apigility-admin received numerous updates:

  • Ability to add documentation of services, fields, and operations.
  • Ability to use MongoDB when configuring an
    OAuth2 authentication adapter.
  • Ability to inspect, add, configure, and delete zf-content-negotiation
    selectors.
  • Links to HTML documentation of APIs managed by the Apigility instance
    (more on this below).
  • Ability to create and manipulate filter chains for each field in a
    service.
  • (Limited) detection of whether or not an opcode cache is enabled; if
    detected, a modal dialog will be presented to the end-user detailing how
    to disable it.
  • Completely overhauled and refactored admin UI application to ease
    maintenance and feature additions. The admin UI now uses
    Bower for managing UI asset dependencies, and
    Grunt for building the UI distribution. We have
    dropped ng-route for the angular-ui
    ui-router, providing us with
    more flexibility in UI implementation and layout. All services,
    controllers, and directives have been moved into their own files.
  • Countless UI/UX improvements.

• zf-apigility-welcome has been updated to use the Apigility "Rocket ElePHPant"
  logo for the splash screen, and to provide buttons to the HTML and Swagger
  documentation, if the appropriate modules are available.

• zf-rest and zf-rpc now each store a service_name key 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.

• All repositories have been updated to make a clean distinction between the
  terms "Entity", "Collection", and "Resource". An "Entity" is anything
  addressable via a URI containing a unique identifier. A "Collection" is any
  URI that returns a set of entities. A "Resource" refers to a URI that may
  return collections and/or entities. As such, we have several BC breaks:

  • The event renderResource is now renderEntity.
  • The event renderCollection.resource is now renderCollection.entity.
  • ZF\Hal\Resource was renamed to ZF\Hal\Entity.
  • The subkey resource in the zf-mvc-auth configuration is now entity.
  • The subkey resource_http_methods in zf-rest is now
    entity_http_methods.
  • The subkey resource_class in zf-rest is now entity_class.
  • The subkey resource_identifier_name in 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.)
  • The subkey identifier_name in zf-apigility db-connected configuration
    is now entity_identifier_name;

• zf-hal now properly differentiates between the identifier used in the route
  definition, and the identifier used for the entity; this allows you to use one
  value on the uri -- e.g., status_id -- and another in your entity class --
  e.g., id. zf-hal will fallback to the route_identifier_name if no
  entity_identifier_name is present.

• zf-apigility, when detecting an input filter is present, will pull values from
  the input filter, and not use any other values even if provided in the
  request. This prevents SQL errors due to unknown columns.

  Additionally, zf-apigility's assets were updated, and a Grunt + Bower
  toolchain provided for keeping them up-to-date.

• zf-rest, when detecting an input filter is present for the current request,
  will inject it into the ResourceEvent, allowing developers to retrieve it
  via $this->getEvent()->getInputFilter().

  Additionally, support for patchList was added to the
  AbstractResourceListener.

• zf-api-problem was updated to match Problem
  API draft 5.
  This has changed the internal structure and JSON representation of problem
  results. If you were manipulating ApiProblem objects directly previously,
  you may need to alter your code.

0.8.0

Adds content validation support.

• Ups minimum supported PHP version to 5.4.8.
• New module, zf-content-validation, which allows associating ZF2 input filters
  with named controller services, as well as creation of named input filters via
  a ZF2 abstract service factory. For requests with content, if the matched
  controller has an associated input filter, the data is passed to the input
  filter, and an error is returned on validation failure.
  • 422 responses are returned when validation fails.
  • 400 responses are returned when the content contains unrecognized data.
• Admin UI now adds an "Inputs" tab to each service, allowing the user to create
  and edit inputs for the service, as well as associate validators.
• Hydrators are now specified via a dropdown, populated from a list of known
  hydrator services in the application.
  • The ArraySerializable hydrator is now specified as the default hydrator for
    REST entity objects.
• The AbstractResourceListener now correctly pulls any whitelisted query string
  variables and passes them to the fetchAll() method.
• You may now specify the default version to use when no version is specified
  (previously, hard-coded to use version 1 as the default version).
• The Admin API will now report an error if you attempt to create a new API and
  a matching module name already exists.
• All Apigility modules now use "next significant release" notation in their
  composer.json files to ensure the latest stable version or development
  version will be selected (vs only the latest development version).
• All Apigility modules have been updated to ensure they are compatible with
  Cross Origin Resource Sharing (CORS) requests.
• Tables used with DB-Connected REST resources can now contain underscores in
  their names.
• Content negotiation now detects JSON decoding errors and raises an exception
  when detected.
• Composed ZF\Hal\Link\Link properties in objects rendered as HAl will be
  rendered as relational links.
• The collection name of a HAL collection can now be specified in HAL metadata
  configuration.
• OAuth2 support has been improved to allow better integration between ZF2 and
  oauth2-server-php request objects, and to allow the password grant type.

0.7.0

Release binaries that include all dependencies, and with development mode enabled.

0.6.0

Initial public release