JMJ CLOUD
  • Home
  • Projects
  • Blog
  • About Us
  • Contact Us

Our Blog

How Oracle ORDS RESTful Services are Structured

10/6/2016

1 Comment

 

Introduction

Picture
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.
Picture
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.
1 Comment
PRANAV link
11/16/2016 12:42:17 pm

Thanks for sharing !!

Reply

Your comment will be posted after it is approved.


Leave a Reply.

    RSS Feed

    Popular Posts

    - APEX Dog Food
    - Cloud ERP & APEX Mashup
    - Modernizing EBS with APEX
    - Easy APEX_WEB_SERVICE
    - Running APEX in RDS
    - ORDS What & Why?

    Categories

    All
    APEX
    AWS
    Fusion Cloud ERP
    INTEGRATION
    OCI
    ORDS
    PaaS
    RAD
    REST
    SOAP

    Archives

    January 2021
    October 2020
    September 2020
    June 2020
    May 2020
    April 2020
    February 2020
    January 2020
    October 2019
    September 2019
    August 2019
    July 2019
    June 2019
    April 2019
    March 2019
    February 2019
    January 2019
    December 2018
    November 2018
    October 2018
    September 2018
    August 2018
    July 2018
    June 2018
    May 2018
    April 2018
    March 2018
    February 2018
    January 2018
    September 2017
    August 2017
    July 2017
    June 2017
    February 2017
    January 2017
    December 2016
    November 2016
    October 2016
    September 2016
    August 2016
    July 2016

Company

About
Contact
Blog
  • Home
  • Projects
  • Blog
  • About Us
  • Contact Us