Studying API Handler Package Layers

Study how ORDS handlers call a REST layer that delegates to shared core API logic.

The figure below illustrates how the five v1 module template handlers call appropriate procedures in the ACTIONS_ITEMS_API_REST package. Each handler uses a combination of ORDS implicit and explicit parameter bind variables to pass incoming request information to the corresponding package procedure. The digram shows the following ORDS handlers and the ACTION_ITEMS_API_REST procedure each invokes:

• GET /v1/actionitems → get_objects

• GET /v1/actionitems/:id → get_object

• POST /v1/actionitems → insert_object

• PUT /v1/actionitems/:id → update_object

• DELETE /v1/actionitems/:id → delete_object

Description of the illustration ords-handlers-call-plsql-api-rest-pkg.png

The package specification for ACTION_ITEMS_API_REST appears below.

package action_items_api_rest as
    ------------------------------------
    procedure get_objects(
        p_search in varchar2,
        p_offset in number   default 0,
        p_limit  in number   default 10,
        p_debug  in varchar2 default null);
    ------------------------------------
    procedure get_object(
        p_id in number,
        p_debug  in varchar2 default null);
    ------------------------------------
    procedure insert_object(
        p_object in clob,
        p_debug  in varchar2 default null);
    ------------------------------------
    procedure update_object(
        p_id     in number,
        p_object in clob,
        p_debug  in varchar2 default null);
    ------------------------------------
    procedure delete_object(
        p_id     in number,
        p_debug  in varchar2 default null);
end action_items_api_rest;

As shown below, the ACTION_ITEMS_API_REST package is a REST-specific layer on top of the ACTIONS_ITEM_API package that contains the core of the API logic. Its simple procedures essentially convert the incoming JSON CLOB payloads into a JSON_OBJECT_T types to pass to the core Action Items API package. Then they use the common functionality in APP_COMMON_REST to write out the response or error details. This layering keeps the ORDS handler PL/SQL blocks extremely simple.

Notice in the diagram how the ACTION_ITEMS_API package reuses application-wide common code from APP_COMMON and Action Item specific common validation logic from ACTION_ITEMS_COMMON. This layering maximizes reuse so your application pages and REST APIs apply the same checks to modified data, regardless of how the users or external systems submit it.

The figure illustrates a package dependency diagram showing:

• ACTION_ITEMS_API_REST uses

  • ACTION_ITEMS_API for logic

  • APP_COMMON_REST as a REST services helper

• ACTION_ITEMS_API uses

  • ACTION_ITEMS_COMMON for validation

  • APP_COMMON for error handling

• ACTION_ITEMS_COMMON also uses APP_COMMON for error handling

In addition, the diagram shows that the Action Items edit page uses the same packages:

• ACTION_ITEMS_COMMON for validation

• APP_COMMON for error handling

Description of the illustration 19c-action-items-rest-api.png