Environment Service & API

1 Overview
- 1.1 Supported Operations
2 Components of a SIF Environment
- 2.1 XML Example
  - 2.1.1 Environment Type and ID
  - 2.1.2 Session Token & Fingerprint
  - 2.1.3 Authentication Method
  - 2.1.4 Default Zone
  - 2.1.5 Application Info
  - 2.1.6 Infrastructure Services (URLs)
  - 2.1.7 Provisioned Zones, Services and ACLs (rights)
3 Environment Endpoints

Overview

The Environment API is probably the most important API for any SIF Adapter. It is the one API that is most likely be used by an adapter for it to query what a specific SIF Adapter “can do”. A SIF Adapter can be a servcie consumer or a service provider. Each SIF Adapter has a specific SIF Environment assigned that provides the adpter with a list of URLs, services and access control lists (ACLs) for each service.

Supported Operations

The Environment service supports the operations listed below. Detailed Open API documentation of each endpoint of the Environment API can be found on the Open API page.

Operation Name	HTTP Verb	URL Segment	DELAYED Supported	Events Supported

Operation Name	HTTP Verb	URL Segment	DELAYED Supported	Events Supported
Create Single Environment	POST	environments/environment	No	No
Get Single Environment	GET	environments/{id}	No	No
Delete Single Environment	DELETE	environments/{id}	No	No

Components of a SIF Environment

A SIF Environment has several components or sections. Explaining each section and its purpose is best achieved by example. Below is an XML example of a typical SIF Environemnt for a service consumer. Follwoing the example are explainations of various sections of the sample environment.

XML Example

<environment type="DIRECT" id="75222386-a163-426e-bfbe-7b41e08793c4" xmlns="http://www.sifassociation.org/infrastructure/3.4">
    <fingerprint>acff2a35-4fda-4853-90e8-0635afb7c691</fingerprint>
    <sessionToken>64e70d3d-a0a1-4b82-aeeb-78d902cdf2fc</sessionToken>
    <solutionId>test</solutionId>
    <defaultZone id="auSchoolTestingZone">
        <description>Default Zone</description>
    </defaultZone>
    <authenticationMethod>Basic</authenticationMethod>
    <consumerName>Student Consumer</consumerName>
    <applicationInfo>
        <applicationKey>TestSIS</applicationKey>
        <supportedInfrastructureVersion>3.2.1</supportedInfrastructureVersion>
        <dataModelNamespace>http://www.sifassociation.org/datamodel/au/3.4.9</dataModelNamespace>
        <transport>REST</transport>
        <applicationProduct>
            <vendorName>Vendor ABC</vendorName>
            <productName>Test Driver</productName>
            <productVersion>v3.21.7</productVersion>
        </applicationProduct>
    </applicationInfo>
    <infrastructureServices>
        <infrastructureService name="environment">https://<baseURL>/environments/75222386-a163-426e-bfbe-7b41e08793c4</infrastructureService>
        <infrastructureService name="requestsConnector">https://<baseURL>/requests</infrastructureService>
        <infrastructureService name="provisionRequests">https://<baseURL>/provision</infrastructureService>
        <infrastructureService name="eventsConnector">https://<baseURL>/eventsConnector</infrastructureService>
        <infrastructureService name="queues">https://<baseURL>/queues</infrastructureService>
        <infrastructureService name="subscriptions">https://<baseURL>/subscriptions</infrastructureService>
        <infrastructureService name="servicesConnector">https://<baseURL>/services</infrastructureService>
        <infrastructureService name="responsesConnector">https://<baseURL>/responses</infrastructureService>
    </infrastructureServices>
    <provisionedZones>
        <provisionedZone id="auSchoolTestingZone">
            <services>
                <service name="StudentPersonals" contextId="DEFAULT">
                    <rights>
                        <right type="QUERY">APPROVED</right>
                        <right type="CREATE">APPROVED</right>
                        <right type="UPDATE">APPROVED</right>
                        <right type="DELETE">APPROVED</right>
                        <right type="PROVIDE">REJECTED</right>
                        <right type="SUBSCRIBE">APPROVED</right>
                        <right type="ADMIN">REJECTED</right>
                    </rights>
                </service>
                <service subType="adminDirective" name="StudentPersonals" contextId="DEFAULT">
                    <rights>
                        <right type="QUERY">APPROVED</right>
                        <right type="SUBSCRIBE">APPROVED</right>
                    </rights>
                </service>
                <service type="SERVICEPATH" name="SchoolInfos/{}/StudentPersonals" contextId="DEFAULT">
                    <rights>
                        <right type="QUERY">APPROVED</right>
                    </rights>
                </service>
                <service type="OBJECT" name="SchoolInfos" contextId="DEFAULT">
                    <rights>
                        <right type="QUERY">APPROVED</right>
                        <right type="CREATE">APPROVED</right>
                        <right type="UPDATE">APPROVED</right>
                        <right type="DELETE">APPROVED</right>
                        <right type="PROVIDE">REJECTED</right>
                        <right type="SUBSCRIBE">SUPPORTED</right>
                        <right type="ADMIN">REJECTED</right>
                    </rights>
                </service>
                <service type="FUNCTIONAL" name="RolloverStudents" contextId="DEFAULT">
                    <rights>
                        <right type="QUERY">APPROVED</right>
                        <right type="CREATE">APPROVED</right>
                        <right type="DELETE">APPROVED</right>
                        <right type="SUBSCRIBE">APPROVED</right>
                    </rights>
                </service>
        </provisionedZone>
        <provisionedZone id="auRolloverTestingZone">
            <services>
                <service ...>
                    <rights>
                        ...
                    </rights>
                </service>
                <service ...>
                    <rights>
                        ...
                    </rights>
                </service>
                ...
        </provisionedZone>
    </provisionedZones>
