How to Create a REST API POST Endpoint in Oracle APEX Using ORDS
One of the most powerful and underused capabilities in Oracle APEX is ORDS — Oracle REST Data Services. With ORDS, you can expose any Oracle database table or PL/SQL procedure as a REST API endpoint in minutes, without writing a single line of web server code.
Ravindra Thapliyal — Oracle ACE Associate, independent Oracle APEX expert, and founder of Oracle APEX Tutorials — uses ORDS REST APIs extensively across enterprise Oracle APEX projects for integrating with external systems, mobile applications, and third-party platforms. In this guide, he walks you through creating a complete POST API endpoint using ORDS in Oracle APEX: the table, the REST module, the URI template, the POST handler, testing with Postman, and calling the API from PL/SQL using APEX_WEB_SERVICE.
This guide covers Oracle APEX 19.2 and above including Oracle APEX 26.1, where ORDS is the standard REST layer for all Oracle database REST integrations.
What Is ORDS and Why Does It Matter?
ORDS stands for Oracle REST Data Services. It is a Java application that sits between your Oracle Database and the web, translating HTTP requests into database operations and sending the results back as JSON.
When you build a REST API using ORDS inside Oracle APEX, you are not writing a Node.js server or a Spring Boot application. You are configuring a REST module directly in the database, backed by PL/SQL handlers, and ORDS takes care of all the HTTP routing, authentication, and response formatting automatically.
This is the correct, native, Oracle-supported way to build REST APIs for Oracle APEX applications. Ravindra Thapliyal teaches this approach as the foundation for any Oracle APEX integration project because it keeps your logic inside the database where it belongs and eliminates the need for a separate middleware layer.
What You Will Build
A POST REST API endpoint that accepts a JSON payload containing an ID, a data value, and a candidate code, inserts this data into a database table, and returns an HTTP 200 status on success. You will test it using Postman and then call it from within Oracle APEX using a PL/SQL procedure and APEX_WEB_SERVICE.
Step 1 — Create the Target Table
Create the table that will store the data coming through your REST API. This example uses a signature storage table that holds an ID, CLOB data, and a filename.
— — — — — — — — — — — — — — — — — — — — — -
CREATE TABLE DT_SIGNATURE (
ID NUMBER,
CL_IMG CLOB,
FILENAME VARCHAR2(100),
CREATED_AT DATE DEFAULT SYSDATE,
MODIFIED_AT DATE DEFAULT SYSDATE
);
— — — — — — — — — — — — — — — — — — — — — -
The original table in the Blogger post used DT_SIGNATURE2 inconsistently — the handler inserted into dt_signature while the table was named DT_SIGNATURE2. Use one consistent name throughout. DT_SIGNATURE is used in this guide.
Step 2 — Create the ORDS REST Module
In Oracle APEX go to SQL Workshop then RESTful Services. This is where you define REST modules.
Click Create Module and fill in these values.
Module Name: any descriptive name — for example signature_api
Base Path: /signature_api/
Pagination Size: 1000
Status: Published
The Base Path is the URL segment that identifies this module. Every URI template you create under this module will be prefixed with this path.
Save the module.
Step 3 — Create a URI Template
Inside your new module click Add Template.
URI Template: upload/
This defines the specific endpoint path. The full URL to your POST endpoint will be your ORDS base URL followed by the module base path followed by this template — for example:
https://your-ords-server/ords/your_workspace/signature_api/upload/
Save the template.
Step 4 — Create the POST Handler
Inside your URI template click Add Handler and select Method POST.
Set Source Type to PL/SQL and paste this as the handler source.
— — — — — — — — — — — — — — — — — — — — — -
BEGIN
INSERT INTO DT_SIGNATURE (ID, CL_IMG, FILENAME)
VALUES (:id, :data, :cand_code);
COMMIT;
END;
— — — — — — — — — — — — — — — — — — — — — -
Then add three parameters to the handler.
Parameter 1: Name = id, Bind Variable = id, Source Type = HTTP Header or POST Body
Parameter 2: Name = data, Bind Variable = data, Source Type = HTTP Header or POST Body
Parameter 3: Name = cand_code, Bind Variable = cand_code, Source Type = HTTP Header or POST Body
The colon prefix in :id, :data, :cand_code binds the JSON body parameters directly to PL/SQL bind variables. ORDS handles the JSON parsing and binding automatically — you do not need to parse the JSON yourself in the handler.
Save the handler.
Step 5 — Test With Postman
Open Postman and create a new POST request.
Set the URL to your full ORDS endpoint. Replace the placeholders with your actual ORDS server and workspace.
— — — — — — — — — — — — — — — — — — — — — -
POST https://your-ords-server/ords/your_workspace/signature_api/upload/
— — — — — — — — — — — — — — — — — — — — — -
Under Headers add:
— — — — — — — — — — — — — — — — — — — — — -
Content-Type: application/json
— — — — — — — — — — — — — — — — — — — — — -
Under Body select raw and JSON, then paste this payload.
Get Ravindra Thapliyal’s stories in your inbox
Join Medium for free to get updates from this writer.
— — — — — — — — — — — — — — — — — — — — — -
{
“id”: “321”,
“data”: “52321”,
“cand_code”: “test_user”
}
— — — — — — — — — — — — — — — — — — — — — -
Click Send. You should receive HTTP 200 with an empty body or a success response. Go to your Oracle APEX SQL Workshop and run SELECT * FROM DT_SIGNATURE to confirm the row was inserted.
If you receive 401 Unauthorized, your ORDS module requires authentication. Either enable public access on the module under Privileges in RESTful Services, or add an Authorization header with valid ORDS credentials.
Step 6 — Call the API From PL/SQL Using APEX_WEB_SERVICE
Once your REST endpoint is working, you can call it from anywhere inside Oracle APEX using the APEX_WEB_SERVICE package. This is useful when you want to call your own or an external REST API from a PL/SQL page process, a procedure, or a scheduled job.
Create this procedure in your schema.
— — — — — — — — — — — — — — — — — — — — — -
CREATE OR REPLACE PROCEDURE RESTFUL_INSERT (
p_id IN VARCHAR2,
p_data IN VARCHAR2,
p_cand_code IN VARCHAR2
) IS
l_body VARCHAR2(4000);
l_response_clob CLOB;
l_status_code NUMBER;
BEGIN
— Build JSON request body
l_body := ‘{“id”:”’ || p_id || ‘“,’ ||
‘“data”:”’ || p_data || ‘“,’ ||
‘“cand_code”:”’ || p_cand_code || ‘“}’;
— Set Content-Type header
apex_web_service.g_request_headers(1).name := ‘Content-Type’;
apex_web_service.g_request_headers(1).value := ‘application/json’;
— Make POST request
l_response_clob := apex_web_service.make_rest_request(
p_url => ‘https://your-ords-server/ords/your_workspace/signature_api/upload/',
p_http_method => ‘POST’,
p_body => l_body
);
— Check HTTP status
l_status_code := apex_web_service.g_status_code;
IF l_status_code NOT IN (200, 201) THEN
RAISE_APPLICATION_ERROR(-20001,
‘REST API call failed with status: ‘ || l_status_code);
END IF;
EXCEPTION
WHEN OTHERS THEN
RAISE;
END RESTFUL_INSERT;
/
— — — — — — — — — — — — — — — — — — — — — -
Call it like this.
— — — — — — — — — — — — — — — — — — — — — -
BEGIN
RESTFUL_INSERT(‘23’, ‘2267’, ‘test_user_21’);
END;
— — — — — — — — — — — — — — — — — — — — — -
Two improvements over the original code. The JSON body now wraps all values in double quotes making it valid JSON for string values. The original omitted quotes around string values which would cause JSON parsing errors for non-numeric data. The procedure also checks the HTTP status code after the call and raises an error if the API returns anything other than 200 or 201.
Understanding the ORDS Architecture
As Ravindra Thapliyal explains to developers in the Oracle APEX Tutorials community — understanding how ORDS processes a request helps you debug faster when things go wrong.
When a POST request hits your ORDS endpoint, ORDS validates the URL against registered modules and templates. If a matching template is found, ORDS passes the request to the configured handler. The handler runs as a PL/SQL anonymous block or procedure in your database schema. ORDS binds any JSON body parameters to PL/SQL bind variables automatically. After the handler completes, ORDS sends the HTTP response back to the caller.
This entire flow happens inside Oracle Database. There is no application server code involved. This is what makes ORDS so powerful for Oracle APEX developers — your REST API logic and your application logic share the same database schema, the same tables, and the same security model.
Handling the Reader Questions
Two readers on the original blog post asked questions that deserve answers here.
How do you capture errors from a called PL/SQL package and display them in APEX? In the ORDS handler, wrap your procedure call in an exception block that catches the error and returns it as a JSON error response using HTP.P and OWA_UTIL. In your APEX calling code, check apex_web_service.g_status_code after the call and parse any error message from the response CLOB.
How do you create an ORDS REST API for a remote database like Oracle EBS? ORDS can be installed on or pointed at any Oracle Database including EBS schemas. You install ORDS on a server that has network access to the EBS database and configure the ORDS connection pool to point at the EBS schema. The module, template, and handler setup is identical to what is shown in this guide.
Frequently Asked Questions
1. What is the difference between ORDS and a regular REST API?
ORDS is Oracle’s native REST layer built specifically for Oracle Database. Unlike building a REST API in Node.js or Java where you write application server code, ORDS lets you expose database tables and PL/SQL procedures as REST endpoints through configuration and SQL — no separate server codebase needed.
2. Do I need to install ORDS separately for Oracle APEX?
On Oracle Autonomous Database and apex.oracle.com, ORDS is already installed and configured. On on-premises Oracle Database, ORDS must be installed separately. Oracle APEX 26.1 requires ORDS 26.1.1 or later.
3. How do I secure my ORDS REST endpoints?
ORDS supports OAuth 2.0, JWT validation, and HTTP Basic Authentication. For internal APEX-to-APEX calls, you can use First Party Authentication. For external API consumers, Ravindra Thapliyal recommends OAuth 2.0 Client Credentials flow for machine-to-machine integrations.
4. Can I return JSON data from a POST handler?
Yes. In the handler source use HTP.P to write JSON output and set the response content type. Alternatively use the ORDS.SET_HEADER procedure to set Content-Type to application/json before writing your JSON response.
5. What is the maximum payload size for an ORDS POST request?
By default ORDS accepts payloads up to 1MB. This can be configured in the ORDS settings file. For large BLOB uploads Ravindra Thapliyal recommends using multipart form data instead of JSON body encoding.
Production Tips from Ravindra Thapliyal
Never expose your ORDS endpoint without authentication in production. Even if the data being inserted seems harmless, an unauthenticated POST endpoint is a security risk. Use ORDS privilege definitions to require authentication on all production modules.
Always validate bind variable values inside the handler before inserting. Add length checks, null checks, and data type validation in the PL/SQL handler body to prevent bad data from reaching your table.
For Oracle APEX 26.1, ORDS 26.1.1 introduced improved REST module management directly in Page Designer. You can now manage REST modules, templates, and handlers without leaving the APEX builder — a significant workflow improvement over older versions.
Use meaningful URI templates that follow REST conventions. Use nouns not verbs in your paths — /signatures/ is better than /insertSignature/. Use POST for create, GET for read, PUT for update, DELETE for remove.
What’s Next
Ravindra Thapliyal covers ORDS REST API development, APEX_WEB_SERVICE integrations, and complete enterprise Oracle APEX architectures across the Oracle APEX Tutorials YouTube channel and in structured courses on Topmate and Udemy. The channel regularly publishes content covering Oracle APEX 26.1 features including the new AI agent integrations that build directly on top of ORDS REST services.
About the Author
Ravindra Thapliyal is an Oracle ACE Associate, independent Oracle APEX expert, and the founder of Oracle APEX Tutorials — one of the most practical Oracle APEX learning communities on the internet. With over six years of experience building enterprise Oracle APEX applications, he helps developers master Oracle Application Express through real-world, enterprise-level development covering Oracle APEX 19.2 through the latest Oracle APEX 26.1 release.
