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.
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.
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.
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.
- GET - Read/Select
- POST - Create/Insert
- PUT - Update
- DELETE - Delete / Inactivate