</environment>

Environment Type and ID

The <environment> node holds two key information bits. The environment type (DIRECT or BROKERED) and the unique environmentId applicable for this environment. Information about environment types can be found the SIF Environment page. The environmentId is of importance for the HTTP GET (query) and HTTP DELETE (delete) environment endpoints. For example to retrieve the environment data for a specific environment the applicable environment endpoint is HTTP GET https://<baseURL>/environments/<environmentId>.

Session Token & Fingerprint

The session token is allocated by this endpoint when an environment is created. Once an environment is created then the session token is used for authentication. It is unique for each environment and shall not be shared with any other AIF adapter. The fingerprint is another unique id of the environment that is NOT used for authentication and hence can be shared for certain purposes. A typical usage for a fingerprint is for eventing in functional services, where an event is directed to a specific service consumer. The service consumer is identified by its fingerprint and the service provider must know that fingerprint to direct the event to the specific service consumer.

Authentication Method

The <authenticationMethod> indicates what authentication method applies to the given environment. There are three methods available. They are explained in detail here.

Default Zone

Each environment has a dedicated “Default Zone”. The id in the <defaultZone> node holds the unique zone Id of the default zone. The id of that deafult zone will point to a specific provisioned zone in the list of the <provisionedZones> node. The <description> node has no functional purpose except readability in what the deafult zone stands for.

Application Info

The <applicationInfo> node is mostly an optional section. It provides some details about the SIF Adapter, vendor etc. to whom the environment belongs.

Infrastructure Services (URLs)

The <infrastructureServices> node provides the base URL for a number of services. Not all services might be available in each SIF environment. The table below shortly outlines what each service URL is intended for and where detailed information about each service can be found.

Service Name	Short Description	Details

Service Name	Short Description	Details
environment	URL to create, query and delete a specific environment for a SIF Adapter.	This page.
requestsConnector	This URL is the place where all SIF Object services are accessed. Generally the SIF Object name (i.e. StudentPersonals) is appended to this URL to provide the final endpoint to access a specific SIF Object. All services with a type of`"OBJECT"`, `"SERVICEPATH"` and `"XQUERYTEMPLATE"` in the `<service>` node are accessed via this URL.
eventsConnector	URL where events must be published to. Note that this URL is only applicable for service providers and if eventing is supported by the environment.	Events.
servicesConnector	URL where functional services and privacy services are provided.	Introduced in SIF 3.2 infrastructure. For more details where this connector is utilised see Functional Service and Privacy Service.
queues	URL to create, delete and read from message queues. It is utilised by service consumers to for events and delayed responses and by service providers if the service provider acts in a true DELAYED mode.	Queue & Messages and DELAYED Request/Response.
subscriptions	URL where a service consumer can register subscriptions for events or a service providers can registers subscriptions for DELAYED requests.	Subscription Service.
provisionRequests	This service endpoint URL can be used by service consumers to request “access” to services and functionality.
responsesConnector	URL where “DELAYED” responses are published by a service provider if the service provider processes request in an asynchronous manner.	Introduced in SIF 3.5 infrastructure. For more details where this connector is utilised see DELAYED Request/Response.

Provisioned Zones, Services and ACLs (rights)

The <provisionedZones> node and sub-nodes indicate which zones and what services are available in each zone. For each service there is also an access control list (ACL) provided that indicates what operations (rights) are available for each service.

The following rights are applicable for a Service Consumer: QUERY, CREATE, UPDATE, DELETE and SUBSCRIBE
The following rights are applicable for a Service Provider: PROVIDE
The ADMIN right is a placeholder for potential future functionality. It is not used currently.

If a right is not listed then a SIF Adapter must assume that it doesn't have the right to the given operation. This is equivalent as if the right would be set to REJECTED. If a right is set to APPROVED then the adapter has access to that operation. If it is set to SUPPORTED then a vendor needs to liaise with the service provider whether it can get access.

Environment Endpoints

To be completed.