We are pleased to announce the immediate availability
of Apigility 1.0.0beta1!
http://apigility.org/download
This is our first beta release of Apigility, marking its initial API
stability, and providing a solid preview of what to expect for the first
stable release.
What is Apigility?
Apigility is the world's easiest way to create and provide secure, well-formed
APIs.
Apigility provides tools for describing and documenting your APIs, both
RESTful and RPC. You can indicate the URL that provides a service, what
HTTP methods are allowed, what representations (e.g., JSON, HTML, XML)
can be provided, how many items to present per page of a collection, and
more.
We make choices so you don't have to. We have standardized on
JSON for RPC services, and Hypermedia Application Language (HAL),
using the JSON variant, for REST services. We provide robust error handling,
using Problem Details for HTTP APIs (API Problem).
HTTP method negotiation and content negotiation are built in, ensuring that
problems are reported early and provide detail on how to submit correct
requests.
You can document what fields can be submitted, and configure how those
fields will be validated. You can indicate what services require an
authenticated user - or even restrict usage based on the HTTP method!
You can configure how users can authenticate, and we provide HTTP Basic,
HTTP Digest, and OAuth2 authentication out-of-the-box.
An API is only as useful as its documentation. Apigility lets you document
every service, every HTTP method, and even differentiate between collections
and entities. We provide both HTML and JSON documentation by default, and
have a separate Swagger UI
implementation you can opt-in to if desired. Alternately, you can write your
own module for exporting the documentation in your own custom format -
we hope to provide both API Blueprint and RAML in the future!
You can use the full Apigility skeleton to create APIs, and the Admin UI
for manipulating them. Alternately, you can opt-in to just the modules you
are interested in, and configure them by hand for optimal control over how
they all work and interact.
In short, Apigility is the most powerful tool you can use for creating
robust APIs.
New Website!
First in our line of announcements,
Enrico Zimuel has completely rewritten the
Apigility website to provide more
content and a more modern look!
What has changed for beta1?
In the three weeks since we released 0.9.1, we've been quite busy. Among other
things, we worked hard to stabilize and release Zend Framework 2.3.0, which
allows us to now pin Apigility to a stable version of the framework. This has
reduced the package size from over 100MB to around 20MB - a reduction of 80%!
Additionally, we've worked hard to fix a number of lingering issues in an
effort to stabilize the Apigility engine and streamline the Admin UI
experience. The following is a list of changes.
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.
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:
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).
Roadmap
We're excited to get a stable release of Apigility as soon as we possibly
can. To that end, we plan to do a beta release weekly until it's ready.
During that time, we will be working primarily on documentation and critical
bugfixes. We hope to have a stable release within a month.
Reaching stability is only the first step, however! We already have contributors
making significant headway on features such as "Doctrine-Connected" and
"Mongo-Connected" REST services, and we will be debuting these in a 1.1 version
not long after we reach version 1.0. Stay tuned!