Part 2: Accessing your secure REST API
In Part 1 of the “ORDS, APEX and secure REST APIs” blog post, we looked at the ways you can secure your REST modules.
Now that we have secured the API, let’s look at the ways you could access it. There are different implementations and different tools in every programming language, which makes REST services so popular and preferred.
As PL/SQL developers, what is mostly interesting for us, as a way to test REST APIs, are:
PL/SQL proceduresthat allow developers to call REST APIs from Oracle Databasecurl– a command line tool allowing us to test REST servicesPostman– an UI tool that allows us to create REST calls, create collections, see the results of our calls, etc.
curl
Syntax:
curl -i -d "grant_type=client_credentials" --user "[client_id]:[client_secret]" https://apex.oracle.com/pls/apex/your_workspace/oauth/token
curl -i --header "Authorization: Bearer [token from previous step]" https://apex.oracle.com/pls/apex/your_workspace/customer/details/
For example:
curl -i -d "grant_type=client_credentials" --user "Te8yn-qGmBoX6jzpPhnUXA..:7KZWVPkkzNZ_gpcS0l-YFw.." https://apex.oracle.com/pls/apex/your_workspace/oauth/token
curl -i --header "Authorization: Bearer y6NqQHt84rloaFhc2lySJA" https://apex.oracle.com/pls/apex/your_workspace/customer/details/
PL/SQL
Here is a sample call to an OAuth2 secured REST service:
declare
l_clob clob;
begin
-- call the oauth_authenticate procedure to get a Token,
-- based on your Client_Id and Client_Secret
apex_web_service.oauth_authenticate(
p_token_url => 'https://apex.oracle.com/pls/apex/your_workspace/oauth/token',
p_client_id => 'Te8yn-qGmBoX6jzpPhnUXA..',
p_client_secret => '7KZWVPkkzNZ_gpcS0l-YFw..');
-- set the request Authorization header
-- pay attention to the oauth_get_last_token - it takes the token, generatted by invoking oauth_authenticate
apex_web_service.g_request_headers(1).name := 'Authorization';
apex_web_service.g_request_headers(1).value := 'Bearer ' || apex_web_service.oauth_get_last_token;
-- call the REST API, using the module URL. The request headers are already set in the g_request_headers
l_clob := apex_web_service.make_rest_request (
p_url => 'https://apex.oracle.com/pls/apex/your_workspace/customer/details/',
p_http_method => 'GET');
-- display the result of the REST API call
dbms_output.put_line('Here is the API call result -> '||l_clob);
end;
And a sample call to a REST service, secured with Basic Authentication:
declare
l_clob clob;
begin
-- call the REST API, using the module URL. Use the username and password to authenticate
l_clob := apex_web_service.make_rest_request (
p_url => 'https://apex.oracle.com/pls/apex/your_workspace/customer/details/',
p_http_method => 'GET',
p_scheme => 'Basic',
p_username => 'your-db/apex-username',
p_password => 'your-db/apex-password');
-- display the result of the REST API call
dbms_output.put_line('Here is the API call result -> '||l_clob);
end;
To get a full list of the procedures and parameters, available in
apex_web_servicepackage – visit the APEX_WEB_SERVICE API Reference
Postman
- Go to File – New –
HTTP Request - Select the method type (
GETfor example) and enter the URL of your REST API - Go to
Authorizationtab - Select OAuth 2.0 from the
Typedropdown - Select Request Headers from
Add authorization data todropdown - Fill the following information in
Configure New Tokensection:- Token Name: ‘My OAuth2 token’
- Grant Type: Client Credentials
- Access Token URL: https://your-host/your-web-server/your-workspace/oauth/token (remember to replace yout-host,your-web-server and your-workspace with appropriate values)
- Client ID: The Client_Id generated earlier
- Client Secret: The Client_Secret generated earlier
- Click on
Get New Access Tokenbutton - Click on
Proceedbutton (or just wait a few seconds to take you automatically to the next step) - Click on
Use Tokenbutton - Click on the big blue
Sendbutton to call your REST API
Sample Postman collection
Find three different API calls in this collection:
- A call to an unsecured REST API
- A call to a REST API, secured with Basic Authentication
- A call to a REST API, secured using OAuth2
Visit Part 1 of this blog post, to see how an ORDS REST API is secured using Basic Authentication or OAuth2. Enjoy!
Additional resources
– OAUTH API reference
https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/21.2/aelig/OAUTH-reference
– ORDS API reference
https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/21.2/aelig/ORDS-reference.html
– APEX_WEB_SERVICE API reference
https://docs.oracle.com/en/database/oracle/application-express/21.1/aeapi/APEX_WEB_SERVICE.html
– Blog posts:
http://c2anton.blogspot.com/2016/06/super-quick-oracle-rest-service-with.html
https://oracle-base.com/articles/misc/oracle-rest-data-services-ords-authentication
APEX App Lab - Blog 
Hi, I want using client reactjs call API of apex oracle, can you support or document for me, thanks so much
LikeLike
Can you provide some additional information on what exactly you are trying to achieve and how?
LikeLike
Nice work. Very helpful!
LikeLike
Hi i’m trying to integrate with Egyptian eInvoicing & eReceipt and i’m trying using this code
Begin
/*———-Setting Headers—————————————-*/
apex_web_service.g_request_headers(1).name := ‘posserial’;
apex_web_service.g_request_headers(1).Value := ‘MYSE2023’;
apex_web_service.g_request_headers(2).name := ‘pososversion’;
apex_web_service.g_request_headers(2).Value := ‘os’;
apex_web_service.g_request_headers(3).name := ‘presharedkey’;
apex_web_service.g_request_headers(3).Value := ”;
apex_web_service.oauth_authenticate(
p_token_url => ‘https://id.preprod.eta.gov.eg/connect/token’,
p_client_id => ”,
p_client_secret => ”
);
/*—————————————————————–*/
DBMS_OUTPUT.PUT_LINE (‘Last Token : ‘||apex_web_service.oauth_get_last_token );
End;
But I Always Get This Error ORA-20001: Authentication failed.
While Iam Totaly Sure of the all data i provide But I Think I May Write Something Wrong Or Miss Something TO Wrtite So Would You Please Let Me Know WHat i Have To Do and here is the link of The Egyptian eInvoicing & eReceipt
https://sdk.invoicing.eta.gov.eg/ereceiptapi/01-authenticate-pos/
LikeLike
When I Try The Same Data in POSTMAN It Work Perfect But When I Use It From Oracle It Give Me ORA-20001: Authentication failed.
LikeLike