SIF Message Parameters

_accept

_O

_HQ

_{Used to indicate when the format that is expected in the response (ex: application/json).}

_{If omitted, may also be indicated by including an extension in the URL’s path (ex: “.json”).}

_{Otherwise results will be conveyed using the default, application/xml.}

_{accept-encoding}

_C

_C

_H

_{Indicate what payload encoding is accepted in the response. Valid values are: identity (not compressed) or gzip (compressed).}

_{access_token}

_MC

_Q

_{The token used to authenticate the sender of the message, authorizing the requested action.}

_{Usually the token/hash value of the Authorization header.}

_{This query parameter is only required when the Authorization header is not set or another authentication standard is leveraged.}

_{applicationId}

_M

_Q

_{A unique Id for an application in regards to the Data Privacy Enforcer service. It is important to note that this is different to the ApplicationKey (see below) which is used for authorization.}

_{applicationKey}

_MC

_HQ

_{If the Application Key is not contained in the Authorization header, then this header must convey this key together with the authentication.}

_{The consumer may choose to convey this value in either place, so providers must honor it in either place.}

_{authenticatedUser}

_OC

_H

_{Set to the users identification (depending on the authentication used) when verified by the middleware.  The receiving Service Provider can trust this field by confirming the middleware’s credentials.}

_{authenticationMethod}

_MC

_Q

_{The identifier for the authentication method used.}

_{Note:  Placing basic access authentication information in a URL query parameter is highly unsecure and should not be used in any production systems.}

_{Unless otherwise specified the prefix from the Authorization header is used:  SIF_HMACSHA256/Bearer/Basic}

_{authorization}

_MC

_MC

_H

_{Used to authenticate the Consumer and is the basis for determining whether the Consumer has the necessary authorization to issue the Request or publish the Event.}

_{When conveyed in URL Query Parameters, access_token and authenticationMethod are used.}

_{changesSinceMarker}

_OC

_OC

_HQ

_{Request: URL Query Parameter. Only required if a changes since request is performed.}

_{Response: HTTP Header. Only required if the request had the changesSinceMarker as a URL query parameter and no paging is used or paging is used, but the first page is requested.}

_connectionId

_MC

_H

_{Identifies the established connection over which the next message in the Queue is being requested and delivered.  This must be a unique unsigned integer ranging in value from 0 to one less than the current value of maxConcurrentConnections.}

_{Must be included only when the consumer utilizes multiple connections to the same queue.}

_{content-encoding}

_C

_C

_C

_H

_{Indicate the payload encoding. Valid values are: identity (not compressed) or gzip (compressed).}

_{See also:  accept-encoding}

_content-Type

_MC

_M

_M

_HQ

_{Tells the receiver how to parse the body of the message.}

_{Supported generally, however SIF data models are generally conveyed with types  application/json or application/xml (default).}

_{Must be conveyed whenever a body is present.}

_{May be omitted in a request. In that case the mime type is either:}

• _{The mime type indicated on the URL (i.e. .json)}

• _{XML if not defined on the URL or the HTTP Header}

_{See also:  Accept}

_contextId

_O

_O

_HM

_{The “context” of the service provided.  The range of possible Context token values for a given Object or Functional type Service is defined by either or both the Data Model which the Environment is supporting, and the administrators of the Zone.}

_{If not provided, it will default to DEFAULT.}

_{This is carried as a matrix URL parameter in Requests, but is conveyed as an HTTP Header field on Events}

_{See also:  relativeServicePath}

_contractId

_O

_Q

_{Used in conjunction with the Data Privacy Enforcer Service. It allows to specify a specific contract that is in place between two parties and what exact filer rules apply.}

_{dataPrivacyMarker}

_OC

_OC

_H

_{If privacy services are in place and enforced then of the respective adapter must include this HTTP header in each request or event.}

_{deleteMessageId}

_OC

_M

_{The ID of the last message received and processed by the Queue Owner.}

_{Only used when making Query Requests to the Queue Service Instance when deleting a previously retrieved message from the queue.}

_{environmentURI}

_OC

_H

_{May be returned by the environment provider where the environment is pre-provisioned.}

_eventAction

_M

_H

_{The specific type of Event being reported:  CREATE/UPDATE/DELETE}

