Web-Service protocol

The Service Proxy has been designed as a fairly non-constraining plugin execution framework and as such leaves the details of request processing to the plugins without imposing any special invocation schemes. Most plugins, however, stick to the established conventions (see plugin pages for details).

In general, SP WS protocol follows the Plain-XML-over-HTTP paradigm. It is an RPC (remote procedure call) oriented framework where a remote functionality is invoked via HTTP requests: by specifying the command request parameter (which is then mapped internally into a processing chain) and in general supplying additional plugin-specific parameters (as specified in the plugin manual).

The Service Proxy itself supports both HTTP GET and POST when processing requests and, in general, is indifferent with respect to those two methods. Specific plugins may however impose additional restrictions (e.g arbitrary data can be only attached to the request using POST)

SP is XML oriented in a sense that plugins involved in a chain build up a response using a common XML response document. By default, the response content type is XML. This is not to say that SP does not support other content types (JSON for example), however, those are always deduced from the internal XML format. In some (rare) cases plugins may override the standard response type e.g to return a binary image -- this should be clearly stated in the plugin documentation.

For example, conversation between the client and the authentication plugin would look as follows:

Request:

  GET /service-proxy/?command=auth&action=login&username=ABC&password=XYZ

Response:

  <auth>
    <status>OK</status>
    <displayName>NGO</displayName>
    <realm>nextgenopac</realm>
    <type>credentials</type>
    <iconUrl/>
    <proxyPattern/>
  </auth>

Error responses

The plugin programming interface specifies a set of error codes (carried over by exceptions to the SP runtime) that, if raised, are send back to the client in an XML format. This format has a well defined structure, for example an error response to the un-authenticated request would look as following:

  <error code="100" msg="NOT AUTHENTICATED">Not authenticated.</error>

Please refer to the API documentation for information on the error codes.

Additionally, the SP runtime sets the 417 HTTP response code on the erroneous response (following Papzar2 behaviour in this matter) -- which allows clients to pick up erroneous responses without explicitly parsing and analyzing response bodies. This may be used as an optimization trick by the client in case they're not instantly interested in the returned (large) data.