ORDS, APEX and secure REST APIs (Part 2 – call the API)

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 procedures that allow developers to call REST APIs from Oracle Database
  • curl – a command line tool allowing us to test REST services
  • Postman – 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_service package – visit the APEX_WEB_SERVICE API Reference

Postman

  • Go to File – New – HTTP Request
  • Select the method type (GET for example) and enter the URL of your REST API
  • Go to Authorization tab
  • Select OAuth 2.0 from the Type dropdown
  • Select Request Headers from Add authorization data to dropdown
  • Fill the following information in Configure New Token section:
    • 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 Token button
  • Click on Proceed button (or just wait a few seconds to take you automatically to the next step)
  • Click on Use Token button
  • Click on the big blue Send button 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

One thought on “ORDS, APEX and secure REST APIs (Part 2 – call the API)

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s