_fingerprint

_MC

_MC

_H

_{Unique environment identifier that can be safely shared with others.  In order not to compromise security it MUST NOT match the environment’s refId, sessionToken, userToken, or applicationKey.}

_{Further details about usage if the fingerprint can be found on the Functional Service & API page.}

_generatorId

_O

_O

_H

_{The optional identification token of the “generator” of this request or event (ex: the administrative clerk who entered in the data that was responsible for generating a Create request).}

_messageId

_O

_M

_M

_H

_{UUID that uniquely identifies the message that carries it.}

_messageType

_O

_M

_M

_H

_{One of: EVENT/REQUEST/RESPONSE/ERROR}

_{If not provided, it will default to REQUEST.}

_{methodOverride}

_MC

_H

_{HTTP PUT:}

_{Included in an HTTP PUT message when it is conveying a multiple delete request, since an HTTP DELETE is not allowed to have a payload.  Valid values are DELETE or UPDATE.}

_{HTTP POST:}

_{Included in an HTTP POST message when it is conveying a QBE request because the HTTP GET is not allowed to have a payload.  Valid values are GET (QBE) or POST (Create).}

_{mustUseAdvisory}

_O

_HQ

_{Informs the Service Provider that if the "suggested" RefId in the Request cannot be assigned to the new object, the Request should be rejected. Valid values are true and false. Used in Create requests to Object Services.}

_{navigationCount}

_O

_H

_{The total number of objects in the set of results generated by the initial Paged Query that is associated with the returned navigationId.}

_navigationId

_MC

_O

_H

_{Identifies state maintained in the Service Provider for the Consumer issuing the Paged Query Request. If returned, the Consumer must supply the navigationId value when requesting subsequent Pages of that object type from that Service Provider.}

_{This should not happen when queryIntention is set to NO-CACHING or ONE-OFF.}

_{navigationLastPage}

_O

_H

_{Included as an aid for the Consumer in detecting when to stop issuing Paged Query Requests.}

_{navigationPage}

_O

_MC

_HQ

_{The number of the Page to be returned. If it is outside the range of results (which does not constitute an error) an HTTP Response with a code of 204 (No Content) will be returned. The first page is indicated with the value 1 (i.e. navigationPage=1).}

_{navigationPageSize}

_MC

_MC

_HQ

_{This is included in every Paged Query Request, and indicates the number of Objects to be returned in the corresponding Response Page. If the Page Size specified is too large for the Service or Environments Provider to supply, an Error with code 413 (Response too large) will be returned.}

_{When contained in the Response, it indicates the actual number of objects on the returned Page.}

_Order

_O

_Q

_{Orders the result set by one or more specified elements and directions. For example, [name/nameOfRecord/familyName=ascending;name/nameOfRecord/givenName=descending]. See discussion in Section 5.8.}

_partyId

_M

_Q

_{A unique Id for an party in regards to the Data Privacy Enforcer service. Aparty can be an organisation, district, state, jurisdiction etc.}

_podId

_O

_H

_{The unique ID (UUID) of the POD that was applied to a payload. The Data Privacy Enforcer service may set this HTTP header.}

_podVersion

_OC

_H

_{The POD version of the POD that was applied to a payload. The Data Privacy Enforcer service may set this HTTP header. If this HTTP header is provided it is expected that the podId HTTP header is also set.}

_{queryIntention}

_O

_H

_{If the Consumer intends to follow up with further Paged Queries after this one, this field must be included in the Paged Query Request.}

_{Valid values are:  ALL/ONE-OFF/NO-CACHING}

_{ALL:  The Consumer intends to come back for the remaining pages of data. It is expected that the provider would return a navigationId HTTP Header in this case.}

_{ONE-OFF:  The Consumer intends to make only this query, however the results may come from a cached source.}

_{NO-CACHING:  The Consumer needs the data returned as it currently exists in the provider’s data store.}

_{It is a “hint” to the Service Provider that maintaining Consumer state (and supplying a navigationId) would be advantageous.}

_{When not provided the default value is ONE-OFF.}

_queueId

_MC

 _C

_H

_{Contains the identity of one of the Consumer’s assigned Queues to which the delayed Response or Job Object Events from the Service Provider related to this request must be routed. If a service provider is in true delayed mode then the consumer’s queueuId must be provided in each response to the response connector.}

