Presented by: SIF 3.0 REST Services Melbourne Developer’s Workshop November 2013 Joerg Huber
© Systemic Pty Ltd November 2013 Melbourne MCG: SIF 3.0 REST URL Structure 2 Components of SIF3 REST Call A SIF3 REST Call can consist of the following parts: Base URL Segment Service ULR Segment Matrix Parameters Query Parameters Header Fields Payload Single-Object vs. Multi-Object URLs
© Systemic Pty Ltd November 2013 Melbourne MCG: SIF 3.0 REST URL Structure 3 Base URL Segment Retrieved from the “infrastructureService” node with the name “requestConnector” in environment Example
© Systemic Pty Ltd November 2013 Melbourne MCG: SIF 3.0 REST URL Structure 4 Service URL Segment Generally the name of the SIF Object in plural form (append “s”) Optionally append ‘Id’ of SIF Object or Optionally append singular form of SIF Object Name Example - StudentPersonal /StudentPersonals /StudentPersonals/ /StudentPersonals/StudentPersonal
© Systemic Pty Ltd November 2013 Melbourne MCG: SIF 3.0 REST URL Structure 5 Matrix Parameters Used instead of Query Parameters because they help in standard caching: If no ‘?’ (Query Parameter) is used in URL the result can be cached Matrix Parameters don’t use the ‘?’ but are part of the URL so the data returned can be cached Notation: ‘; = ’ Used in SIF3 to set the zone and context in a URL If not provided: Default Zone and/or Context is used Example - StudentPersonal /StudentPersonals;contextId=current /StudentPersonals/ ;zoneId=4001 /StudentPersonals;zoneId=4001;contextId=current
© Systemic Pty Ltd November 2013 Melbourne MCG: SIF 3.0 REST URL Structure 6 Query Parameters Everything after a ‘?’ in the URL is referred to as Query Parameter. Returned data is not cached Notation: ‘? = {& = }’ Used in SIF3: Paging Info, xQuery Info Example - StudentPersonal /StudentPersonals?pageSize=10&page=2 /StudentPersonals;zoneId=4001?pageSize=10&page=2
© Systemic Pty Ltd November 2013 Melbourne MCG: SIF 3.0 REST URL Structure 7 Header Fields SIF3 uses standard and custom HTTP Request/Response header fields. Not part of the URL Different header fields for Request and Response Example Standard Header Fields - Request Authorization (authorisation token) If-None-Match (caching info) Example Custom Header Fields - Request generatorId (Optional: Who makes request) navigationId (query paging support)
© Systemic Pty Ltd November 2013 Melbourne MCG: SIF 3.0 REST URL Structure 8 Payload The final part of a SIF3 REST Service call is the actual payload or the XML Message. Payload is XML for now (JSON later) Most requests for REST Calls have a payload Some Request don’t have a payload (DELETE for single object) Most responses for single-object operations don’t have a payload. Exception: GET Responses for multi-object operations do have a payload.
© Systemic Pty Ltd November 2013 Melbourne MCG: SIF 3.0 REST URL Structure 9 Single-Object vs Multi-Object URLs Single Object URLs: s GET: /StudentPeronals/{refId} s PUT: /StudentPeronals/{refId} + payload s DELETE: /StudentPeronals/{refId} EXCEPTION: CREATE an Object! s POST: /StudentPeronals/StudentPersonal + payload Multi-Object URLs: s GET: /StudentPeronals s PUT: /StudentPeronals + payload s POST: /StudentPeronals + payload s DELETE: /StudentPeronals + payload
© Systemic Pty Ltd November 2013 Melbourne MCG: SIF 3.0 REST URL Structure 10 Question Time… Questions?