Service Paths & Query By Example (QBE): Query Mechanism SIF 3 Service Paths & QBE Service Paths & Query By Example (QBE): Query Mechanism Joerg Huber

Service Paths What is a Service Path? Base URL Format & Components Other URL Components Limitations How do the Frameworks work with Service Paths? Consumer Provider Training Course SIF3: Service Paths September 18

What is a Service Path It is a Query Mechanism! Allows retrieval of ‘Associated’ Objects (i.e. All Students at a School) Standard REST paradigm Optimises data retrieval One query vs. many queries Standard notation, easy to read Query condition is part of the URL. Training Course SIF3: Service Paths September 18

Base URL Format & Components Example: Get Students at School <baseURL>/xSchools/<refId>/xStudents Association Object RefId of the School Object to be returned Query Condition: ‘where SchoolRefId = <refid>’ Training Course SIF3: Service Paths September 18

Other URL Components etc. Service Paths support all standard URL components of any Object Service: Can be ‘nested’ …/xSchools/<refId>/xStudents/<refId>/xDailyAttendances Above will return daily attendances for a given student at a given school. Matrix Parameters (zoneId, contexId) Query Parameters (navigationPage, navigationPageSize) HTTP Headers (requestId) Exception: serviceType = SERVICEPATH No Payload Not valid for HTTP GET! Training Course SIF3: Service Paths September 18

Limitations: Query Only Can only Query Data (HTTP GET). No create, update or delete No Events are sent to a Service Path Only available right in ACL will be “QUERY” HTTP Header ‘serviceType’ must be set to ‘SERVICEPATH’ Not to worry about if frameworks are used. Training Course SIF3: Service Paths September 18

Frameworks & Service Paths Available in Java & .Net version Consumer: Part of Abstract Consumer consumer.retrieveByServicePath(…) Provider: Implement QueryProvider Interface Direct Environment Template Entry <service name=“xSchools/{}/xStudents" type="SERVICEPATH"> <rights> <right type="QUERY">APPROVED</right> </rights> </service> Implemented by class of “Object to be Returned” Training Course SIF3: Service Paths September 18

What is Query By Example It is a Query Mechanism! Allows retrieval of Objects based on a ‘Sample Object’. Service of “Sample Object” serves the query. Query Condition is given by a standard SIF Object: <xStudent> <name> <type>LegalName</type> <familyName>Jones</familyName> </xStudent> => Give me all students with legal family name of Jones. Training Course SIF3: Service Paths September 18

What is Query By Example cont. Payload and Query Condition Interpretation: Each element in the payload forms a specific query condition. The conjunction between the conditions is 'AND‘. Comparator for all types except strings is EQUAL. Strings have a LIKE with the only supported wildcard of '%': 'ABC': No wildcards in the value is equivalent to an 'EQUAL'. '%ABC': Wildcard at the start of the value means 'ENDS IN'. In this case anything that ENDS IN 'ABC'. 'ABC%': Wildcard at the end of the value means 'STARTS WITH'. In this case anything that STARTS WITH 'ABC'. '%ABC%': Wildcard at the start and end of the value means 'CONTAINS'. In this case anything that CONTAINS 'ABC'. 'AB%C': Wildcard anywhere in the value means 'STARTS WITH' and 'ENDS IN'. In this case anything that STARTS WITH 'AB' followed by any number of characters and ENDS IN 'C' Training Course SIF3: Service Paths September 18

URL Components, GET vs. POST. QBE supports all standard URL components of any Object Service: Matrix Parameters (zoneId, contexId) Query Parameters (navigationPage, navigationPageSize) HTTP Headers (requestId, generatorID etc.) BUT it has a Payload!! Not valid for HTTP GET! It uses a HTTP POST with HTTP Header of methodOverride=GET => Abstracted with SIF3 Frameworks. Training Course SIF3: Service Paths September 18

Frameworks & Service Paths Available in Java & .Net version Consumer: Part of Abstract Consumer consumer.retrieveByQBE(…) Provider: Implement QueryProvider Interface If not supported then throw UnsupportedQueryException. ACL: Direct Environment Template Entry Part of standard Object Service (no changes) “QUERY” right must be “APPROVED”. <rights> <right type="QUERY">APPROVED</right> </rights> Training Course SIF3: Service Paths September 18

Exercise 6: Service Path Question Time… Questions? Exercise 6: Service Path (Consumer & Provider) Training Course SIF3: Service Paths September 18