Das Dokument behandelt die Integration von REST-Services mit Oracle APEX 18.1, einschließlich der Verwendung von Web-Source-Modulen und Authentifizierungsmethoden wie Token-basierte Zugriffe. Es werden Beispiele für die Anbindung an externe APIs, insbesondere NFL- und Jira-Daten, sowie technische Herausforderungen und Lösungen im Zusammenhang mit Access Control Lists (ACL) vorgestellt. Zudem sind Hinweise zur Modulerstellung, zur Fehlerbehebung und zur optimalen Nutzung von REST-API-Funktionen enthalten.

1. REST mit APEX 18.1
Oliver Lemm
DOAG 2018

2. @OliverLemm@OliverLemm 2
Oliver Lemm
APEX WORLD
2016 & 2017

3. @OliverLemm
facts & figures
Independent Technology House
with Cross-Industry Expertise
Headquarter
Ratingen
(North Rhine – Westphalia)
260
Employees
Founded
1994
Branches
Dortmund, Cologne,
Frankfurt
Top Company
for Trainees &
Students
Privately-
Owned
Corporation
Oracle
Platinum
Partner
28 Mio. Euro
Revenue
3@OliverLemm

4. @OliverLemm@OliverLemm
 REST Services
 Web Source Modul
 Authentifizierung
 Einbau der Komponenten
 API Packages
 APEX_ EXEC, APEX_WEB_SERVICE
 Sample REST Services
Agenda

5. @OliverLemm@OliverLemm
 Daten im „frei“ verfügbar
 eingeschränkte Datenmenge
 keine „Echtzeitdaten“
 Eingeschränkte Anzahl Anfragen
pro Zeitraum
 Zugriff Token basiert
 Premiumdaten kostenpflichtig
 Keine Einschränkungen
https://fantasydata.com
Beispiel NFL Daten

6. @OliverLemm@OliverLemm
 per „Start Free Trial“
Token erstellen
 2 Tokens
https://developer.fantasydata.com
Beispiel NFL Daten

7. @OliverLemm@OliverLemm
 API
 XML & JSON
https://developer.fantasydata.com
Beispiel NFL Daten

8. @OliverLemm@OliverLemm
 Name des Endpoint
 URL Endpoint
 hier „gesamte“ URL
 Parameter
 Alle Werte mit
“Doppelpunkt”
im Link
Modul erstellen
APEX Web Source Module

9. @OliverLemm@OliverLemm
 lokale Umgebung
 ACL Fehler „ORA-24247“
 apex.oracle.com
 „ohne“ zusätzliche ACL lauffähig
 cloud.oracle.com
 „ohne“ zusätzliche ACL lauffähig
 https://docs.oracle.com/database/apex-18.1/HTMIG/enabling-network-services-in-Oracle-
db11g-or-later.htm#HTMIG29160
Modul erstellen – ACL Fehler
APEX Web Source Modul

10. @OliverLemm@OliverLemm
 „re-run“ fähiges Skript
 Principal = „Schema“
 wenn „Web Source Modul“
oder „APEX_EXEC“
 Dann APEX Schema
APEX_180100
 wenn mittels anderer
Packages dann
Ausführungsschema
 HTTPS => Port: 443
ACL (11g/12c*) definieren
APEX Web Source Modul
declare
l_principal varchar2(100) := 'APEX_180100';
l_host varchar2(100) := 'api.fantasydata.net';
l_acl varchar2(100) := lower(l_principal) || lower(l_host) || '.xml';
l_port number := 443;
l_description varchar2(100) := 'Calling fantasydata REST Webservice';
begin
begin
dbms_network_acl_admin.drop_acl(acl => l_acl);
exception
when others then
null;
end;
dbms_network_acl_admin.create_acl(acl => l_acl
,description => l_description
,principal => l_principal
,is_grant => true
,privilege => 'connect'
,start_date => systimestamp
,end_date => null);
dbms_network_acl_admin.assign_acl(acl => l_acl
,host => l_host
,lower_port => l_port
,upper_port => l_port);
commit;
end;
/

11. @OliverLemm@OliverLemm
 Base URL
 Endpunkt unter dem
verschiedene Services
zusammengefasst werden
 „read only“ (beim Bearbeiten)
Modul erstellen – Base URL
APEX Web Source Modul

