Tip of the Iceberg

Thus far, we've only looked at the "back end" code that can be used within an XPage to register and authenticate users. So let's finish off by exploring how all the concepts this article has discussed can come together to create a fully functional application API.

The following is the entire source XML of registerUser.xsp:

The first characteristic of this element that is atypical for an XPage is the rendered attribute of the UIViewRoot node: by setting it to false, we tell Domino not to send any markup of its own. This allows us to "print" to the browser only the specific data that we want to send. Since we are surfacing an API to consumer applications that will provide its own visual representation of the data, we can send just the data with no visual characteristics of our own. We do that using the sendJson method of our base API class:

This method obtains a handle on the servlet response, which allows us to not only write our desired content directly to the consumer, but also to set the content type of the response and set a header that prevents caching, just in case the consumer would otherwise choose to cache the response.

We use the afterPageLoad event of the XPage to call this method, but before doing so, we use the native importPackage function of SSJS to allow us to use an abbreviated syntax. Since all SSJS code is ultimately interpreted by Java at runtime, we would normally have to use the full Java namespace (com.puncrock.api.API.sendJson) to allow the runtime to load the correct method; importPackage provides the class loader a shortcut for finding the method, so as long as we haven't defined any conflicting variables, we can simply call API.sendJson() and the correct code will be executed.

The registerUser method returns an instance of a UserRegistration class. We've previously examined its register method; let's take a look now at its toJson method:

This method uses the org.json package, which can be downloaded from (as you might expect) json.org. Although the XPage runtime automatically includes multiple packages for generating JSON, when generating – and parsing – basic JSON structures, the org.json package is far simpler to use, as the above example illustrates.

If the registration request succeeded, the consumer will receive the following response:

{"success":true}

If the request was unsuccessful, however, the response will be similar to the following:

{"success":false, "error":"User Id timtripcony already exists"}

Either response provides the consumer all of the information it needs to provide appropriate feedback to the user.

The source of getToken.xsp is quite similar:

Once again, we block the default rendering of the page, and in its place, send back a JSON response – this time, by calling an almost identical toJson method of the TokenRequest class we examined earlier:

This time, if a valid user ID was provided, the consumer should receive a response similar to the following:

{"token":"AEB5929ED34F602FD98DB7917098AC5B"}

Finally, let's allow a user to actually do something in our application. To be precise, let's allow a user to store their current GPS position in their account record. So we'll create setUserLocation.xsp:

This page calls the setUserLocation method of our base API class, and passes it several request parameters, including the API key that should identify a valid user:

Because this is the longest single block of code we've yet seen, but also because it finally demonstrates a real use case for this authentication technique, let's examine it in excruciating detail.

1. We create an empty JSON object that will be sent back to the consumer to notify the user of the result of the attempted operation.

2. We call the getUserId method we examined earlier, passing it the API key received with the request. If the key is expired – or was never valid – we update the JSON object to convey that the operation was not successful because the user is not authenticated. This provides the consumer an opportunity to request a new token and try the same operation again.

3. If, however, the key we received was valid, we now know the user ID associated with the token used to generate the key. We can, therefore, rapidly obtain a handle on their account record.

4. Having now located their account record, we write the latitude and longitude data received with the API request and save the record.

5. Finally, we update the JSON object to convey that the operation was successful.

Expanding on this basic premise would allow your service to do more interesting things: instead of just storing the user's current location by overwriting item values in their account record, you could create a separate "check-in" document each time, storing the user ID, location data, and current date-time. This might allow consumer applications to display a chronological map of a user's travels, perhaps even calculate patterns of changes in physical distance between members of a given social circle.

What is significant about this example is not what is done with the data that was submitted to the application; rather, the most pertinent facet of the above method is how the application is determining whether the data should be accepted in the first place – and if so, on whose behalf.