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 Page 2

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 authenticate and authorize user

Local filestore, Admin user needs role „SQLDeveloper“

► RESTcomponents▪  Modules

−  ResourceTemplates

−  Methods/Handlers(GET,PUT,POST,DELETE)

RESTDefini;onsModules,RessourceTemplatesandHandlers

► 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

ModifyressourcesusingPOST,PUTandDELETE

► Createanewressource(POST)

► Updatearessource(PUT)

► Deletearessource(DELETE)

UseCasesModifyressourcesusingPOST,PUTandDELETE

► 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

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

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;

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>

► 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

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-

► 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

pretius oracle apex primer

oracle apex 5

meetup oracle apex latinoamÉrica

oracle application -...

tabs with oracle apex

oracle apex oam integration

running oracle forms from apex

oracle ords – quickstart für entwickler · oracle ords...

minilesson oracle apex 2_2

qué es oracle apex

oracle ords 101 - jumpstart your development · oracle ords...

apex day 1.0 oracle apex 5.0 patrick wolf

oracle apex installation guide

apex feature requests board -...

oracle apex & phonegap

manual de uso - oracle apex

on openvms –running oracle apex - gtug · 2018-05-18 ·...

apex 19.2 new features - oracle€¦ · oracle jet and...

oracle application express (apex) for e-business suite ......

oracle apex urls untangled & seoptimized