Skip navigation
1 2 Previous Next


17 posts

Over at FamilySearch, I've been involved in supporting Flash application development that consumes a public POX API. It's not a REST API, but like REST, we provide a set of resources that are accessible at a given URI. Up to this point, our Flash developers have been stuck with parsing the resources as XML. It works fine, but it's not without a significant overhead. XML isn't the most efficient data format, nor is it very convenient to work with in ActionScript code.

The "native" data format for flash development is AMF. When ActionScript objects get written to a stream, they are serialized as AMF. When the objects are read from a stream, AMF is the presumed deserialization format. The Enunciate project has provided support for supplying SOAP endpoints as AMF services for quite some time now, but I've only recently added support for AMF REST endpoints.

Here's the wrap-up of the process. As mentioned in the article, if you're already using Enunciate, this process will be significantly simpler. Enunciate already comes with a JAX-RS provider that does the serialization and it will generate your client-side ActionScript classes for you. Not to mention the fact that Enunciate will also generate documentation for your API and neatly package it up, ready to be deployed into your favorite servlet container.

So you've got your JAX-WS or JAX-RS endpoints defined and implemented, and they're compiling, building and running smooth on your server. All is well, right? You've been diligent in documenting and testing your code, and the consumers of your API seem to be happy.

Well, that's just because they don't know what they're missing.

Here's the thing: your Web service API could be so much better. What if you could leverage all that work you've put into your JavaDocs and publish that as documentation for your API? And what if you could provide fully-documented, well-formated, strongly-typed client-side code for your .NET, Java, or ActionScript clients?

With just some enhancements to your build file or your POM, you can produce stuff that looks like thisfor your Web service API.

Let's say you're using Maven to build your project. Just use the Maven Enunciate Plugin to export your own docs to thetarget/docs directory:


Or if you're using Ant, you can do the same thing with something like this:

<enunciate basedir="src/main/java">
  <include name="**/*.java"/>
  <classpath refid="enunciate.classpath"/>
  <export artifactId="docs" destination="target/docs"/>

That's it. Try it out. Check out the Enunciate documentation to learn more.

As of version 1.10, Enunciate will generate elegant client-side C# code and supply an AMF provider for your REST endpoints.

There is also a new Maven plugin that can be used to generate just the user documentation and client-side classes for your JAX-WS and JAX-RS endpoints. If you're using JAX-WS or JAX-RS, you ought to try it out and witness the value-add for yourself.


Enunciate 1.9 Released Blog

Posted by stoicflame Jan 22, 2009

Enunciate 1.9 provides support for JAX-WS RI and CXF and generates a lightweight JAX-WS client-side library for accessing the endpoints.

For more information on how to use CXF with Enunciate:

Enunciate 1.8 was recently released with support for JAX-RS annotations. This means that Enunciate will now be able to process your Web service API as defined by JAX-WS (for SOAP endpoints) and JAX-RS (for REST endpoints). If you already have your endpoints defined via JAX-WS and/or JAX-RS, it might be a good time to check out the additional features that Enunciate can provide.

  • Full User Documentation
    Enunciate will generate nice HTML documentation for your Web service API, scraped from the JavaDocs.
  • Client-Side Code
    The documentation will have links to download client-side code that Enunciate generated to be able to invoke your service operations via the Web service API.
  • WSDLs, Schemas, etc.
    The WSDLs and Schemas were generated by Enunciate from the source code, so they're consolidated, well-formatted, and documented.
  • Additional Endpoints
    Enunciate will publish your JAX-WS endpoints as GWT RPC endpoints and AMF endpoints (for Flex clients)

Enunciate 1.8 also added support for GWT 1.5 and a hefty set of bug fixes and minor enhancements


OAuth is Handy Blog

Posted by stoicflame May 16, 2008

OAuth for Spring Security was released this week, and I thought I'd take a stab at why you might be interested.

What is OAuth?

I like to explain OAuth by describing the problem it is trying to solve. So here goes.

Let's say you're a sizeable social networking site and you'd like to offer a feature to your users to allow them to search their webmail contacts for import into their social network. The problem is, you (the "consumer") need access to a resource that is protected by a another site (a.k.a. "service provider"). How do you go about doing that?

