Direct Provider Call (DPC)
This mode is appropriate when the proxy model is undesirable due to latency, legal, or other considerations. The provider can still get most of the benefits of the WebServius platform without having consumers call a WebServius endpoint.
Currently, only free usage plans are available in this mode. Paid plans can be enabled by special arrangement. Please contact us if interested at support@webservius.com.
Here are the integration steps for the provider:
1. Provider registers the service at WebServius.
2. Provider designs a protocol for key-based authentication and opens its service.
3. The service must be documented and documentation made available to consumers (this is done on the Service Settings page). There is no limitation to the service interface other than each call must be associated with a WebServius-issued subscription key. Consumers will receive their key after subscribing to the service via WebServius UI.
4. The provider can accept or reject service calls based on their discretion. Typically this logic will rely in part on cached balance data obtained from WebServius (see below).
5. Provider implements a callback mechanism by which WebServius will be periodically notified of the occurred consumer calls. Please see below for the callback API description.
6. As consumers start making calls, provider keeps track of which keys were presented and periodically relays this information back to WebServius. The provider also has an option to pre-authorize consumer calls as often as needed. WebServius does not mandate how often callbacks must be made. Provider needs to decide on this logic based on a trade-off between performance and the risk of allowing consumers to exceed their quota.
Consumer Key Verification
WebServius provides a quick cryptography-based method of verifying that the consumer key has been issued by WebServius. WARNING: This is a light front-line defense measure only and should not be considered a security feature. This method cannot account for stolen or no longer valid keys.
Documentation is forthcoming. Please contact support@webservius.com if an immediate response is required.
Callback URL
For each DPC service WebServius creates an endpoint, which hosts the provider callback API. The API is accessible via HTTPS only. The URL can be seen on the Service Settings page.
Callback API uses key-based authentication using a query parameter. The provider key can be seen on the My Account page. The key uses URL-safe encoding and can be provided verbatim.
NOTE: Please keep this key secret at all times.
Callback API v1
The API is a simple REST-like XML interface designed for ease of integration. Two operations are offered: pre-authorization, and log reporting. All requests must be “text/xml” POSTs.
Pre-authorization (“check”)
https://{callback URI}/check?provKey={provider key}
Use this operation in order to query a consumer’s balance. Please be cautious about caching the results of this call, because many external events may affect the consumer balance over time. Balance information is also returned when the logs are reported back to WebServius.
Request Format
<check>
<keys>
<key>
<value>consumer subscription key</value>
<op>operation friendly name</op>
</key>
</keys>
</check>
value (required): this is the WebServius-issued key that consumers get when they subscribe to your service
op (optional): this is the friendly name for the operation, as defined on the Operation Metering page. This element is optional if there is only one operation defined on the service.
The element may be repeated multiple times to check many consumer key/operation combinations in one call.
Response Format
<response>
<balances>
<balance>
<id></id>
<calls></calls>
<access></access>
</balance>
</balances>
<errors>
<noData>
<id></id>
<message></message>
</noData>
</errors>
</response>
The response will contain one <balance> or one <noData> element for each <key> from the request.
balance/id: zero-based index of the <key> element from the request in request document order
balance/calls: the minimum number of calls the consumer can make to the specified operation. This value will be 0 if there is no balance or the subscription is disabled. The value returned may be lower than the actual balance, but will never be higher.
balance/access: true or false based on whether the access policy for this subscription allows access to the specified operation.
noData/id: zero-based index of the <key> element from the request in request document order
noData/message: message describing why the balance could not be returned. This is generally caused by invalid <key> in the request.
Call log reporting (“record”)
https://{callback URI}/record?provKey={provider key}This operation is the method by which the provider notifies WebServius of the call traffic that occurred on the service. The logs will be processed by WebServius and will be available in reports and summaries.
· Charge requests will be processed in order
· An attempt to charge for an operation that the consumer has no access to will succeed, but <access>false</access> will be included in the results.
· An attempt to charge more units than the consumer has available will succeed, but <calls>0</calls> will be included in the results
Request Format
<record>
<charges>
<key>
<value>consumer subscription key</value>
<op>operation friendly name</op>
<calls>number of calls to charge</calls>
<badCalls>number of failed calls</badCalls>
<factor>call weight multiplier</factor>
</key>
</charges>
</record>
value (required): this is the WebServius-issued key that consumers get when they subscribe to your service
op (optional): this is the friendly name for the operation, as defined on the Operation Metering page. This element is optional if there is only one operation defined on the service.
calls (required): number of calls, which the consumer usage plan should account for. Each call will be metered based on the operation weight and specified factor (if included).
badCalls (optional): for reporting only, this is the number of failed calls, for which there is no charge
factor (optional, floating point): charge multiplier useful for when the charge depends on some variable in the service request or response
The element <key> may be repeated multiple times.
Response Format
The response format is exactly the same as for the check operation. Please see above.