APEX REST: How do I USE Path Parameters

 

Introduction

When building RESTful web services in Oracle APEX, path parameters offer a clean and efficient way to pass values directly within the URL structure. This technique is especially useful when you want to retrieve specific records or perform operations on targeted resources such as employees, orders, or products. Understanding how to define and use path parameters properly is essential for making your APEX RESTful services more intuitive, dynamic, and REST-compliant.

How to Use Path Parameters in APEX

To implement path parameters in Oracle APEX, follow these steps:

1. Access the RESTful Services Module
   Navigate to SQL Workshop > RESTful Services and either create a new module or edit an existing one.

2. Define a Resource Template with a Path Parameter
   Add a new resource template with a syntax like /employees/{employee_id}. Here, {employee_id} is a path parameter placeholder.

3. Declare the Path Parameter
   After saving the resource template, go to the Parameters section and add a new parameter:

   • Name: employee_id

   • Type: Path Parameter

   • Data Type: Number or Text, depending on your use case

   • Required: Yes

4. Use the Parameter in SQL or PL/SQL Logic
   In the GET method of the resource, reference the path parameter using a bind variable:

   SELECT first_name, last_name, department_id
     FROM employees
    WHERE employee_id = :employee_id
   

5. Test the Endpoint
   You can now call the service using a URL like:

   https://your-apex-domain/ords/hr/api/employees/103
   

   The value 103 will be passed to your SQL via :employee_id.

Best Practices

• Always validate the path parameter value in your SQL or PL/SQL to avoid unexpected results or SQL injection risks.

• Use meaningful and predictable names for your path parameters (e.g., {employee_id}, {order_id}).

• Stick to RESTful conventions—use plural nouns for resource names (/employees, /orders) and include the parameter only when you need to access a specific record.

• Avoid mixing path parameters and query parameters for the same data point; choose one method consistently.

Oracle APEX Documentation
For more details, see the official Oracle APEX documentation:
https://docs.oracle.com/en/database/oracle/apex/

 

You would call the service by embedding the ID number directly in the URL path.

Example URL:

https://your-server/ords/schema/rest/employees/{employee_id}

To dynamically call the service using the ID number provided by the user (e.g., through a page item like P1_EMPLOYEE_ID), you can use the following approach:

1. Create a Button or Process to trigger the call.

2. Use the APEX_WEB_SERVICE package in PL/SQL to make the RESTful call.

DECLARE

    l_url        VARCHAR2(32767);

    l_response   CLOB;

    l_employee_id VARCHAR2(100);

BEGIN

    -- Get the employee ID from the page item

    l_employee_id := :P1_EMPLOYEE_ID;

    -- Construct the RESTful URL with the employee ID

    l_url := 'https://your-server/ords/schema/rest/employees/' || l_employee_id;

    -- Make the REST call to the service

    l_response := APEX_WEB_SERVICE.make_rest_request(

                      p_url          => l_url,

                      p_http_method  => 'GET'

                  );

    -- Process the response

    -- (Handle response as JSON or XML depending on your API)

    DBMS_OUTPUT.put_line(l_response);

    

    -- You can also populate the page items with data from the response

    :P1_EMPLOYEE_DATA := l_response; -- Example: Store response in a page item

END;

Here, the l_url is dynamically constructed by appending the employee_id from the page item P1_EMPLOYEE_ID to the base URL.

Conclusion

Path parameters in Oracle APEX are a powerful and RESTful way to pass values within your URL endpoints. They help keep your API design clean and logical while enabling dynamic access to individual resources. By understanding how to define and implement path parameters effectively, you can build more maintainable and intuitive web services within APEX.