Option 1: Just ask the user for his/her credentials and promise that you won't store them or do anything bad with them. Well, it works, I suppose, but this isn't a great general-purpose practice for online applications. And it's not hard to see why. Sure, you might be trustworthy, but there are plenty of other sites who are not. And what about the service provider? How would you feel about your users giving out their credentials to other sites that want access to the resources you protect?

Option 2: Use OAuth. OAuth is a protocol that was defined to address this problem. Continuing the above example, let's say that you've established a trust with the webmail service providers. You share a "secret" (which in practical terms is a passphrase or a public key or something) that you can use to gain access to the webmail contacts—provided, of course, that the user approves it. In order to gain this approval, all you have to do is redirect the user to the login page of the webmail service provider and have the user tell the service provider that it's okay that you access his/her contacts.

OAuth is a protocol standard that can be used to enable this mechanism.

How do I try it out?

OAuth for Spring Security has a really nice tutorial that walks you through setting up both a service provider and a consumer on your local box. Once those are set up, you can see OAuth in action by walking through the user flow.

How do learn more?

Enunciate 1.7 has been released!

The primary feature of Enunciate 1.7 is support for securing your Web service endpoints using Spring Security. There is additional support for OAuth, with OpenID and WS-Security planned for 1.8.

In addition, Enunciate 1.7 introduces the concept of custom REST content types, which you can use to support custom serialization formats for REST responses (beyond the default XML and JSON endpoints).


The first part of this tutorial walked through the development of a Web service API that exposes its endpoints via SOAP, REST/XML, JSON, GWT-RPC, and AMF. In this second part of the tutorial, we intend to prove out this API. We will walk through building a rich AJAX application with an embedded Flash component. The AJAX application will use GWT-RPC to access the API while the Flash movie will use AMF.

For those of you who would like to see the example code on your local filesystem, you can check it out of SVN at

Step 1: Set up the GWT application.

We first have to create our GWT application. We will use the name

So you've got a web application that needs to expose a Web service API. Maybe you're going to be writing a Rich Internet Application (RIA) using Flex or some AJAX Framework. Or maybe you'll be developing a desktop application that needs to interface with your online data. Or perhaps you've got a few business partners that want to integrate with your application.

Whatever the reason, you need a solution that not only fits your client-side requirements, but one that is also easy to develop, easy to debug, easy to maintain, and easy to enhance. Don't be too hasty with your choice of a Web service implementation technology.REST is not always the best answer. It might be, but not always. Take some time to research your needs, gather your requirements, and look at other remoting technologies that are available. Then decide what you need.

This is the first part of a tutorial will walk you through developing a Web service API that could meet the requirements of all of the above-mentioned use cases. For the sake of clarity and brevity, we'll keep the operations simple, but by the time we're done, we'll have a fully-functional Web service API that exposes a bouquet of endpoints: SOAP, REST/XML, JSON, GWT-RPC, and even AMF (for all you Flex developers). In Part II of this tutorial, we'll prove out the Web service API by building a rich AJAX application with an embedded Flash component that accesses it.

By the end of this two-part tutorial, we'll have established a good custom-fit Web service development process for maintaining your Web service API in your favorite development environment.

For those of you who would like to see the example code on your local filesystem, you can check it out of SVN at

Step 1: Create Your Project

We will be exposing a Web service API for an address book application. We will be using Maven 2 and Enunciate 1.6 to build and package our application. (Note that we could also use Ant to build the application, but Maven will get us started more quickly.)

We'll label our application

If you haven't checked out the Enunciate project recently, you may want to give it another look to see how it can improve the development, deployment, and consumption of your Web service API.

