enunciate

articulate your web api.

Step 1: Write The Code

We'll start by defining the domain of our app. We'll define a persona with an id, an alias, an email address, a name, and a picture. The name is a complex structure, made up of a given name and a surname. We'll also define a link between two personas and a social group consisting of an id, a group leader, the group members, and whether the group is exclusive.

Next, we'll define the services available for our domain data. The PersonaService will define the operations available on a persona. This includes operations for reading a persona, storing a persona, and deleting a persona. The SocialGroupService will carry the operations that deal with linking and grouping personas. These operations include creating a link between two personas, creating a social group, adding someone to a social group, and reading the social groups of a given persona.

We also define the possible exceptions that can get thrown, including a PermissionDeniedException when trying to create a link between two people, and an ExclusiveGroupException when trying to add a persona to an exclusive group.

After having defined our service interfaces, we create our implementation classes, PersonaServiceImpl and SocialGroupServiceImpl.

Apply the Metadata

In order for our code to be identified as a Web service API, we need to apply some metadata in the form of Java annotations. We'll start by defining an XML REST API using JAX-RS annotations. Our objects will be converted to XML using JAXB.

A JAX-RS endpoint is identified by mapping it's implementation to an URI path using the @javax.ws.rs.Path annotation. We'll apply the PersonaServiceImpl endpoint implementation to the "/persona" path and the SocialGroupServiceImpl to the "/group" path.

Then, using JAX-RS, we map each method to an HTTP operation and, optionally, to a subpath. We decide to apply method metadata on the interface that defines the method. (Note that using interfaces isn't strictly necessary, but it may be convenient to do so if and/or when we apply some AOP or dependency injection.)

So for the PersonaService, we will use an HTTP GET to access the "readPersona" method and will pass in the persona id as a parameter on the path. We will use an HTTP POST operation to store a new persona, and an HTTP DELETE method to delete a person.

Then, for the SocialGroupService, we will use an HTTP GET to access the "readGroup" method and will pass in the group id as a parameter on the path. To store a new group, we will use the HTTP POST method and pass in the parameters as HTTP query parameters. To add a persona to a group, we'll use a POST to the group path and pass in the persona id as a query parameter.

Because we're returning objects from a few of our REST API calls, we need to also apply the @XmlRootElement annotation so that JAXB will know how to write out the root of our XML tree.

So, we've got our domain defined along with some services that operate on the domain. The source code structure looks like this:

src | |----com | |----ifyouwannabecool | |----api | | | |----ExclusiveGroupException.java | |----SocialGroupService.java | |----PermissionDeniedException.java | |----PersonaService.java | |----domain | | | |----link | | | | | |----Link.java | | |----SocialGroup.java | | | |----persona | | | |----Name.java | |----Persona.java | |----impl | |----SocialGroupServiceImpl.java |----PersonaServiceImpl.java

Step 2: Enunciate the API >>

@SIDENAV@
@DONATIONS@