Oracle ORDS 101 - Jumpstart your Development · 1.0 2010 First release as Oracle APEX Listener with...

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

02.02.2016 Oracle ORDS 101 - Jumpstart your Development

DietmarAust


► 2015DatabaseDeveloperoftheyearintheORDScategory▪  PrimarilyformyknowledgeregardingORDSasthepla_ormtechnologyforAPEX▪  RESTfulServiceswithORDSares;llrela;velynew–buttheyhavegreatpoten;al

andwillgaininimportance


Agenda

► WhatisREST?

► WhatisORDS?▪  ComponentsandArchitecture

► ManagementoftheRESTdefini;onswithSQLDeveloperandtheAPI

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

► Security▪  Authen;ca;onandAuthoriza;on

► Addi;onalReading

► TheslidesandthedemoscriptwillbeavailablefromOGh.nlwebsiteandalsoonmyblog:h\p://daust.blogspot.de

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

► 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

► InwhichrepositorydoIcreatethewebservice?

► APEXREST▪  Integra;onwithAPEXSession

► ORDS_METADATAREST▪  ThenewRESTfunc;onalitybasedonthenewmetadatarepository▪  PL/SQLAPIs(defineandoauth)

► TheFuture?▪  NewfeatureswillonlybeaddedtoORDS_METADATAREST



► Currentlythedocumenta;ondoesn’talwaysclearlydis;nguishbetweenAPEXRESTandORDS_METADATAREST.

► Thusthesamplesinthedocumenta;onandontheinternetaremixed….buttherearesmallfunc;onaldifferences!

► 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

► MapandBind:

▪  ImplicitlyaccessallURIparametersintheURLorinthebody(e.g.POSTrequest)−  Happensautoma;cally,evenJSONParameters(usingContent-Type:

applica;on/json)

▪  Explicitparameterspossible▪  Accessheadervariables



► TransformtoJSON

▪  ReturnJSONbyusingbindvariables(declara;vely)orcreatetheJSONmanuallyyourself

▪  Declara;veFormats:JSONorCSV,manuallyyoucancreateanything▪  Canchangetheh\preturncodeorseth\pheadervariables



► Connec;onPooling▪  ThetargetOracleuser(schema)isac;vatedusingaProxyConnect▪  TheuserORDS_PUBLIC_USERconnecttothedatabaseandthenswitchesitsiden;tyto

thetargetOracleuser▪  Thusweneedfewerconnec;onpoolsandeachconnec;onpoolbecomessmallersince

mul;pleOracleuserscanbeservedwiththesameconnec;onpool▪  EachSQLandPL/SQLstatementisexecutedusingthetheoriginalusersession



► Connec;onPooling▪  EasiertodealwiththanwithAPEX,sincewithAPEXthesessionuserwillbe

APEX_PUBLIC_USER,NOTtheparsingschema




ManagementoftheRESTdefini;onswithSQLDeveloperandtheAPI

► ManagementoftheRESTdefini;onswithSQLDeveloper

RESTDefini;onsManagementwithSQLDeveloper



► Createuseroncommandline



Schema/Workspace will decide between APEX REST and ORDS REST

##UsertomanageRESTdefinitionsinSQLDeveloperjava-jarords.waruserdietmar.aust"SQLDeveloper”




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“

► 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


► Handler–types▪  SQLQuery(legacy)(source_type_query)▪  SQLQuery(eineZeile)(legacy)(source_type_query_one_row)▪  Collec;on(source_type_collec;on_feed)▪  Collec;onItem(source_type_collec;on_item)▪  Feed(source_type_feed)▪  PL/SQL(source_type_plsql)

−  Generateeverythingmanuallymyself

▪  Media(source_type_media)−  Binaryrepresenta;ons

RESTDefini;onsHandler-Types


► Handler–Typ:SQLQuery(legacy)(source_type_query)▪  Containsalinktoitself

RESTDefini;onsHandler-Typen


selectemp.*fromemp

► Handler–TypSQL:SQLQuery(onerow)(legacy)(source_type_query_one_row)



selectemp.*fromempwhereempno=:empno

► Handler–TypSQL:Collec;on(source_type_collec;on_feed)

► Completeincl.naviga;onlinks:▪  Self▪  Describedby▪  First(onlybypagina;onorlimit)▪  Next(onlybypagina;onorlimit)▪  Previous(onlybypagina;onorlimit)



selectemp.*fromemp

► Handler–TypSQL:Collec;onItem(source_type_collec;on_item)▪  Containsalinktothecollec;onitself



selectemp.*fromempwhereempno=:empno

► Handler–TypSQL:Feed(source_type_feed)



selectemp.*fromemp


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

ModifyressourcesusingPOST,PUTandDELETE

► Createanewressource(POST)

► Updatearessource(PUT)

► Deletearessource(DELETE)

UseCasesModifyressourcesusingPOST,PUTandDELETE


Demo

► RendereverythingmanuallywithPL/SQLyourself▪  GETwithTypPL/SQL▪  UseOWAToolkittowriteitout

−  APEX_JSON,PL/JSON

−  12cJSONFunk;onen

UseCasesPL/SQLHandler–implementeverythingyourself


► Displayanimage▪  GEThandler(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


► Inputparameters▪  Implicit

−  AllvariablesthatarepassedintheURLorinthecontentbody

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

−  :body(alsBLOB)

▪  Explicit(usingdeclatra;veparameters)−  Allregularh\pheadervariables

−  AllvariablesthatarepassedintheURLorinthecontentbody

UseCasesParameter


► Outputparameters▪  Explicit(usingdeclatra;veparameters)

−  Returnaresponsebyseyngasimplebindvariablewhichisthenconvertedautoma;callytoJSONbyORDS

−  Setanh\pResponseCode(Pseudo-Header:X-APEX-STATUS-CODE),e.g.201,403

−  RedirecttoadifferentURL(Pseudo-Header:X-APEX-FORWARD)

−  Setah\pheadervariable

UseCasesParameter



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/

hgmloofddffdnphfgcellkdzzjeloo

► 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-res_ul-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://res_ul-api-design.readthedocs.org/en/latest/intro.html▪  h\p://blog.mwaysolu;ons.com/2014/06/05/10-best-prac;ces-for-be\er-res_ul-

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.ie_.org/html/rfc2616

► URIspec:h\p://tools.ie_.org/html/rfc3986

► JSONformat:h\p://json.org/

WeitereInforma;onsquellen


1-DayDeveloperWorkshopORDS► InCologneinJune(inGerman)

► OnlineasafulldaywebinarinJuly(inEnglish)

► Topics▪  Setup/configura;onforAPEX/mod_plsqlandREST▪  RealWorldproject(morecomplexexamples)▪  Differentusecaseswithlotsofhands-ons▪  Authen;ca;onusingWLS,GlassfishandTomcat▪  OAUTH2flowimplementa;on

1-DayDeveloperWorkshop


Contact


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

Oracle ORDS 101 - Jumpstart your Development · 1.0 2010 First release as Oracle APEX Listener with...

Documents

Transcript of Oracle ORDS 101 - Jumpstart your Development · 1.0 2010 First release as Oracle APEX Listener with...