I've recently been exploring the RESTful web services aspect of APEX and decided to build a small to-do list application to demonstrate how it works. Some knowledge of REST standards is required if you are thinking of diving in. I wont cover that here in detail, but there are plenty of online resources available on REST. I can also recommend the excellent REST in Practice by O'Reilly. A great book that explores REST, HATEOAS (Hypermedia as the Engine of Application State) and the concept of the Internet as one large state machine.

One thing I wont be covering in this post is the authentication methods that are available in APEX. I'll be covering this in a follow up post using OAuth 2 as the authentication mechanism.

The first thing to do in APEX is to make sure your REST service is enabled and that the path prefix is set as appropriate. The path prefix will default to your workspace name, so you don't have to change it.

workspace_prefs

Now let's go and configure a REST API module. Firstly, lets think about what might be required for a basic to-do app.

  • Get a list of to-do items.
  • Create a new to-do item.
  • Delete a to-do item.
  • Update a to-do item as done/not done.

From this I can identify the following URI templates that will be used to identify a specific to-do item, a list of to-do items or a new to-do item.

  • items/{ID} (a single to-do item)
  • items (a list of to-do items, new to-do item)

This is how my REST module looks in APEX.

rest_module

I have given the module a URI prefix of todo/ in order to identify the all URIs as being a part of my to-do application. Pagination has been set to 5, meaning that only 5 to-do items will be sent back with each response.

In the left hand section, 2 different URI templates can be seen under my module next to the green cogs and within these are handlers identified by the method or verb that will be used in a HTTP request.

Let's drill into one of those handlers.

post_handler

This handler defines an UPDATE statement that is executed when a request is made using a POST method. The :ID is a parameter supplied as part of the URL path, whereas :done is extracted from the POST data in the request body.

Let's now test one of my endpoints using a HTTP client.

postman

Success! My API call has returned some to-do list data from APEX. What you should notice here, is that as well as my to-do data, an extra property is returned in the form of a URL to get the next part of the data set. This is a feature of HATEOAS; it is important for a RESTful service to provide us with the necessary information to make our next step. If we now follow the link that has been provided...

postman_2

...we can see that there is one data item on the next page. We are now also provided with two additional links. One to take us back to the first page of results and one to take us back to the previous page (in this case they happen to be the same). We are also provided with a next link, which I suspect is an issue with the APEX RESTful Services implementation since there is no additional data to navigate to.

In my to-do application, I render the next and previous links if they are provided in the response in order to enable pagination.

Page 1 todo_page_1

Page 2 - Note the issue with the counter, which is based on a count of items in each request. A new endpoint is required to retrieve a total to-do item count from APEX. todo_page_2

The to-do app is built using HTML and a JavaScript framework called AngularJS. Let's look at the full implementation of my API in the AngularJS controller for my to-do application.

angular_control

As you can see, there are several controller functions in use that make use of my APEX REST API. Notice that the markDone and removeTodo functions both call the same URL when making a request to my API (likewise for addTodo and render), but are differentiated by the HTTP method used. Remember that we previously configured the same URI in APEX to have separate POST and DELETE handlers.

You may have noticed the presence of a fail handler in the addTodo method. Let's take another look at the REST service and see what's happening in the POST handler for the items URI template.

post_error

We can see that an exception gets thrown if the handler does not receive a description. This causes the request to fail and therefore the $http fail handler will be called in our AngularJS controller's addTodo method. The fail handler opens up the returned HTML in a new window. Crude, but acceptable for the purposes of a demo.

todo_app

With a few simple URI templates and HTTP method handlers you can provide a powerful REST API for your APEX applications.