enunciate

articulate your web api.

Step 4 (Optional): Iterate

Even with no extra options or decorations, Enunciate does a pretty good job publishing your API. But there's so much more you can do with only a minimal amount of effort! Let's give our classes some extra love, then we'll talk about what we did:

src | |----enunciate.xml |----LICENSE.txt |----com | |----ifyouwannabecool | |----api | | | |----ExclusiveGroupException.java | |----SocialGroupService.java | |----package-info.java | |----PermissionDeniedException.java | |----PersonaService.java | |----domain | | | |----link | | | | | |----Link.java | | |----package-info.java | | |----SocialGroup.java | | | |----persona | | | |----Name.java | |----package-info.java | |----Persona.java | |----impl | |----SocialGroupServiceImpl.java |----PersonaServiceImpl.java
  • Add a SOAP API

    Adding a SOAP API is as simple as applying the JAX-WS @WebService annotation to our service interfaces and to our service implementations. (Note that per the JAX-WS specification, the implementation must reference the interface using the "endpointInterface" method on the annotation.) We also apply the @WebFault annotation to our exceptions so they'll be translated to the client correctly.

    There is, and always will be, debate around a SOAP API vs. a REST API. Whatever your opinion, there are advantages to defining a SOAP API, including the ability to define your API with a WSDL and provide a well-defined set of operations to your client. And when it's this easy to define a SOAP API, you may want to consider whether the advantages are worth it.

  • Removed the use of the default namespace

    It is considered a "best practice" to namespace-qualify your domain API. We did this with the use of the package-info.java files for the link API and the persona API. Namespace-qualifying your domain API ensures maximum compatability as the use of the default namespace is confusing to implementation vendors. It also provides a mechanism for versioning your API.

  • Add a splash package

    You'll notice we added a package-info file to the "com.ifyouwannabecool.api" package. This is where we added the introductory (i.e. "splash") documentation for our API. We want this documentation to show up on our index page for our documentation, so we specify this package as the splash packge in our configuration file. For more information, check out the user guide.

  • Documentation

    We've added javadocs to everything, including the endpoints, their methods and parameters, and the domain data. This documentation will show up in our generated documentation. You're free to use HTML tags as you want; they'll be applied in the resulting HTML. Javadoc block tags are recognized, but currently there is no support for javadoc inline tags (they'll show up unparsed in the documentation).

  • Specify a title and copyright

    We can specify a title and copyright to the generated documentation in the configuration file.

  • Add another file to download

    We want to be able to add a downloadable file to the documentation. In this case, we add the license file that governs the use of the API. This extra download is specified in the configuration file.

  • Specify the deployment configuration

    We specify our hostname ("www.ifyouwannabecool.com") and the context at which the app will be deployed ("api") in the configuration file. There are two advantages to this. (1) The generated WSDL will have an absolute reference to our SOAP endpoints, making the formal XML contract complete. (2) Consumers of our client code won't have to specify the URL of our endpoints if they don't want to.

  • Specify your namespace prefixes

    Again, done in the configuration file. Why would we want to do this? Just because we suffer from OCD and don't like the default "ns0", "ns1", etc. prefixes that are automatically assigned. It also gives a nice name to our wsdl and schema.

  • Change the package structure of the client-side classes

    Done (where else?) in the configuration file. This will distinguish the generated client classes from the original server-side classes. (Makes it easier to test, clearer that you're dealing with client-side classes, etc.)

And there are still a ton of other configuration options available to you as the API developer (which we won't go into here):

  • Specify your own CSS for the documentation, or even your own XSLT stylesheet if you don't like the structure.
  • Customize the web.xml file used to deploy your app.
  • Add AOP interceptors to your services.
  • Add your own API rules to be enforced at compile-time.
  • Etc.

Well, when we're done polishing things up, we enunciate our API again and deploy the war file as we did in steps 2 and 3. (Note that this time, we specify the config file on the command line.)

user@localhost>enunciate -f enunciate.xml -Espring.war.file ifyouwannabecool.war\ src/com/ifyouwannabecool/api/package-info.java\ src/com/ifyouwannabecool/api/ExclusiveGroupException.java\ src/com/ifyouwannabecool/api/PermissionDeniedException.java\ src/com/ifyouwannabecool/api/SocialGroupService.java\ src/com/ifyouwannabecool/api/PersonaService.java\ src/com/ifyouwannabecool/impl/PersonaServiceImpl.java\ src/com/ifyouwannabecool/impl/SocialGroupServiceImpl.java\ src/com/ifyouwannabecool/domain/persona/Name.java\ src/com/ifyouwannabecool/domain/persona/Persona.java\ src/com/ifyouwannabecool/domain/link/Link.java\ src/com/ifyouwannabecool/domain/link/SocialGroup.java

Step 5 (Optional): Behold the Glory >>

@SIDENAV@
@DONATIONS@