This document describes in example form the XML-based instructions to manage sessions when communicating with Internet accounting systems.
Before reading this document, you should be familiar with the Core XML-X Requests which explain the model and authentication needs of all requests. Also see the XML-X site. for more precise documents.
The purpose of XML-X is to enable clients to deliver accounts and payment instructions to servers.
This description concentrates on the session management requests that permit many requests to be delivered.
The mission of this project is
to create a protocol for spend interfaces and front-end/back-end interfaces that can be the standard for all web based accounting systems.
The benefit will be obtained when merchants only have to implement one and only one interface method to access many different web based accounting systems. As the cost of implementing methods is very high, no merchant implements more than a few of the available systems. By implementing XML-X as a standard interface, any given web based accounting system can quickly acquire many merchants, thus ensuring the success of both the system and the merchant.
The Primary Authors of XML-X are Erwin van der Koogh and Ian Grigg.
Contributors and Influences include
The Author of this document is Ian Grigg, with contributions from all the above.
Parts in italics are optional at some level, for implementation, client or server.
In order to achieve a batch payment effect, a composite request may be used. This request batches up a series of other requests, and returns a like series of responses.
<CompositeRequest order="timed"> <TransferRequest> first </TransferRequest> <TransferRequest> second </TransferRequest> <HistoryRequest> . . . </HistoryRequest> </CompositeRequest> <CompositeResponse> <TransferResponse> successful </TransferResponse> <ErrorResponse> error </ErrorResponse> <HistoryResponse> a balance </HistoryResponse> </CompositeResponse>
Each and every subsidiary request is matched by its response, in the order of the original <CompositeRequest>. If one transaction fails, then an <ErrorResponse> is returned at the appropriate place, as shown above.
Note that GM used a different method which breaks the notion of a single authenticated request and record, and results in higher layer problems. Such is avoided by using the above method.
In order to send a sequence of requests, wrapped into one authentication session, use a <LoginRequest>.
<LoginRequest> <Auth>one of the above</Auth> </LoginRequest> <LoginResponse> <Token> Some magic string </Token> </LoginResponse>
In the event that separate requests are made over new connections, the requests can include the appropriate <Auth> with the supplied <Token> included. For example, the following <Logout>:
<LogoutRequest>
<Auth>
<UserId> MyName </UserId>
<Token> Some magic string </Token>
</Auth>
</LogoutRequest>
<LogoutResponse>
</LogoutResponse>
An alternate method might be to send a sequence of requests over the same connection, and thus the session is defined by the context of the connection.
<LoginRequest>
<Auth>one of the above</Auth>
</LoginRequest>
<TransferRequest> first </TransferRequest>
<TransferRequest> second </TransferRequest>
<HistoryRequest> . . . </HistoryRequest>
<LogoutRequest>
<Auth>
<UserId> MyName </UserId>
<Token> Some magic string </Token>
</Auth>
</LogoutRequest>
Between each Request sent, there might be some substantial delay as a human user prepares the next request to a web server, for example. On receipt of each request, the server would respond in order.
<LoginResponse> <Token> Some magic string </Token> </LoginResponse> <TransferResponse> successful </TransferResponse> <ErrorResponse> error </ErrorResponse> <HistoryResponse> a balance </HistoryResponse> <LogoutResponse> </LogoutResponse>
One goal of XML-X is to achieve a single request - response cycle to each request. Each request is generally idempotent; that is, repeating the exact same response many times will have the same meaning as doing it once.
In order to assist matching up a response to a request, the client can add to any request tag a special token in the rid attribute which the server must return in the response.
For example:
<TransferRequest rid="some_magic_token">
. . .
</TransferRequest>
will result in:
<TransferResponse rid="some_magic_token">
. . .
</TransferResponse>