How Oracle ORDS RESTful Services are Structured

Introduction

Before we get into building our first REST service, we should consider how ORDS implements REST and how this implementation my impact the way we design our REST services using ORDS. ORDS has four primary structures that are used to implement a REST based service (schema, module, template and handler). I will cover each of these structures in this post. Some of the material in this post is also covered in my last post ords-what-is-it-how-can-i-use-it-how-should-i-use-it.html it is included here also for completeness.

In order to illustrate these structures and their impact on our design decisions, I will be referring to the below diagram throughout the post.

Oracle REST Data Services - Structure

---

Schema

At the highest level is the database schema. When you enable a schema for ORDS (ORDS.ENABLE_SCHEMA) you identify the schema that should be ORDS enabled. You also identify the URL pattern that ORDS will use to direct REST requests to handler logic related to that schema. If we create a schema called XXEBSREST and enabled it for ORDS with a url mapping pattern of /ebs, all requests received by ORDS that have /ebs in the URL will be directed to handlers associated with the XXEBSREST schema.

The schema acts as a logical container for all of the modules, templates and handlers you create for services related to your schema. The reason I say logical is that all ORDS related metadata is actually stored in the ORDS_METADATA schema (as opposed to the schema you have ORDS enabled).

Design Tip: Just because you named your schema xxr2d2 because of some internal standard does not mean you have to use this in the URL mapping. The ORDS enable API allows you to use anything for the URL mapping.

Module

You can think of a module as a collection of related services. A module is tied to a database schema via a url mapping pattern (see previous section) and a database schema can contain many modules. Modules are not a REST concept as such but are a useful grouping structure for your resources that has been provided by ORDS.

The module in ORDS is also component of the URL path for your web service, so you should consider the names of your modules carefully.

Design Tip: I like the idea of using modules to version my REST services. This makes it easier for me to move certain consumers of my APIs to a new version while other can still use an older version.

In the example structure, we have created modules for v1 and v2 of our EBS APIs. In V2, we have introduced a new PUT method to allow authorized users to update orders and we have also changed the GET handler of the customer template to include search capabilities. In order that we don't disrupt existing consumers of these APIs, we have implemented a V2 module. New consumers can access the new services under /ebs/v2/customer and /ebs/v2/order. Existing customers can use /ebs/v1/customer and /ebs/v1/order. This also gives you time to move your old customers to the new version and deprecate v1 gracefully.

You can of course create modules to represent other groupings of services. For example, I could have created a module called 'md' for master data and a module called 'om' for order management related services. Then I would have placed the customer template under the 'md' module and order under the 'om' module.

Template

In REST lingo, a template can be thought of as a resource (item, customer, cat, dog etc.). This is a not a strict relationship as there are times when you need to create multiple templates for a resource (e.g. if you need two versions of a GET service with different parameters). Templates also represent the final piece of the REST service URL. In our example, we have templates/resources called customer and order under both the v1 and v2 modules.

At this stage the URLs to access our services look as follows. This assumes that when we installed ORDS we kept the war file name as ORDS.war:
    - Customer - http://example.com/ords/ebs/v2/customer
    - Order - http://example.com/ords/ebs/v2/order

Design Tip: Follow good REST principals when deciding on your resource names. It may be tempting to call your services updateOrder and getCustomer but the resource name should really be a noun. See me last post ords-what-is-it-how-can-i-use-it-how-should-i-use-it.html for a more in-depth analysis of resource naming.

Handler

Finally, we have reached the actual REST service code/logic. Handlers can be created for the following http methods:

• GET - Read/Select
• POST - Create/Insert
• PUT - Update
• DELETE - Delete / Inactivate

The handler is what links your resource / template (identified in the web service URL) to the verb/action (identified in the HTTP method used to invoke the service). It is where your SELECT statements or PL/SQL logic are stored. You can create a single handler per http verb per template. The handler does not make up part of the URL for the service, instead it is the verb/action part of your REST service.

Conclusion

In this post, I have covered the basics of how the structures in ORDS implement REST based web services. Understanding these structures, as well as how they impact the service URL and HTTP method is key to understanding ORDS itself.