ZF Blog

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: 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":

Authentication choices

Authentication form

Authentication view

To use HTTP Basic authentication, you will need to create a htpasswd file, using Apache's htpasswd utility. When you add HTTP Basic authentication to your application, you will specify the location of the htpasswd file.

For HTTP Digest authentication, you will need to create a file with lines in the following format:

<username>:<realm>:<credentials>

The 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 appropriate realm, 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 password grant 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:

Authorization

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.

We highly recommend the combination of Apigility and ZfrCors when building web-based JavaScript applications that will operate on separate domains from your APIs.

Validation

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, zf-content-validation, which provides a validation engine based on Zend Framework's InputFilter 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:

Validation

For more information, view the demo video.

Future

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.

Updates

  • 2013-12-21 16:10 UTC: Fixed wget command and URI, per reports of errors in comments.

Return to entries

blog comments powered by Disqus