12. @OliverLemm@OliverLemm
 Ist für “Base URL” Bearbeitung
 Type: Web Source
 Type: Authentication
 Export nimmt in 18.1 Authentication
nicht mit => One-of Patch 28128115
 “Prompt on Install”
 Bei Runtime only
APEX_APPLICATION_INSTALL.SET
_REMOTE_SERVER
 liegt unter “Workspace Utilities”
Remote Servers
APEX Web Source Modul

13. @OliverLemm@OliverLemm
 Token <> Authentifizierung
Modul erstellen - Authentication
APEX Web Source Modul

14. @OliverLemm@OliverLemm
 Token als “HTTP Header” Variable
Modul erstellen - Parameters
APEX Web Source Modul

15. @OliverLemm@OliverLemm
 ORA-29273
 Zertifikat fehlt
Modul erstellen - Parameter
APEX Web Source Modul

16. @OliverLemm@OliverLemm
Zertifikat exportieren
APEX Web Source Modul

17. @OliverLemm
APEX Web Source Modul
17
Zertifikat importieren

18. @OliverLemm
APEX Web Source Modul
 Blogeintrag: APEX, HTTPS, Zertifikate und das Oracle Wallet
 APEX 18.1 Dokumentation
https://docs.oracle.com/database/apex-18.1/AEADM/configuring-instance-
settings.htm#GUID-BBE43F61-DA0B-4517-AC5E-D06C4C69D526
 Internal
 Manage Instance
 Instance Settings
 Wallet
Wallet nutzen

19. @OliverLemm@OliverLemm
 Data Profile
 Bearbeiten von Dateneigenschaften
 Operationen
 Neben GET können auch POST, PUT,
DELETE oder PATCH als Operationen zu
einem Service definiert werden
 Credentials
 Statische oder Dummy
Authentifizierungsparameter
 Parameter
Übersicht
Web Source Modul

20. @OliverLemm@OliverLemm
 Caching pro WebSource
Modul
 Achtung beim Testen
Caching
Web Source Modul

21. @OliverLemm@OliverLemm
Data Profile
Web Source Modul

22. @OliverLemm@OliverLemm
 Spalte mit “falschen” Datumsformat im JSON
 Spalte im Web Source Modul erzeugt auch Fehler wenn diese nicht im Report
aufgenommen wurde
 Fehler erscheint so lange Datentyp nicht korrekt gemappt wird.
 Achtung “automatisches identifizieren” liegt auch mal falsch
Fehler
Web Source Modul

23. @OliverLemm@OliverLemm
Data Profile
Web Source Modul

24. @OliverLemm@OliverLemm
 Lesender Zugriff
 Interactive Report
 SQL Report
 Charts
 Region Plugins
https://blogs.oracle.com/apex/apex-181-early-adopter-2-rest-services-and-plug-ins
 Schreibender Zugriff
 momentan nicht unterstützt (Interactive Grid wird auch im lesenden Zugriff nicht unterstütz
(deklarative) Unterstützung
Komponenten erstellen

25. @OliverLemm@OliverLemm
Synchronize Columns
Komponenten erstellen

26. @OliverLemm@OliverLemm
 vorher wenn möglich REST Abfrage
selber zum Filtern nutzen
 mögliche Filter
 Where/Order By Clause
 SQL Query
 PL/SQL Body returning SQL Query
Local Post Processing
Komponenten erstellen

27. @OliverLemm@OliverLemm
 Fehler der zu nutzenden API möglich
 Key abgelaufen/nicht gültig
 Key fehlt
 Beschränkung im Limit
Fehler
Web Source Modul
{
"message": "API rate limit exceeded for 188.111.4.162. (But here's the good news:
Authenticated requests get a higher rate limit. Check out the documentation for more details.)",
"documentation_url": "https://developer.github.com/v3/#rate-limiting"
}

28. @OliverLemm@OliverLemm
Beispiel Einbindung Atlassian Jira

29. @OliverLemm@OliverLemm
 Name des Endpoint
 allgemeine Informationen: „MT Jira“
 Version: „latest“
 Welche Daten: „Projects“
 Einschränkung: „key“
 URL Endpoint
 enthält die „gesamte“ URL
Modul erstellen – URL Endpoint
APEX Web Source Module - Jira

30. @OliverLemm@OliverLemm
 ein User “statisch”
 zum Testen perfekt
 Authentication Type
 Basic Authentication
 OAuth2
 Wird kein Username &