_{See also:  requestType, jobId}

_role

_O

_Q

_{A role name in regards to the Data Privacy Enforcer service. It is expected that this is used inconjunction with the applicationId (see further up) to further tie down privacy rules to a particular application role (e.g. teacher, student). Depending on the role different privacy rules may apply.}

_{relativeServicePath}

_MC

_H

_{Replicates all information contained in the segments of the Request URL following the Request Connector.  This could include the Service name, eXtended Query Template name or Service Path defining the payload format, and any accompanying URL matrix parameters (Context and Zone).}

_{URL Query parameters are included.}

_{The Environment Provider places it into all delayed Responses (and would therefore not be supplied by a Service Provider in a Brokered Architecture), as an aid to stateless Consumers.}

 _{It is optional for immediate Responses.}

_{Example: /StudentPersonals}

_replacement

_O

_H

_{Set to FULL (current values of all object elements) or PARTIAL (only elements whose values have changed)}

_{If not set, it is defaulted to PARTIAL.}

_requestId

_MC

_MC

_H

_{Only required for delayed Requests.}

_{A Consumer specified “token” that uniquely identifies every delayed Request issued by the Consumer.  It could be as simple as a monotonically increasing integer.   Used to correlate the delayed (asynchronous) Response with the original Request.   It could be as simple as a monotonically increasing integer.}

_{requestAction}

_O

_H

_{Indicates what the request is trying to do.}

_Defaults:

• _{POST:  CREATE}

• _{PUT:  UPDATE}

• _{DELETE:  DELETE}

• _{GET:  QUERY}

• _{HEAD:  HEAD}

_requestType

_O

_H

_{One of IMMEDIATE or DELAYED.  If not set, it defaults to IMMEDIATE.}

_{responseAction}

_M

_H

_{This must exactly match the requestAction value contained in the HTTP header of the Request being responded to.} 

_{Valid values are:  CREATE/UPDATE/DELETE/QUERY/HEAD}

_serviceName

_M

_H

_{The name of the data object collection being conveyed in the event.}

_serviceType

_O

_O

_O

_H

_{One of:  UTILITY/OBJECT/FUNCTIONAL/SERVICEPATH/XQUERYTEMPLATE/SERVICE.}

_{If not provided, it will default to OBJECT}

_{serviceSubType}

_O

_O

_O

_H

_{If a service is for an admin directive rather than the actual base service then this HTTP header must be set to ‘adminDirective’.}

_{If not provided it must be assumed that the request, response or event is intended for the base service.}

_sourceName

_MC

_H

_{The applicationKey is added by Brokered Architecture to all Requests before forwarding to the Service Provider.}

_{Used by the Service Provider in Brokered Architectures when issuing an Alert concerning an erroneous Request.}

_timestamp

_MC

_M

_M

_HQ

_{Date / Time of Event creation (in ISO-8601 format which is also used as the basis of xs:dateTime)}

_{If not need for authentication, may be omitted in the request.}

_{If needed, only for requests this value may be provided as a URL query parameter instead of a header.}

_vary

_O

_H

_{This standard HTTP Header can be set by the provider to indicate that it supports compression. It would only be set if the consumer or broker calls the provider with uncompressed payloads where the provide could deal with compression. In such a case the HTTP header vary would take the following value:}

_{Vary: Accept-Encoding}

_Where

_O

_Q

_{A restricted XPATH expression that qualifies which among the set of all objects supplied by the Provider will satisfy the query and be returned.}

_zoneId

_MC

_M

_HM

_{Indicates the Zone the Request should be routed to.  It is a token that must have a value which:}

• _{Is unique from any other Zone ID}

• _{Identifies an entry in the Zone Registry if that Registry Service is present.}

_{If not specified in the Consumer’s Request, the Request Connector will insert the Consumer’s “Default” Zone ID (assigned to the Consumer when it initially created its Environment).}   

_{This is normally carried as a matrix URL parameter in Requests, but conveyed as an HTTP Header field on Events.}

_{[name matches eXtended Query Template parameter]}

_MC

_Q

_{Supplies value to a parameter of the eXtended Query template whose token is in the last URL segment of the Query Request.}