Post on 27-Mar-2020
► Dipl.-Inform.DietmarAust,FreelanceConsultant▪ Master'sDegreeinComputerScience(MSCS)
► BuildingOraclebasedWebApplica;onssince1997▪ Portal,Forms,Reports,OWAToolkit,nowAPEX!
► 1997-2000:ConsultantatOracleGermany
► Since09/2000:FreelanceConsultant,Since2006–APEXonly!
► Blog:h\p://daust.blogspot.com/
► RegularpresenteratOracleconferences(ODTUG,DOAG,OOW)
► AuthoroftheJasperReportsIntegra;ontoolkit▪ h\p://www.opal-consul;ng.de/tools
DietmarAust
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 3
DietmarAust
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 4
► 2015DatabaseDeveloperoftheyearintheORDScategory
► WhatisREST?
► WhatisORDS?▪ ComponentsandArchitecture
► ManagementoftheRESTdefini;onswithSQLDeveloperandtheAPI
► UseCases▪ Naviga;on/Links/Filter/Sor;ng/Parameter(Input/Output)
► Security▪ Authen;ca;onandAuthoriza;on
Agenda
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 6
► Itisanarchitecturalstyleforapplica;ons,neitheraprotocolnoraW3Cstandard
► REST:=Representa;onalStateTransfertermcoinedin2000byRoyFielding▪ h\ps://en.wikipedia.org/wiki/Representa;onal_state_transfer
► Characteris;cs:▪ Stateless(100%oftheapplica;onstateismanagedbytheclient)▪ Basedontheh\pprotocol▪ Highlyscaleable▪ RESTusesh\pmethods(POST,PUT,GET,DELETE,…)toimplementCRUD
opera;ons(Create/Read/Update/Delete)
► Why?▪ Lightweightalterna;vetoRPC(RemoteProcedureCalls)andotherWebServices
(SOAP,WSDL,…)▪ IncreasinglypopularthroughAPIsprovidedbyGoogle,Facebook,Twi\erand
others.
WhatisREST?Defini;on
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 8
► Ressourcesprovideservicesandareuniquelyiden;fyable▪ h\p://api.example.com/customers/▪ h\p://api.example.com/customers/1234▪ h\p://api.example.com/customers/1234/orders/
► Mul;pleURIscanpointtothesameressource:▪ h\p://example.org/NewOrleans/traffic/I10▪ h\p://example.org/traffic/NewOrleans/I10
► Wemodeltheressource,nottheac;on!▪ Useofnounsinpluralform▪ PUTh\p://example.com/accounts/12345▪ PUTh\p://example.com/accounts/edit/12345▪ POSTh\p://example.com/accounts/▪ POSTh\p://example.com/accounts/addaccount
WhatisREST?Ressources
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 9
► Methodsimplementaspecificopera;on▪ Uniformopera;onsforallressources▪ GET,POST,PUT,DELETE,OPTIONS,HEAD
► Weuseveryfewverbstooperateonmanydifferentnouns.
WhatisREST?Methods
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 10
► Communica;onofsuccessanderrormessagesthroughstandardHTTPResponsecodes1xx,2xx,3xx,4xx,5xx▪ h\p://www.restapitutorial.com/
h\pstatuscodes.html#
WhatisREST?Methods
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 11
► Representa;onsdeterminehowtheanswerwillbeinterpreted▪ XMLrepresenta;onusingmime-type:text/xml▪ JSONrepresenta;onusingmime-type:
applica;on/json
► Asingleressourcecanprovidemul;pledifferentrepresenta;ons▪ JSON,XML,CSV…▪ Therightrepresenta;onisac;vely„nego;ated“▪ Theclientsendsalistofpreferredmime-types–
theserverrespondswiththebestanswerandsendsthechosenmime-typeinthe„Content-Type“h\pheader.
WhatisREST?Representa;ons
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 12
► OracleRestDataServices(ORDS)▪ MiddlewareJ2EEcomponentinthe
applica;onserver(WLS,Glassfish,Tomcat)▪ TranslatesURLsintoacallinthedatabase
(eitherselectorstoredprocedurecall)
► Threemajorusecases▪ SupportforOWAtoolkitapplica;ons(will
replacemod_plsql)▪ OracleApplica;onExpress(APEX)▪ RESTfulWebservices
WhatisORDS?
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 14
WhatisORDS?TheHistory
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 15
Version Date Description
1.0 2010 First release as Oracle APEX Listener with with support for OWA toolkit used by APEX
1.1 2011 First release with REST support for JSON, Microdata, CSV, Pagination. Also added FOP
2.0 2012 OAuth2 support, Integrated with APEX, Multi Database, SQL Developer integration
2.0.5 2013 Added support for Oracle Pluggable Databases (12c)
2.0.6 2014 Renamed to Oracle REST Data Services to emphasize REST commitment, integration with APEX 4.2 in SQL Workshop
2.0.8 2014 Added REST Filtering
3.0.0 2015 REST AutoTable, NoSQL, DB12 JSON, Bulk loading over REST,…
ORDSiscurrentlytransi2oningawayfromthedependencyonAPEX
► ORDSrequiresarepositorytostorethewebservicedefini;ons
WhatisORDS?APEXRESTvs.ORDS_METADATARESTSupport
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 16
► ORDS2.0
► Schemas▪ APEX_040200/APEX_050000▪ APEX_LISTENER▪ APEX_REST_PUBLIC_USER
► Configurationusing▪ APEXSQLWorkshop▪ SQLDeveloper
► ORDS3.0
► Schemas▪ ORDS_METADATA▪ ORDS_PUBLIC_USER
► Configurationusing▪ SQLDeveloper▪ PL/SQLAPI
► APEXRESTsupportintheAPEXSQLWorkshop
WhatisORDS?APEXRESTvs.ORDS_METADATARESTSupport
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 17
► Twodifferentrepositories:APEXRESTandORDS_METADATAREST▪ TypicallybothareinstalledwhenusingAPEX5▪ APEX5requiresthatyourunapex_rest_config.sqlwhichcreatesAPEX_LISTENER
andAPEX_REST_PUBLIC_USER
► TheFuture?▪ NewfeatureswillonlybeaddedtoORDS_METADATAREST
► InwhichrepositorydoIcreatethewebservice?▪ APEXREST
− Integra;onwithAPEXSession
▪ ORDS_METADATAREST− Allnewfunc;onalityisaddedtothenewrepository(only!)
► Inthispresenta;onwewillfocusonthefeaturesavailableinORDS_METADATARESTSupportwithORDS3.0
WhatisORDS?APEXRESTvs.ORDS_METADATARESTSupport
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 18
► HowisaRESTwebservicecallactuallyprocessed?
WhatisORDS?Architecture
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 19
http://myhost/ords/employees/7536SELECT*FROMEMPWHEREEMPNO=:b1
Oracle DB
3. SQL Call over JDBC
Browser
1. Browser RESTful get request
2. ORDS maps to “EMPLOYEES” SQL
4. DB returns JDBC Results
5. JSON
ORDS Runs in WLS, Tomcat, Glassfish container
Oracle REST Data Services
► Connec;onPooling▪ ThetargetOracleuser(schema)isac;vatedusingaProxyConnect▪ TheuserORDS_PUBLIC_USERconnecttothedatabaseandthenswitchesitsiden;tyto
thetargetOracleuser▪ Thusweneedfewerconnec;onpoolsandeachconnec;onpoolbecomessmallersince
mul;pleOracleuserscanbeservedwiththesameconnec;onpool▪ EachSQLandPL/SQLstatementisexecutedusingthetheoriginalusersession
WhatisORDS?Architecture
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 20
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 21
ManagementoftheRESTdefini;onswithSQLDeveloperandtheAPI
► ManagementoftheRESTdefini;onswithSQLDeveloper
RESTDefini;onsManagementwithSQLDeveloper
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 22
► ManagementoftheRESTdefini;onswithSQLDeveloper
RESTDefini;onsManagementwithSQLDeveloper
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 23
Oracle REST Data Services
SQL Developer
http/https
APEX_050000
ORDS_METADATA
jdbc
jdbc authenticate and authorize user
Local filestore, Admin user needs role „SQLDeveloper“
► ManagementoftheRESTdefini;onswithSQLDeveloper
► Createuseroncommandline
RESTDefini;onsManagementwithSQLDeveloper
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 24
Schema/Workspace will decide between APEX REST and ORDS REST
##UsertomanageRESTdefinitionsinSQLDeveloperjava-jarords.waruserdietmar.aust"SQLDeveloper”
► RESTcomponents▪ Modules
− ResourceTemplates
− Methods/Handlers(GET,PUT,POST,DELETE)
RESTDefini;onsModules,RessourceTemplatesandHandlers
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 25
► ManagementthroughthePL/SQLAPI
► Simplefile…containsallresourcetemplatesandmethodsforamoduleinasingleplace
► Firstwedeletetheexis;ngdefini;onandthenwerecreateitfromscratch
► Verywellsuitedforscriptbaseddeployment
► APIreference(PackageORDS):h\p://docs.oracle.com/cd/E56351_01/doc.30/e56293/ords_ref.htm#AELIG90180
► UsePackageORDSinsteadofORDS_SERVICESinthefuture!!!
RESTDefini;onsManagementthroughtheAPI
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 27
► ResourceTemplate–types▪ SQLQuery(legacy)(source_type_query)▪ SQLQuery(onerow)(legacy)(source_type_query_one_row)▪ Feed(source_type_feed)▪ Collec;on(source_type_collec;on_feed)▪ Collec;onItem(source_type_collec;on_item)▪ PL/SQL(source_type_plsql)
− Generateeverythingmanuallymyself
▪ Media(source_type_media)− Binaryrepresenta;ons
RESTDefini;onsResourceTemplate-Types
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 28
► ResourceTemplate–Type:SQLQuery(legacy)(source_type_query)▪ Containsalinktoitself
RESTDefini;onsResourceTemplate-Types
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 29
selectemp.*fromemp
► ResourceTemplateType:SQLQuery(onerow)(legacy)(source_type_query_one_row)
RESTDefini;onsResourceTemplate-Types
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 30
selectemp.*fromempwhereempno=:empno
► ResourceTemplate–TypeSQL:Feed(source_type_feed)
RESTDefini;onsResourceTemplate-Types
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 31
selectemp.*fromemp
► ResourceTemplate–TypeSQL:Collec;on(source_type_collec;on_feed)
► Completeincl.naviga;onlinks:▪ Self▪ Describedby▪ First(onlybypagina;onorlimit)▪ Next(onlybypagina;onorlimit)▪ Previous(onlybypagina;onorlimit)
RESTDefini;onsResourceTemplate-Types
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 32
selectemp.*fromemp
► ResourceTemplate–TypeSQL:Collec;onItem(source_type_collec;on_item)▪ Containsalinktothecollec;onitself
RESTDefini;onsResourceTemplate-Types
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 33
selectemp.*fromempwhereempno=:empno
Firststep:EnableRESTcapabili;esforaschemainthedatabase
► UsingtheGUI(right-clickontheconnec;on)
► Usingthecommandline/API
UseCasesEnableRESTinSchema
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 35
BEGINORDS.ENABLE_SCHEMA(p_enabled=>TRUE,p_schema=>'ORDSTEST',p_url_mapping_type=>'BASE_PATH',p_url_mapping_pattern=>'ordstest',p_auto_rest_auth=>FALSE);COMMIT;END;
Implementnaviga;onlinkstonavigatebetweenthedifferentressources
► Linksusedfor:▪ Linktothecurrentrow▪ Linktoanimageoranembeddedlist(ressourceorderscancontainalisttothe
relatedorderitems)▪ Linktotheparent▪ Linktoother“siblings”usingrela;vepaths,e.g.../..
UseCasesNaviga;onandLinks
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 36
► Inputparameters▪ Implicit
− AllvariablesthatarepassedintheURLorinthecontentbody
− :content_type(varchar2,z.B.applica;on/json)
− :body(alsBLOB)
▪ Explicit(usingdeclatra;veparameters)− Allregularh\pheadervariables
− AllvariablesthatarepassedintheURLorinthecontentbody
UseCasesParameter
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 38
► Outputparameters▪ Explicit
− Returnaresponsebysewngasimplebindvariablewhichisthenconvertedautoma;callytoJSONbyORDS
− Setanh\pResponseCode(Pseudo-Header:X-APEX-STATUS-CODE),e.g.201,403oruseowa_u;l.set_status_line()(3.0.5andhigher)
− RedirecttoadifferentURL(Pseudo-Header:X-APEX-FORWARD)
− Setah\pheadervariable
UseCasesParameter
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 39
ModifyressourcesusingPOST,PUTandDELETE
► Createanewressource(POST)
► Updatearessource(PUT)
► Deletearessource(DELETE)
UseCasesModifyressourcesusingPOST,PUTandDELETE
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 40
Demo
► RendereverythingmanuallywithPL/SQLyourself▪ GETwithTypPL/SQL▪ UseOWAToolkittowriteitout
− APEX_JSON,PL/JSON
− 12cJSONFunk;onen
UseCasesPL/SQLResourceTemplate–implementeverythingyourself
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 41
► Displayanimage▪ GETresourcetemplate(typeMediaressource)
UseCasesMedia-Ressourcen
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 42
selectmimetype,product_imagefromdemo_product_infowhereproduct_id=to_number(:product_id)
► Pagina;on▪ Allowstopaginatethroughtheresultset▪ Onlyapplicableforhandlertypecollec;on(source_type_collec;on_feed)▪ h\p://docs.oracle.com/cd/E56351_01/doc.30/e56293/develop.htm#BABIHBDH▪ Pa\ern:GEThttp://<HOST>:<PORT>/ords/<SchemaAlias>/
<ObjectAlias>/?offset=<Offset>&limit=<Limit>▪ Alsocreatesthelinks“NEXT”,“PREVIOUS”und“FIRST”mit
► Example:
UseCasesPagina;on
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 43
► ResultSetFiltering▪ QuerySyntaxtofilteracollec;on▪ Onlyapplicableforhandlertypecollec;on(source_type_collec;on_feed)▪ h\p://docs.oracle.com/cd/E56351_01/doc.30/e56293/develop.htm#AELIG90104
► Sor;ng/OrderBy▪ QuerySyntaxtosortacollec;on▪ Onlyapplicableforhandlertypecollec;on(source_type_collec;on_feed)▪ h\p://docs.oracle.com/cd/E56351_01/doc.30/e56293/develop.htm#AELIG90104
UseCasesFilterandSort
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 44
► Differentwaysofauthen;ca;ngthecurrentuser▪ Authen;ca;onusingtheintegratedpasswordstore(“creden;als”file–just
recommendedfordevelopmentandtestenvironments)▪ Authen;ca;onusingtheapplica;onserver(authen;ca;onisdelegated,e.g.to
Glassfish)
► Authen;ca;onusingOAUTH2▪ Establishedstandard–usedwidely▪ Basicallycontrolsa“session”betweenclient/serverandyous;llneedto
authen;catewiththeappserver
► MoredetailstousingOAUTH2withORDS:Ar;clesfromCarstenCzarski(inGerman,butcanbetranslatedusingGoogleTranslator)▪ h\p://json-rest-oracledb.blogspot.de/2015/12/vorher-anmelden-bi\e-
authen;fizierung.html▪ h\p://json-rest-oracledb.blogspot.de/2016/01/ords-und-3-legged-oauth-so-
gehts.html
Security
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 47
► Authoriza;on:=Protectaccesstoressourcesforcertainuserroles
► CreateaROLEfirst(onlypossiblethroughtheAPI)
► CreateaprivilegetoprotectafullmoduleorjustaURIpa\ern
► Cannotrequireprotec;onjustforaspecificmethod,e.g.limitaccesstoPUT,POST,DELETEandallowGETforeverybody.▪ Perhapsusingtwomodules:
− /public/departments/(implementGEThandler)
− /protected/departments/(implementPOST,PUT,DELETEhandler)
Security
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 48
QuicklyAuto-RESTenableadatabasetableorview
► Pros:▪ Fastandeasy▪ CandosomecleverthingsusingINSTEAD_OFtriggersontheview
► Cons:▪ Can’tusetheauthen;cated:current_uservariabletofigureouttheuseriden;ty
whichisrequiredforloggingpurposes
Auto-REST
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 52
EnableRESTcapabili;esforatableorview
► UsingtheGUI(right-clickonthetable/view)▪ „EnableRESTService“
► Usingthecommandline/API
UseCasesEnableRESTinSchema
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 53
BEGINORDS.ENABLE_OBJECT(p_enabled=>TRUE,p_schema=>'ORDSTEST',p_object=>'DEPT',p_object_type=>'TABLE',p_object_alias=>'dept',p_auto_rest_auth=>FALSE);COMMIT;END;
► Displayerrormessagesdirectlyinthebrowser(onlyuseondevelopment/testenvironments,notproduc;on!)▪ Modifydefault.xml
► Fullloggingwithalldetailsusingjava.u;l.logging▪ h\ps://cdivilly.wordpress.com/2013/03/08/configuring-logging-in-oracle-
applica;on-express-listener-2-0-1/
Debugging/Troubleshoo;ng
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 56
<entrykey="debug.debugger">true</entry><entrykey="debug.printDebugToScreen">true</entry>
► Commandlinetool:curl-h\ps://curl.haxx.se/
► AdvancedRESTClient(forGoogleChrome)▪ h\ps://chrome.google.com/webstore/detail/advanced-rest-client/
hgmloofddffdnphfgcellkdyyjeloo
► PLSQLlogger▪ h\ps://github.com/OraOpenSource/Logger
Tools
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 58
► Slidestodownload:h\p://daust.blogspot.de
► Wikipedia:h\p://en.wikipedia.org/wiki/Representa;onal_State_Transfer
► REST–APIDesign▪ h\p://www.vinaysahni.com/best-prac;ces-for-a-pragma;c-reszul-api▪ h\ps://www.thoughtworks.com/de/insights/blog/rest-api-design-resource-
modeling▪ h\p://blog.octo.com/en/design-a-rest-api/▪ h\ps://reszul-api-design.readthedocs.org/en/latest/intro.html▪ h\p://blog.mwaysolu;ons.com/2014/06/05/10-best-prac;ces-for-be\er-reszul-
api/
► CarstenCzarskiBlogaboutREST:h\p://json-rest-oracledb.blogspot.de/(canbetranslatedusinggoogletranslator)
FurtherReading
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 60
► RESTfulWebServices,byLeonardRichardsonandSamRuby,availablefromO’ReillyMediaath\p://oreilly.com/catalog/9780596529260/
► Thesource:h\p://www.ics.uci.edu/~fielding/pubs/disserta;on/top.htmmostlychapters5and6
► Anice14minutevideointroduc;on:h\p://www.youtube.com/watch?v=YCcAE2SCQ6k
► HTTPspec:h\p://tools.iez.org/html/rfc2616
► URIspec:h\p://tools.iez.org/html/rfc3986
► JSONformat:h\p://json.org/
WeitereInforma;onsquellen
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 61
Contact
29.06.2016 Oracle ORDS 101 - Jumpstart your Development Page 62
DietmarAustOpal-Consul;ng,Kölnwww.opal-consul;ng.dedaust.blogspot.comdietmar.aust@opal-consul;ng.de