Passwort übermittelt
=> Unauthorized (401)
Modul erstellen - Authentication
APEX Web Source Modul - Jira

31. @OliverLemm@OliverLemm
 Shared Components
 Security
 Web Credentials
“statisch”
Web Credentials - Jira

32. @OliverLemm@OliverLemm
 Web Source Modul initial mit “gültigen”
Authentifizierungsparametern anlegen
 Spalten identifizieren “Re-Discover”
 Web Source Modul Credentials auf “Dummy ändern”
 Aufruf von PL/SQL mit Eingaben des Endusers
dynamisch
Web Credentials - Jira
apex_credential.set_session_credentials(p_credential_static_id => 'DUMMY_JIRA',
p_username => :P6_USERNAME,
p_password => :P6_PASSWORD);

33. @OliverLemm@OliverLemm
Pagination & Sortierung per REST
REST - Jira - JQL
 Information zu Anzahl Zeilen im Response enthalten
 Default werden maximal 50 Einträge zurückgeliefert
 1. Lösung: parameter &maxResults=XXX
 2. Lösung: Parameter &startAt=50
 Sortierung
 Wenn möglich jede Datenfilerung per REST definieren, damit die Performanz optimal ist.
"expand":"schema,names","startAt":0,"maxResults":50,"total":827,"issues":[….]}
https://jira.mt-ag.com/rest/api/latest/search?jql=project=BP&maxResults=1000
https://jira.mt-ag.com/rest/api/latest/search?jql=project=BP&startAt=50
https://jira.mt-ag.com/rest/api/latest/search?jql=project=BP+order+by+duedate

34. @OliverLemm@OliverLemm
https://apex.mt-ag.com/en/websourceslibrary
Web Sources Library by MT AG

35. @OliverLemm@OliverLemm
Web Source Modules
Web Sources Library by MT AG

36. @OliverLemm@OliverLemm
 Einbindung von Oracle Datenbanken ohne
Datenbanklink
 Zieldatenbank muss per ORDS angesprochen
werden
 Es wird immer ein HTTP Post gemacht
 Caching über Region definierbar
 For All Users
 By User
 By Session
Remote SQL

37. @OliverLemm@OliverLemm
 Global Constants
 Data Types
 ADD_COLUMN Procedure
 ADD_FILTER Procedure
 ADD_ORDER_BY Procedure
 ADD_PARAMETER Procedure
 CLOSE Procedure
 EXECUTE_PLSQL Procedure
 EXECUTE_REMOTE_PLSQL Procedure
 EXECUTE_WEB_SOURCE Procedure
APEX 18.1 API - APEX_EXEC
APEX API – APEX_EXEC
 GET_COLUMN Function
 GET_COLUMN_COUNT Function
 GET_COLUMN_POSITION Function
 GET_PARAMETER Functions
 GET_TOTAL_ROW_COUNT Function
 IS_REMOTE_SQL_AUTH_VALID Function
 NEXT_ROW Function
 OPEN_REMOTE_SQL_QUERY Function
 OPEN_QUERY_CONTEXT Function
 OPEN_WEB_SOURCE_QUERY Function
 PURGE_WEB_SOURCE _CACHE Procedure

38. @OliverLemm@OliverLemm
 About the APEX_WEB_SERVICE API
 Invoking a SOAP Style Web Service
 Invoking a RESTful Style Web Service
 Retrieving Cookies and HTTP Headers
 Setting Cookies and HTTP Headers
 BLOB2CLOBBASE64 Function
 CLOBBASE642BLOB Function
 MAKE_REQUEST Procedure
 MAKE_REQUEST Function
 MAKE_REST_REQUEST Function
 MAKE_REST_REQUEST_B Function
APEX 18.1 API - APEX_WEB_SERVICE
APEX API - APEX_WEB_SERVICE
 OAUTH_AUTHENTICATE Function
 OAUTH_GET_LAST_TOKEN Function
 OAUTH_SET_TOKEN Function
 PARSE_RESPONSE Function
 PARSE_RESPONSE_CLOB Function
 PARSE_XML Function
 PARSE_XML_CLOB Function

39. @OliverLemm@OliverLemm
Packaged App
Sample REST Services

40. Oliver Lemm
Telefon: +49 2102 30961 – 0
oliver.lemm@mt-ag.com
@OliverLemm