-
Notifications
You must be signed in to change notification settings - Fork 8
Tablature User Guide for Interfaces
Interfaces is the Orchestra schema for defining service offerings and session configuration. Tablature provides easy authoring of such files my composing them as a markdown document.
You should write an overview of your exposed interfaces starting with a heading. You may use any text for the heading so long as it is heading level 1, as designated by a single "#".
You may follow the heading with any number of paragraphs that describe the service offerings. Recall that markdown separates paragraphs with an extra linefeed.
The description of the rules of engagement may be followed by a table of metadata terms to identify your document. It tells the what, when, and who issued the document. The table has two columns, Term and Value. The terms are defined by and industry standard called Dublin Core Terms for media identity. The core terms are: "contributor", "coverage", "creator", "date", "description", "format", "identifier", "language", "publisher", "relation", "rights", "source", "subject", and "type".
Here's and example of a document overview with metadata:
# Service Offerings and Sessions
Services and their session configurations
| Term | Value |
|-----------|----------------------------------------|
| subject | Service offerings and sessions example |
| publisher | FIX Trading Community |
| rights | Copyright 2020, FIX Protocol, Limited |
| date | 2020-06-09T16:09:16.904-06:00 |
Sections of your document are identified by a heading at level 2 or lower starting with one of the following keywords: Interface, Protocols, Identifiers or Session. Matching is case insensitive, but the keyword must be the first word in the heading.
Below each section heading, you may provide any number of paragraphs of explanation. The paragraphs may include markdown marks for emphasis, such as italic or bold. Markdown lists may also be included. Tablature treats lists the same as regular paragraphs.
An interface is a service that you expose to customers or partners. As an application, it is also known as a service offering. An application depends upon layers of protocols, and these protocols must be specified to users of the service.
An interface description is initiated by heading at level 2 or lower starting with the keyword Interface. It may be followed by paragraphs of expanation.
Below the interface description, you can provide a specification of a protocol stack required to communicate with the service. This document section is initated by a markdown header starting with the keyword "Protocols". Tablature associates the protocols with an interface by its position in the document.
The protocol layers in Tablature are based on Open Systems Interconnection model (OSI model) of communications. In that model, high level protocols, with application layer at the top, depend on lower layers for support.
The protocol layers recognized by Tablature are:
| Layer | Synonym | Responsibility |
|---|---|---|
| Service | Application | Business service |
| UI | UserInterface | Display service |
| Encoding | Presentation | Message syntax |
| Session | Message exchange | |
| Transport | Message delivery |
Other values are accepted for layer that do not fit neatly with OSI model, e.g. Security.
You may use either the keyword in the layer column or its synonym in Tablature. Matching is case insensitive, but the keyword must be spelled out.
The lowest layers of the OSI model are physical networking and signaling that we don't generally need to specify for customers.
In the table of protocols, the required column headings are Layer, and Name. Additional optional columns:
- Version of a protocol, e.g. TLS version 1.3.
- Orchestration is a link to rules of engagement for that protocol in the Orchestra repository schema. The value must be in the form of a URL for either a local file or a web link.
- Reliability of a messaging protocol. This may apply to either Session or Transport layers. The possible values are "bestEffort", "idempotent", or "recoverable". Matching of values is case insensitive.
The following columns only apply to Transport layer protocols:
- Address e.g. IP address or domain name
- Use e.g. primary / secondary connections
- MessageCast one of "unicast", "multicast", "broadcast"
As for other tables in Tablature, matching of column headings in case insensitive, and the columns may be appear in any order.
Here's an example of an interface definition with a protocol stack:
## Interface Private
Order entry service with algorithm control
#### Protocols
| Layer | Name | Orchestration | Reliability | Messagecast |
|-----------|------------|-----------------------------------------------|-------------|-------------|
| Service | orderEntry | https://mydomain.com/orchestra/orderEntry.xml | | |
| UI | ATDL | https://mydomain.com/orchestra/algo.xml | | |
| Encoding | TagValue | | | |
| Session | FIXT.1.1 | https://mydomain.com/orchestra/session.xml | RECOVERABLE | |
| Transport | TCP | | | UNICAST |
Some protocols have defined sessions, either for communication channels or identification at the application layer or both. A session configuration in Tablature begins with heading starting with the keyword Session. A session is associated with the previous interface by its position in the file. Like an interface, a session may have paragraphs of description following the heading.
If a session has unique identifiers, it follows a heading with the keyword Identifiers. A session may have any number of identifiers. For example, in the traditional FIX session protocol, a session is identified by a combination of SenderCompID and TargetCompID, as in the example below. The Identifiers table has two columns, Name and Value.
A session may also have specific configuration of protocols listed for its interface. In the example below, the session has connection settings for its transport that are different than another session of the same interface. It is not necessary to list all protocols for a session, only the ones that have a session-specific configuration.
### Session XYZ-ABC
#### Identifiers
| Name | Value |
|--------------|-------|
| SenderCompID | XYZ |
| TargetCompID | ABC |
#### Protocols
| Layer | Use | Address | Messagecast |
|-----------|-----------|---------------|-------------|
| Transport | primary | 10.96.1.2:567 | UNICAST |
| Transport | secondary | 10.96.2.2:567 | UNICAST |
The tool md2interfaces parses a markdown document to generate an Orchestra interfaces file.
The reverse tool is called interfaces2md. It supports a roundtrip between text and Orchestra. It extracts information from an existing Orchestra interfaces file and writes it out as a markdown document.