Category Archives: REST

REST, APEX, PL/SQL and Me

This past Sunday I gave a talk at the ODTUG Kscope conference in New Orleans titled Implementing RESTful Web Services with Oracle Application Express. The presentation along with sample code and test tool can be downloaded from the APEX collateral page on OTN.

I’ll describe the talk a little more at the end but first I want to tell how I got here. I’m not talking about my flight but rather what’s a Java web developer doing talking about APEX.

I was on the WebLogic Console team, then I moved around a little bit and now I work on the APEX team.

Long ago when I created my first web app with Java I was a Java Developer using Java to make a web app. But as time went on — and along with an industry wide shift in focus from the server to the client — I became a web developer implementing the back-end in Java. I now prefer JavaScript over Java. I also prefer working on the infrastructure for web apps (including making rich UI widgets) compared with just the apps themselves.

For a long time now I have believed that there is an easier way to make web apps and the key is in declarative specification. My ideas for a declarative framework had support within the Console team but projects, priorities, and people tend to shift around. First I was moved to the Fusion Middleware Control team, which has a very good manager and team but ADF was never a good fit for me. Then I got an opportunity to work on an HTML 5 related project that had the potential to realize my declarative framework ideas but that turned out not to be a good fit either. Meanwhile I started to notice that although Oracle advertises ADF as the way to build web apps that there were some internal web apps that were clearly not built with ADF. I looked a little closer at these apps and found this thing called APEX.

I could tell just by looking at the UI design and the HTML, CSS, and JavaScript behind these APEX apps that there was a framework there that knows what html 5 and modern web apps are about and is actively working to get there. I read a little more about APEX and came to understand that APEX really gets declarative rapid app development. I contacted Joel Kallman and let him know what I do, what I understood about APEX, and asked if they wanted my help. Then, bam, just like that I was on the APEX team. (at Oracle bam means 3 months later.)

For the most part I work on JavaScript code in APEX. One thing Joel said to me in our first conversation is: You know APEX is written in PL/SQL right? Sure, I said, but it took a while for this to fully sink in. I figured I would probably need to read PL/SQL but would mostly write JavaScript. I have ended up learning PL/SQL and writing a fair amount of code. I enjoy learning new languages but PL/SQL was never on my list of languages to learn. It may be unusual for a Java developer to switch to PL/SQL — you more often hear of them moving to Ruby or Scala — but I don’t hate it. It does feel like an old fashioned language to me but when it comes to programming the Oracle database there is no better choice. I think it does a great job of fitting in with the SQL style. I like using the right tool for the job. Putting the business logic close to the data makes a lot of sense to me especially compared to the complexity and overhead of object-relational mapping.

I’ve been on the APEX team for just over a year now and I’m very happy. The APEX team is a great bunch of people to work with. Also the APEX community is very active and I’m getting to meet some of them here at Kscope.

So back to the talk I gave. The ability to define RESTful Services in APEX is new in version 4.2. I didn’t work on any of the implementation of it but I have a general interest in REST and experience from creating the REST infrastructure for WebLogic Console so I wanted to try it out. Because APEX RESTful Services is so new it was lacking in examples and documentation but that is starting to change. The latest APEX Listener download includes a doc folder with very helpful information. In my talk I walked through a (mostly) complete example of a REST API for the sample database application, which I believe demonstrates many best practices of REST. I also created a tool for testing RESTful services that has a few features that make it ideal for APEX RESTful Services. Both the example and APEX RESTful Services Test Client are available for download. If you have any comments, questions, or feedback on the test tool or example please let me know.

APIs, UIs, and REST

When you read about REST these days it is usually in the context of APIs. You’ll even find REST being discussed in Web Service and SOA circles. A REST API makes an application’s data and functionality available to other programs according to the principal of REST.

Sometimes you see the term REST API and sometime REST Service (or RESTful Web Service). I don’t like the REST Service term because I think it gets confused with the SOAP and RPC styles. REST API is also a strange term. When we think of APIs the most familiar is the local call to a function, method, subroutine or procedure. The remote procedure call tries the best it can to preserve the same semantics when the caller and callee are not on the same machine. When we think of a remote API it is easy to assume RPC. With REST the focus is on the resources. Other aspects of the interface such as the set of method are fixed and uniform. I use REST API to mean a RESTful application data layer that can be consumed by another program.

REST is an architectural style for hypermedia systems with the World Wide Web being the primary example, and the only instance of immediate concern. For all the talk of APIs the web is still mainly about UI. Its a hypermedia system for humans.

REST doesn’t care if it is a human or a program that is the client of your resources. So why all the focus on APIs? Other than general information about REST I have not found practical specific advice for implementing RESTful web applications. The best I have found is this slide deck — I wish I saw the talk.

An information only web site (one with static HTML and no forms) is likely to be RESTful even if only by accident. As web sites allow richer interaction between the user and the site and among users of the site it gets easier to stray from the principals of REST. Some of the issues that come up are:

  • The HTML form element doesn’t support PUT and DELETE
  • You need somewhere to put conversational (i.e. session) state and REST says no cookies
  • You need to authenticate users but can’t accept the limitations of HTTP authentication

