Design RESTful Services for Oracle JET: Part 2

UPDATE: I don’t use Oracle JET anymore (switched to Angular), so I will unfortunately not be able to help you with your Oracle JET related questions.

In the first post in this mini-series on RESTful services, we looked at the RESTful architecture from a very high-level. In this second post, we will dive in and design a simple RESTful service, which can be called almost effortlessly from Oracle JET!

The Demo RESTful Service

Let’s take the employees table from Oracle’s HR schema and use it as the foundation for a CRUD RESTful service:

Anyways, it isn’t the implementation that’s the focus of this post, but some basic design principles that will make sure your RESTful services are easy to use in Oracle JET.

Identify the Resource

Unlike SOAP and similar RPC technologies, you should not think in verbs (i.e. hire employee), but in nouns (i.e. employee).

Use the noun as the basic for the URI to your resource. The noun should always be in plural even when it’s bad grammar (i.e. informations). When designing RESTful services, consistency beats grammar!

So the path to our Employee RESTful service would be /employees

Use HTTP Methods

We will use standard HTTP methods to interact with the resource:

Task

Method

Path

Create a new employee

POST

/employees

Delete an existing employee

DELETE

/employees/{id}

Get a specific employee

GET

/employees/{id}

Get a collection of employees

GET

/employees

Update an existing employee

PUT

/employees/{id}

All interactions with the resource are handled via HTTP methods. So if we want to hire an employee, we create a new employee via the POST method. If we want to give an employee a salary increase, we will use the PUT method to update an existing employee with a new salary.

You should also note how the bad grammar continues. Even when we deal with a single employee, we still use plural in the path name to keep the naming consistent.

In the POST method, we must make sure that the client doesn’t need to supply the primary key (i.e. employeeId) as input. The RESTful service should automatically take that from a sequence. The reason is that it will be impossible for the client to guess an unused primary key. On top of that, the POST method should return the newly created employee, so the client can get access to the primary key, and continue to manipulate the record if necessary.

You should be careful about using other HTTP methods than the Big Four (GET, POST, PUT, DELETE), because they might be rejected by proxy servers, load balancers, or other opinionated middlemen that stands between the client and the server.

It’s true that the client might be able to use HTTP tunneling to get the traffic through anyway, but it doesn’t exactly make it easy to call your web service…

The only other HTTP method you should seriously consider is PATCH. PATCH is similar to PUT but where PUT makes a complete update of all fields (including those that hasn’t been changed) then PATCH is a partial update that only overwrites fields that have actually been changed.

If the client deals with simple data in a form-oriented way (load all data into a form, manipulate them, and write them all back) then consider PUT, but if the client uses data-grids where individual cells are updated in isolation, or your service uses seriously big and complex data structures then consider PATCH.

Use JSON Only

For HTTP request and response bodies, we should only use JSON (and not XML).

Yes, it’s trivial to add XML support in JAX-RS by changing an annotation, but XML is simply not used by Oracle JET (or similar frameworks) and the agile principle of maximizing the amount of work not done (to keep things simple) should be followed.

Why? Because code that hasn’t been written doesn’t contain defects or security holes, and it doesn’t need to be tested and maintained. This is probably also why some highly popular RESTful APIs, like Twitter’s, dropped XML support several years ago…

Don’t Leak the Implementation!

Finally, it’s important not to leak the server’s implementation of the resource, as that’s one of the bedrock principles of the RESTful architecture. That is, the client shouldn’t notice that we use Java and an Oracle Database for the implementation.

The most obvious leak in this example would be to leak the names of the database columns to the client. The standard in JavaScript is to use camel case (i.e. phoneNumber) and not snake case (i.e. phone_number) like in an Oracle Database.

If we leak this then either the client code will look dodgy (by mixing two naming standards) or the client will waste valuable time on implementing the parse and parseSave functions in oj.Model.extend to do the conversion…

But if we stick to the design principles outlined in this post then Oracle JET’s Model and Collection APIs will take care of almost everything for us, which will make our Oracle JET code look really neat!

For example, if we want to get a specific employee, we only need this code: