opal consulting – oracle apex knowhow seit 2006 ......added fop 2.0 2012 oauth2 support,...

OracleORDS101-JumpstartyourDevelopment

DietmarAustOpal-Consul;ng,Kölnwww.opal-consul;ng.de

► 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

DietmarAust


► 2015DatabaseDeveloperoftheyearintheORDScategory


Agenda

► WhatisREST?

► WhatisORDS?▪  ComponentsandArchitecture

► ManagementoftheRESTdefini;onswithSQLDeveloperandtheAPI

► UseCases▪  Naviga;on/Links/Filter/Sor;ng/Parameter(Input/Output)

► Security▪  Authen;ca;onandAuthoriza;on

Agenda



WhatisREST?

► 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


► 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


► Methodsimplementaspecificopera;on▪  Uniformopera;onsforallressources▪  GET,POST,PUT,DELETE,OPTIONS,HEAD

► Weuseveryfewverbstooperateonmanydifferentnouns.

WhatisREST?Methods


► Communica;onofsuccessanderrormessagesthroughstandardHTTPResponsecodes1xx,2xx,3xx,4xx,5xx▪  h\p://www.restapitutorial.com/

h\pstatuscodes.html#

WhatisREST?Methods


► 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



WhatisORDS?

► OracleRestDataServices(ORDS)▪  MiddlewareJ2EEcomponentinthe

applica;onserver(WLS,Glassfish,Tomcat)▪  TranslatesURLsintoacallinthedatabase

(eitherselectorstoredprocedurecall)

► Threemajorusecases▪  SupportforOWAtoolkitapplica;ons(will

replacemod_plsql)▪  OracleApplica;onExpress(APEX)▪  RESTfulWebservices

WhatisORDS?


WhatisORDS?TheHistory


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


► 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



► 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



► HowisaRESTwebservicecallactuallyprocessed?

WhatisORDS?Architecture


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



ManagementoftheRESTdefini;onswithSQLDeveloperandtheAPI

► ManagementoftheRESTdefini;onswithSQLDeveloper

RESTDefini;onsManagementwithSQLDeveloper





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“


► Createuseroncommandline



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



Demo

► 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


► 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


► ResourceTemplate–Type:SQLQuery(legacy)(source_type_query)▪  Containsalinktoitself



selectemp.*fromemp

► ResourceTemplateType:SQLQuery(onerow)(legacy)(source_type_query_one_row)



selectemp.*fromempwhereempno=:empno

► ResourceTemplate–TypeSQL:Feed(source_type_feed)



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)



selectemp.*fromemp

► ResourceTemplate–TypeSQL:Collec;onItem(source_type_collec;on_item)▪  Containsalinktothecollec;onitself



selectemp.*fromempwhereempno=:empno


UseCases

Firststep:EnableRESTcapabili;esforaschemainthedatabase

► UsingtheGUI(right-clickontheconnec;on)

► Usingthecommandline/API

UseCasesEnableRESTinSchema


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



Demo

► Inputparameters▪  Implicit

−  AllvariablesthatarepassedintheURLorinthecontentbody

−  :content_type(varchar2,z.B.applica;on/json)

−  :body(alsBLOB)

▪  Explicit(usingdeclatra;veparameters)−  Allregularh\pheadervariables

−  AllvariablesthatarepassedintheURLorinthecontentbody

UseCasesParameter


► 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


ModifyressourcesusingPOST,PUTandDELETE

► Createanewressource(POST)

► Updatearessource(PUT)

► Deletearessource(DELETE)

UseCasesModifyressourcesusingPOST,PUTandDELETE


Demo

► RendereverythingmanuallywithPL/SQLyourself▪  GETwithTypPL/SQL▪  UseOWAToolkittowriteitout

−  APEX_JSON,PL/JSON

−  12cJSONFunk;onen

UseCasesPL/SQLResourceTemplate–implementeverythingyourself


► Displayanimage▪  GETresourcetemplate(typeMediaressource)

UseCasesMedia-Ressourcen


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


► 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



Demo


Security

► 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


► Authoriza;on:=Protectaccesstoressourcesforcertainuserroles

► CreateaROLEfirst(onlypossiblethroughtheAPI)

► CreateaprivilegetoprotectafullmoduleorjustaURIpa\ern

► Cannotrequireprotec;onjustforaspecificmethod,e.g.limitaccesstoPUT,POST,DELETEandallowGETforeverybody.▪  Perhapsusingtwomodules:

−  /public/departments/(implementGEThandler)

−  /protected/departments/(implementPOST,PUT,DELETEhandler)

Security


Security



Demo


Auto-REST

QuicklyAuto-RESTenableadatabasetableorview

► Pros:▪  Fastandeasy▪  CandosomecleverthingsusingINSTEAD_OFtriggersontheview

► Cons:▪  Can’tusetheauthen;cated:current_uservariabletofigureouttheuseriden;ty

whichisrequiredforloggingpurposes

Auto-REST


EnableRESTcapabili;esforatableorview

► UsingtheGUI(right-clickonthetable/view)▪  „EnableRESTService“

► Usingthecommandline/API

UseCasesEnableRESTinSchema


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;


Demo


Debugging/Troubleshoo;ng

► 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


<entrykey="debug.debugger">true</entry><entrykey="debug.printDebugToScreen">true</entry>


Tools

► 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



FurtherReading

► 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


► 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


Contact


DietmarAustOpal-Consul;ng,Kölnwww.opal-consul;ng.dedaust.blogspot.comdietmar.aust@opal-consul;ng.de

opal consulting – oracle apex knowhow seit 2006 ......added fop 2.0 2012 oauth2 support,...

Documents