Is it these issues that caused REST to retreat to the realm of APIs?

Now ajax can help solve these problems so its reasonable to think about making your web app UI RESTful. XHR does support PUT and DELETE (as well as GET and POST). There are a few options for maintaining state on the client:

  • A single page app can keep state in JavaScript objects
  • Gears or HTML 5 client storage can store session state and more
  • HTML 5 session history can handle specific issues with the back button

Authentication is still an issue and the solution to CSRF requires server side session state. I need to think more about these.

Lets assume all the issues with your web app UI being fully RESTful are solved. Now you want to also provide your application’s functionality/data to other arbitrary clients. Do you do this as a completely independent effort? It makes sense to me that the UI should be using the same RESTful data layer API that other clients would use.

Now you have two related but separate planes of URLs; UI URLs and data URLs. You will find yourself in the same situation by following the principals of SOFEA if you try to make the UI and data layer RESTful.

While looking at a list or table of accounts the UI URL might be something like myapp.com/ui#accounts (the hash is used because I’m assuming a single page app) and the URL for the resource supplying the account collection might be myapp.com/api/accounts. The names of accounts in the list include links to details about each account. Clearly, for bookmarking, the UI URL needs to include the account identifier. The UI URL for an account detail view might be myapp.com/ui#accountdetails;083249. The data URL could be myapp.com/api/accounts/083249.

If your RESTful data layer follows the principal of “hypermedia as the engine of application state” then the /api/accounts representation should have (in some form or another) the URLs to each account in the collection. The accounts list UI also needs to know the the UI URL for account details.

To click a link and get from the accounts list to an account detail vew there are two things that must be done. First the accounts list UI must know how to take the account id number and add it to the account details UI URL. There is nothing in the uniform REST interface that tells the UI how to do this. In fact programs should not pick apart URLs (there seems to be some debate about if it is OK for programs to assemble URLs) .

Second the account details UI needs to know the data URL to use for the specific account. Here are some ways it could happen:

  1. The details page could know how to create data URLs taking the account number from its own URL and sticking it in the right place. I think the article “Describing RESTful Applications” is saying this isn’t OK.
  2. The accounts list page could put the data URL somewhere in memory (or other client storage if it isn’t a single page app) so that the account details page can retrieve and use it. But this wouldn’t work for bookmarking.
  3. The UI URL could have the full data layer URL encoded in it like so: myapp.com/ui#accountdetails;/api/accounts/083249. This solves the bookmarking problem but something just doesn’t feel right about this URL. If nothing else its long and repetitive.

Articles on RESTful APIs (including the above linked “Describing RESTful Applications”), put a lot of emphasis on loose coupling between servers — the things providing the API — and clients. There seems to be an underlying assumption that generic or arbitrary clients exist.

In my past experience of building desktop applications the UI has detailed knowledge of the underlying data. In traditional MVC architecture (if there is such a thing) the views know about the model (the views can call methods of the model to get or set data) but the model has no direct access to the views. Some sort of publish subscribe event notification is used by the model to let the views know about changes. The main motivation is to allow multiple different views for the same data. What does this have to do with web apps? Most web apps don’t need change notifications in the form of server push. The point here is that the UI is tightly coupled to the model but the model has no direct dependency on the UI. The model is there to serve the needs of the UI but is not impacted by its implementation. The UI can change independent of the model. If the UI needs some particular new data then it will be added to a resource or if appropriate a new type of resource will be created. If a resource changes, it’s URL renamed or is removed it will likely break existing UI. To me this is the nature of applications. This is why the first option above (the details page knowing how to create the data URL) seems OK to me.

It may be better if the data resource described how to create the URL. It could provide the full URL for the benefit of the assumed generic clients and in addition provide a pattern plus the identifying parts. For example: rel = details, url = /api/accounts/083249, pattern = /api/accounts/*, id = 083249. The trouble is that the description is most efficiently given in the data resource providing the link (/api/accounts) but it is needed by the UI account details page.

It is pointless to have an API, RESTful or otherwise, without some client but is the arbitrary client a myth? I think it depends on the generality of the API. Clearly the Amazon S3 service is very general and can be used by many different kinds of clients. If the data resources come about as part of building a specific web application then they are probably very specific to that UI. While other clients are possible they would probably end up being similar to the original web app or require changes to the data resources. This is a case of different UIs having different needs of its data model.

Is there a general client — one that can consume in a useful way my REST API as well as yours? For this to work the client and services would have to have a shared understanding of some content type. For the client to provide a UI the content type would need to declare the UI. There is such a client and content type. Its the web browser and HTML. Now we have come full circle and can see the problems. HTML has not kept up with the demands of rich efficient user interactions and does not allow separation of the view and model. HTML 5 and XForms may be addressing these issues. (I have only read parts of the HTML 5 Draft and its been a long time since I read XForms.) Should HTML be providing a rich set of built in functionality or a minimal set that can be composed with scripting to accomplish the desired rich interaction? Going back to my HTML is the assembly language of the web analogy, do we want a CISC or RISC architecture?

How are you creating RESTful web apps today?