Apigility 0.8.0 Released!
Today, we're releasing version 0.8.0 of Apigility! You can grab and test it using one of the following two methods:
composer create-project zfcampus/zf-apigility-skeleton apigility
- Manual download:
wget https://github.com/zfcampus/zf-apigility-skeleton/releases/download/0.8.0/zf-apigility-skeleton-0.8.0.zip unzip zf-apigility-skeleton-0.8.0.zip
We never announced our 0.7.0 version (though we showed off the features at several conferences this past month), so there's a ton to announce!
Authentication and Authorization
Authentication and Authorization were the number one requested feature after our original release announcement at ZendCon 2013. We managed to get this in place in time for ZendCon 2013 Europe, and the features include:
- Ability to use HTTP Basic or Digest authentication, or OAuth2.
- Ability to create authorization rules per HTTP method, per service in your API.
We are leveraging Zend Framework 2's
Zend\Authentication library for HTTP
authentication, and Brent Shaffer's oauth2-server-php
library for OAuth2.
Apigility allows you to define one authentication scheme per application. You can set the authentication details on the main dashboard, under the heading "Authentication":
To use HTTP Basic authentication, you will need to create a
htpasswd utility. When you add HTTP Basic authentication to
your application, you will specify the location of the
For HTTP Digest authentication, you will need to create a file with lines in the following format:
credentials field must be an MD5 hash of the password that will be
accepted. When adding the HTTP Digest authentication to your application, you
will specify the location of this file, and will also need to specify the
nonce\_timeout (number of seconds the credentials remain
valid), and, optionally, a list of
digest_domains (the domains for which the
same authentication information is valid).
To use OAuth2 authentication, you will need to setup a database, and add clients
and optionally users (users are only necessary if using the
type). See the zf-oauth2 README for
details on how to setup the database and seed it.
Once you have authentication setup, you can start setting up authorization restrictions on your API. To do this, navigate to the "Authorization" menu item in any API:
By default, APIs created with Apigility are public. To require authorization on specific services or specific HTTP methods of services, check the appropriate boxes and save your changes. From that point forward, authentication will be required for those actions!
For more information, view the demo video
Cross Origin Resource Sharing
In order to operate a web-based application that interact with your APIs, you
may need to investigate Cross Origin Resource Sharing (CORS). CORS describes
HTTP requests for HTTP resources made from a different domain than the resource
exists on. As an example, if your API is at
http://example.com/api/, but you
want to request it from
http://my-uber-cool-app.com/, CORS is in effect.
If a browser attempts to create an
XMLHttpRequest to a different domain than
the current page, then it will detect a CORS request. At that point, the browser
will ask the server with the resource if the request is allowed; if the
originating server does not reply with the appropriate headers, the browser will
not submit the original request, and the
XMLHttpRequest will fail.
Apigility does not deal with CORS by default, but the 0.8.0 release includes changes that ensure that CORS requests can be honored if you are using a CORS plugin. We have tested against the ZfrCors ZF2 module, and it works seamlessly with Apigility at this point.
Another aspect of API security is validating the incoming input. Ideally, you should reject anything that does not validate outright, and as early as possible.
0.8.0 adds a new module,
which provides a validation engine based on Zend Framework's
component. This component, when a request method that contains incoming data
occurs, checks to see if the matched service has a corresponding input filter,
and, if so, attempts to validate the incoming data against it. If the validation
fails, an error response is immediately returned.
In the Apigility Admin UI, each service now has an "Inputs" tab that allows you to define the input filter. In this tab, you define inputs, which correspond to each field of data you will be expecting. For each input, you can define one or more validators, along with any configuration you want for each. In this case, a picture is probably more sufficient:
For more information, view the demo video.
At this point, we're wrapping up the featureset for a stable version of Apigility. The last milestones we have include:
- a module for generating API documentation. At this time, we are favoring API Blueprint as the markup is trivial to generate from our configuration, and, being markdown-derived, relatively easy to edit and expand once the initial generation is complete.
- some cleanup of the UI, including some long-overdue refactoring and formalized testing.
- documentation of the various components, as well as tutorials on how they all fit together.
We hope to complete the API documentation milestone in the first weeks of 2014. At that point, we will start the beta release cycle, spending that time to do the UI refactoring and project documentation. Once those are complete, we'll finally issue a stable release; we're aiming for late February 2014 at this time.
- 2013-12-21 16:10 UTC: Fixed
wgetcommand and URI, per reports of errors in comments.