How do I USE Path Parameters in REST

 Using path parameters in REST APIs is a fundamental technique to create dynamic and flexible endpoints that can handle variable data within the URL itself. In Oracle APEX and RESTful services, path parameters allow developers to define parts of the URI that act as placeholders for values such as IDs or names. This approach makes REST APIs more intuitive and resource-oriented, enabling users to request specific data by embedding identifiers directly into the URL path.

Using path parameters in REST services within Oracle APEX allows you to create dynamic and flexible REST endpoints that respond to variable inputs embedded directly in the URL. Path parameters are placeholders in the URL path that are replaced by actual values when the service is called. This enables clients to request specific resources or filter data without relying on query strings.

To use path parameters in REST in Oracle APEX, first you need to define a RESTful service module and resource. When creating a resource, specify the URI pattern with placeholders wrapped in curly braces {}. For example, /employees/{employee_id} defines a path parameter named employee_id. This indicates that any request to /employees/123 will pass 123 as the value for employee_id.

Next, in the RESTful service resource handler (GET, POST, PUT, DELETE), you can reference the path parameter in your SQL query or PL/SQL code. Oracle APEX automatically maps the path parameter value to a bind variable with the same name. For example, in the SQL source you can use :employee_id to filter records like:

SELECT * FROM employees WHERE employee_id = :employee_id

Similarly, in PL/SQL, you can access the path parameter by referring to the bind variable :employee_id.

When testing the REST endpoint, replace the path parameter placeholder with an actual value in the URL. The REST service will then use that value in the backend logic to return or manipulate the targeted resource.

In summary, the key steps are:

1. Define a RESTful service module in Oracle APEX or ORDS.

2. Create a resource with a URI template containing path parameters using {}.

3. Use the corresponding bind variables in your SQL or PL/SQL to access parameter values.

4. Call the REST endpoint with actual values replacing the path parameters in the URL.

This method makes your REST services more intuitive and RESTful, adhering to resource-oriented URL design principles. It also simplifies filtering and accessing specific records, improving API usability and flexibility.

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.

Mastering the use of path parameters in REST services is essential for building scalable and maintainable APIs in Oracle APEX. By effectively utilizing path parameters, you can design cleaner, more efficient endpoints that clearly represent resources and their relationships. This improves both the developer experience and the overall usability of your RESTful interfaces.