Service Paths

Overview

A service path is a standard REST paradigm that desceribes the mechanism of a REST endpoint of an Object Service to efficiently retrieve associated objects. The association or “query condition” is part of the URL. Generally the last segment of the URL will be the object (data) to be returnd. The concept of service paths is best explained by example(s) as depicted in on this page.

URL Structure

Overall a service path has the following URL notation:

Open

Example: Retrive all students at the school with the school ID of ABC.

URL: HTTP GET .../schools/ABC/students

In the above example the “schools” segement indicates the associated object, the “ABC” segment is the unique id of the associated object and the last segment (students) indicates the objects to be returned. The “query” this service path represents can be expressed as “return all students with an enrolment at a school where schoolId = ABC”.

Nested Service Paths

Servcie paths can be nested. Each nesting level is a sub-query of the previous nesting level (query). For example the following service path will return daily attendances for a given student (student ID = 456) at a given school (school ID = ABC): HTTP GET .../schools/ABC/students/456/dailyAttendances

HTTP Headers

It is important to note that a consumer MUST provide the HTTP header “serviceType=SERVICEPATH” in the request to ensure correct routing of the request. This HTTP header will indicate to the Service Provider that the request is not a standard object service request but a service path request.

Other URL parameters and HTTP Headers

As with a standard object service requests, service path requests can carry zone and context matrix parameters. Service Paths request also allow “paging” and paging related HTTP Headers or URL query parameters (i.e. navigationPage, navigationPageSize).

ACL in SIF Environment

Service paths are considered a separate service type and therefore need to be listed separately in a consumer’s or provider’s environment ACL. The service notation/name of a service path must follow the convention associateObjectName/{}/returnedObjectName. Note the ‘{}’ brackets. They indicate the place holder for the ID of the associated object during runtime (when a request is issued by a service conumser). The service type must be set to “SERVICEPATH”.

Service Consumer:

Because service paths are “Queries” the “QUERY” right must be set to “APPROVED” in the consumer’s environment to enable access to a specific service path (example: enable the “student at school” service path):

Service Provider

The Service Provider is the provider of service paths and therefore must have the “PROVIDE” right set to “APPROVED” in the providers’s environment to enable it to respond to specifc service path requests (example: enable the “student at school” service path):

Constraints

• Service Paths may only be used in Query Requests.  A Service Path cannot be used to create, update or delete data.

• Service Paths do not post Events and cannot be subscribed to.