Betfair Service IDL

Overview

The Betfair Service Interface Definition Language (Betfair Service IDL or BSIDL for short) is an XML-based DSL (domain specific language) for describing versioned service interfaces. The DSL uses a combination of ideas taken from Thrift with additional support for events and information on users of interfaces.

The format allows us to fully describe the methods, request/response parameters, exceptions as well as events and all documentation associated with these entities. The format is already used throughout Betfair to describe APIs and services interfaces and standardisation of this gives us the benefit of consistent documentation (generated from the XML) as well as the ease of modification of wire formats and potential generation of serialisation/deserialisation code.

Benefits

• Generated artifacts created in a consistent way across Betfair meaning that users of these artifacts are familiar with conventions used.
• All users benefit from the debugging of generated output. For example WSDLs are notoriously hard to create that work consistently across technology stack (a whole spec. was created to try and fix this Basic Profile) 
• Data can be processed and validated before generation (e.g. Topological Sorts on data types for Thrift)
• Documentation is consistent and generated at low cost to the developer. They need only worry about content and not format (no more editing word documents).
• Automated versioning tasks can be build around the IDL for marshalling from one version to another
• Enables the use of a consistent domain model throughout technology
• Creates a focal point for tooling and NFR support

Types

The base types supported by the IDL are as follows:

• bool - a boolean value, true or false
• byte - an 8 bit signed byte
• i32 - a 32 bit signed integer
• i64 - a 64 bit signed integer
• float - a 32 bit signed floating point number (deprecated, please only use the double type)
• double - a 64 bit signed floating point number
• string - An encoding agnostic text or binary string
• dateTime - Date & Time expressed in xsd:dateTime format: http://www.w3.org/TR/xmlschema-2/#dateTime
• list(type) - a parametric, stable, ordered non unique collection of entities
• set(type) - a parametric unstable, unordered unique collection of entities
• map(keyType,valueType) - a parametric associative array of keys to values where keys follow the rules of a set

Note that generics are specified with ‘()’ rather than ‘<>’ as chevrons break the xml and are a pain to delimit.

Elements

h5. Preamble

<?xml version="1.0" encoding="ISO-8859-1"?>
<interface name="Test" owner="Joe Bloggs" version="0.1" date="01/01/1970">
	<authors>
		<author name="Joe Bloggs" email="joe@bloggs.com"/>
	</authors>
	<description>This is here to provide an example of all features in order for tests to be made</description>
</interface>

This is essentially the header of the IDL containing information about the service. Below each significant XPath is explained

h5. Operations

<operation name="someMethod" since="0.1.0">
	<description>Retrieves an account</description>
	<parameters>
		<request>
			<parameter name="mandatoryNumber" type="i64" mandatory="true">
				<description>abc</description>
			</parameter>
		</request>
		<simpleResponse type="i64">
			<description>Some Number</description>
		</simpleResponse>
	</parameters>
	<consumers>
		<product name="SoftGames"/>
	</consumers>
</operation>

h5. Parameters

Parameters are an instantiation of a base type with a name, a nullability constraint, and a description. They can also have valid values assigned to them.

h6. Valid Values

Valid Values elements indicate the total set of available values which can be used for the named parameter, and which should ultimately be validated in the interface implementation. An example is shown below

<parameter name="type" type="string">
	<description>The type of balance</description>
	<validValues>
		<value name="AVAILABLE_TO_BET">
			<description>The amount of the balance the user can Bet with</description>
		</value>
		<value name="AVAILABLE_TO_WITHDRAW">
			<description>The amount of the Balance that the user can Withdraw to a payment method</description>
		</value>
	</validValues>
</parameter>

So this is a string parameter called ‘type’ which can have the value AVAILABLE_TO_BET or AVAILABLE_TO_WITHDRAW

h5. Simple types

These act as aliases for the base types supported by the IDL.

<simpleType name="someType" type="i64"/>

h5. Data Types

<dataType name="Example">
	<description>This data type represents an example for a howto</description>
	<parameter name="account" type="Account">
		<description>The account being referenced in this Example</description>
	</parameter>
	<parameter name="master" type="bool">
		<description>If the account is a master account</description>
	</parameter>
</dataType>

h5. Events

<event name="SomeChange" since="1.1.0">
	<description>Event indicating that a change has been made</description>
	<parameter type="i64" name="accountId" mandatory="true">
		<description>The Account ID to which the change has been made. Must be between 10^12 and -10^12</description>
	</parameter>
	<parameter type="i64" name="newAccountId" mandatory="false">
		<description>The new value for this account</description>
	</parameter>
</event>

h5. Exceptions

<exceptionType name="SomeException">
	<description>This exception is thrown when Something bad happens</description>
	<parameter name="errorCode" type="string">
		<description>An error code</description>
	</parameter>
	<parameter name="message" type="string">
		<description>This is a message describes the reason for the exception in English and is for debug/logging purposes
		only and shouldn't be returned to users. There is also no need to localize this string.</description>
	</parameter>
</exceptionType>

h5. Enumerations

BSIDL deliberately does not support enumerations as they make interfaces unnecessarily brittle on the possible values of that enumerations, adding, removing or changing a value requires a re-release of the interface. Contraints on the values of a particular parameter should be enforced in the code and noted in the documentation.

h5. Validation rules

More info required (regexps + size restrictions).

Extensions

Several elements within the IDL support extension markup which is specific to each modeled protocol. Extension elements take the format of:

<extensions>
	<!-- Some Protocol name which supports extensions, which maps to the type generator name
             such as bfmq-java, or rest -->
	<rest>
		<httpmethod>GET</httpmethod>
	</rest>
</extensions>