BSIDL Reference

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.

It is the main input into the Maven Cougar Codegen Plugin.

Benefits

Generated artifacts created in a consistent way 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 specification 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.

File structure reference

Note that a document describing an interface is an interface definition document (IDD) and is written in the interface definition language (BSIDL). It may directly contain extensions or these may be specified in a seperate extensions document.

Main IDD (Interface.xml):


  <interface>
    <authors>
      <author/>
    </authors>
    <description/>
    <operation>
      <description/>
      <parameters>
        <request>
          <parameter>
            <description/>
            <validValues>
              <value>
                <description/>
              </value>
            </validValues>
          </parameter>
        </request>
        <response>
          <description/>
        </response>
        <exceptions>
          <exception>
            <description/>
          </exception>
        </exceptions>
      </parameters>
    </operation>
    <event>
      <description/>
      <parameter>
        <description/>
        <validValues>
          <value>
            <description/>
          </value>
        </validValues>
      </parameter>
    </event>
    <exceptionType>
      <description/>
      <parameter>
        <description/>
        <validValues>
          <value>
            <description/>
          </value>
        </validValues>
      </parameter>
    </dataType>
    <dataType>
      <description/>
      <parameter>
        <description/>
        <validValues>
          <value>
            <description/>
          </value>
        </validValues>
      </parameter>
    </dataType>
    <simpleType>
      <description/>
      <validValues>
        <value>
          <description/>
        </value>
      </validValues>
    </simpleType>
  </interface>

IDD Extensions (Interface-Extensions.xml):


  <interface>
    <operation>
      <parameters>
        <request>
          <parameter>
            <extensions>
              <style/>
            </extensions>
          </parameter>
        </request>
      </parameters>
      <extensions>
        <path/>
        <method/>
      </extensions>
    </operation>
    <event>
      <parameter>
        <extensions>
          <style/>
        </extensions>
      </parameter>
    </event>
  	<extensions>
  		<path/>
  	</extensions>
  </interface>

<interface>

The interface element describes the top-level attributes of service interface defined by this IDD.

<?xml version="1.0" encoding="utf-8"?>
<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>

The attributes are explained in more detail: * name: The name of the service, this should match exactly with the file name without file extension (e.g. filename: FooBar.xml corresponds to name: FooBar). * owner: The person who should be contacted with any queries regarding this service interface, in many cases one of the authors but this isn’t necessary. * version: The version of the interface - please see versioning. * date: The date that the interface version was frozen - in development service interface can use the now() function that will insert the current date time - the date should be formatted as an [[ISO 8601 date|http://en.wikipedia.org/wiki/ISO_8601]] in UTC.

The description element provides a description of the interface (usually in English).

#### Supported extensions

TODO

<authors>

The authors element must contain one or more author elements which give a name and email address for each author.