Enunciate 1.6 was just released with support for mounting your JAX-WS endpoint classes via AMF (thanks to Adobe's release of BlazeDS). This should be really interesting to Flex developers. Not only will you be able to make Web service calls via AMF, but Enunciate will also generate type-safe client-side ActionScript classes that will access those endpoints.

Enunciate will also publish your endpoints via SOAP, REST/XML, JSON, and GWT. You'll also get your WSDLs, schemas, and full user-level documentation of your Web service API.

I'll be shortly posting a two-part tutorial on how to publish this kind of a rich API with your service endpoints and how to write an AJAX app with an embedded Flash component that consumes it.


Enunciate 1.5 Released Blog

Posted by stoicflame Oct 21, 2007

Enunciate 1.5 makes some dramatic improvements in the GWT application development experience. Included in the distribution bundle is a new pet clinic sample application that will demonstrate how to publish the pet clinic Web service API and how to develop a nice AJAX app for the pet clinic using GWT.

The honeymoon with RESTful Web services is over. Now that we've had some time to get over the infatuation, let's take a fresh look at the principles of sound Web service API design. Despite how rocky our relationship with SOAP has been, it's time to confront our prejudices and accept both technologies for their virtues and vices.

In fact, I propose we give this discussion a new identity in order to help us put the painful memories, bitter tears, and long, sleepless nights behind us. Because it's not really about REST vs. SOAP anymore, is it? A well-designed Web service API is so much more important than the technology we use to implement it. So after we get past the name-calling and mud slinging, what we're left with is a set of fundamental architectural principles for Web service API design.

On the REST side of the playing field we have engineers who have a set of well-defined resources that they want to make available by defining a constrained set of basic operations that can be applied. On the other side, we have engineers whose operations are much more complex, maybe contextual, and perhaps interdependent. These engineers may or may not have a well-defined set of resources to which these operations apply. Rather than making a set ofresources available, these engineers have a set ofservices they want to make available.

So on one end of the spectrum we have the need to design a Resource-Oriented Interface (ROI). On the other end, we have the need to design a Service-Oriented Interface (SOI).

Determining what kind of an API is to be published should be thefirst step in designing a good Web service API. And, trust me, it's not always easy to determine where your API fits. You may, for example, have a well-defined set of Gismo objects to which you can limit your operations to be create, read, update, and delete. But what if you want to provide a search operation for Gismos? In this case, the boundaries of the resource and the operation are less clear.

In any case, you will be able to make a much better choice of a development technology if you can first define whether your API is more Resource-Oriented or Service-Oriented. (By the way, it'll probably fit somewhere in between.) Choosing the development technology first is letting the tail wag the dog.

Still unconvinced? May I suggest that you subscribe to one or more of the common misconceptions about the current state of Web service development? Let's debunk those right now, shall we?

  1. It is not easier to design a good Resource-Oriented Interface (think "REST") than it is to design a good Service-Oriented Interface. Actually, I'd suggest that for most engineers, an SOI is more intuitive than a ROI.
  2. It is not easier to implement an ROI than it is to implement an SOI. In fact, the tools these days are much more mature for SOI. I've found that ROI developers often have to work directly with low-level protocol APIs, although that's changing fast.
  3. It is not easier to consume an ROI than it is to consume an SOI. Which type of interface is easier to consume always depends on the platform of the consumers. Are they using a high-level, compiled programming language or are they in looser, more interpreted environment?
  4. An SOI is not any less interoperable than an ROI.I'm going to assert that we've pretty much solved the issue of interoperability. I'm sure there are many of you who might disagree. Bring it on.
  5. SOAP is not the only technology for implementing an SOI. Really. Just because you have a more service-oriented API doesn't mean you have to use SOAP. (Really? Whew!)
  6. ROI is not always the best choice for supporting RIAs. Many AJAX frameworks (e.g. GWT) have their own RPC mechanisms that are much more SOI than they are ROI. Another example for Flash is AMF.

So what do you think? I say let's adopt a rational, reasonable approach to Web service API design and stop letting the tail wag the dog.

When you use Enunciate 1.4 to publish your Web service API, Enunciate will build you a war that you can drop into your favorite webapp container. The war will supply any or all of the following, depending on your configuration:

  • Full documentation (scraped from the JavaDocs)
  • Your service beans mounted via SOAP, along with the formal contract (WSDL, schemas, etc.)
  • Those same service beans mounted via REST/XML.
  • Those same service beans mounted via JSON.
  • Those same service beans mounted as GWT-RPC endpoints.
  • Client-side libraries for download (used for invoking your API programatically via SOAP).
  • Client-side GWT Java libraries that can be used with GWT to support an AJAX app.
  • Etc.

If you want to know more, I suggest a quick walk through the getting started guide.


Enunciate 1.3 Released Blog

Posted by stoicflame Aug 23, 2007
Enunciate 1.3 includes support for applying aspects to service beans, customization of endpoint URLs, and many bug fixes and minor enhancements. See therelease notes for details.  

Enunciate 1.2 Released Blog

Posted by stoicflame May 30, 2007
Maps and support for type adapters were the two features most requested from those using Enunciate (and the two features that most often precluded more use from those wanting to use Enunciate). Of course, the release includes numerous bug fixes and some user experience enhancements.