Service Paths

Owned by James Overell
Dec 15, 2017

From Base Architecture - SIF Specifications - A4L


Although the SIF Infrastructure is independent of the Data Model defining the payloads it carries, Service Paths are provided to optimise data retrieval for those Data Models which utilise “Associative” objects. Assume the following three objects: Student, Section and StudentSectionAssociation, the last of which might contain the RefId of a Student, the RefId of a Section and the information related to that Student’s association with that Section (such as the student’s attendance records and final grade for that section).
A common Consumer use case might be to retrieve all students for a given section who’s RefId is known. This might be done by:

  • Querying the StudentSectionAssociations collection for all associations with the given section RefId (1 query)
  • Examining each returned Association object to obtain its corresponding Student RefId.
  • Querying the Students collection for the Student object corresponding to each RefId (1 query per student in section)

In the case where there were 40 students in that section, this would require a total of 41 Queries. In a similar manner, obtaining all the Students in a School might require hundreds of individual Query requests. With Service Paths, the Consumer issues only a single Query in either case.

Service Paths in Query URLs

When used, the Service Path replaces the Service Object Name in the URL of a Query Request, and the Consumer never accesses the intermediate associative object. In the example above, the Service Path in the Query URL would look like:

../sections/1234/students

The Query Response would contain the collection of Student objects corresponding to the set of students enrolled in the section whose RefId was 1234. This single Query then provides the same Student data that would otherwise have required 41 queries to obtain. The exact same approach could be used to satisfy other common use cases. For example:

../students/5678/sections    → returns all the Section objects in which Student 5678 is enrolled
../schools/9012/students     → returns all the Student objects attending School 9012
../schools/9012/sections     → returns all the Section objects offered at School 9012

The following restrictions apply to Service Paths:

  • They may only be used in Query Requests. A Service Path cannot be used to create, update or delete data.
  • They do not post Events and cannot be subscribed to. In the above example, when an existing Student is added to a Section, the only Event published will be a Create Event, issued by the StudentSectionAssociations Object Provider.
  • They may “nest”. The following URL is legal and may be defined in a particular Data Model binding to the SIF 3 infrastructure: ../schools/9012/sections/1234/students, If successful, a query with this Service Path would return all Students for Section 1234 located in school 9012.

In all other respects, they are the equivalent of Service Names. This means a Service Path URL may be qualified by Context and Zone, and be combined with Paged Query HTTP Header fields and where clause URL Query parameters. What explicitly distinguishes a Service Path Query is that:

  • The URL segments may include one or more UUIDs, none of which is the last segment
  • The value of the “serviceType” HTTP Header Field is set to “SERVICEPATH”

Service Paths in the Provider Registry

If a Service Provider Registry is present, every supported Service Path within a given Environment must have an entry in that registry. This takes the form of

owningObjectName/{}/returnedObjectName

The “{}” is a placeholder for the RefId of the owning object that will be indicated in the actual Query URL as issued by the Consumer. To support the examples above would require the following Service Path entries in the Provider Registry:

sections/{}/students
students/{}/sections
schools/{}/students
schools/{}/sections

Any authorised Service Provider may provide a Service Path, although in general it will usually be the provider of the Association object.