IAP - Protocol Basics
As has been mentioned in earlier documents, IAP is a network protocol with a set of common standards using which additional semantic protocols can be implemented. IAP defines the common basic message format, but does not dictate exactly what fields each message should contain. That is up to the semantic protocols to define.
The semantic protocols target specific use cases. For instance, a time protocol, file exchange, RPC calls etc. Therefore each semantic protocol specifies its own set of message types and associated behaviour. However, all of these message types will be encoded using the standard IAP message format.
The way semantic protocols use the standard IAP message format is similar to how SOAP, REST, XML-RPC and other protocols are implemented on top of HTTP. These protocols use different message contents and have different behaviour, but they all use HTTP requests and responses to exchange these messages.
At first we intended to create a single base protocol which would be able to handle the functionality needs of most (if not all) semantic protocols, including multiplexing, routing, authentication, authorization and many other features. However, as we started looking into different semantic protocols it became clear that it would be better to leave such details to each semantic protocol, rather than force a standard set of functionality upon the semantic protocols.
For instance, routing of messages depends on the topology of the system the messages are to routed within. A single routing mechanism might not suffice for all system topologies. Therefore it is better to leave routing to be specified by the concrete semantic protocol, rather than by the IAP core features. The same is true of authentication, authorization etc.
It is possible however, that standard ways of handling common issues will arise, and that semantic protocols will elect to follow these standards, to make life easier for everyone. But that is up to the semantic protocol designers to decide.
IAP is Message Oriented
IAP is intended to be a message oriented network protocol. The semantic protocols that are based on IAP are thus also message oriented protocols.
IAP Message Structure
An IAP message consists of a single ION Object field as described in the ION Encoding specification. To recap, an ION Object field can contain an arbitrary set of ION fields inside it.
Exactly what ION fields a given IAP message contains depends on what semantic protocol that message belongs to. This gives the semantic protocol designers maximum freedom to design the message structure for each message type in the protocol.
An ION object field tells explicitly how big (in bytes) it is. This is enough for general IAP clients and servers to be able to see where one IAP message ends and another starts. It is thus possible to exchange any semantic protocol messages via standard IAP clients and server software.
Standard IAP client and server software will only be concerned with sending and receiving IAP messages, but will leave the interpretation of these messages to the software using the clients and servers. That means, that standard IAP clients and servers need not be concerned with the decoding and interpretation of the ION fields inside the ION Object fields. That is up to the applications using the IAP clients and servers. This makes the client and server responsibility simpler. They just have to look for ION Object field starts and ends, and can ignore their contents.
To be able to understand the IAP message sent by another part, you need to know what semantic protocol the message adheres to. In other words, you need to know the semantic context in which to interpret that message. Therefore it is assumed that all IAP messages adhere to some semantic protocol.
An IAP message can adhere to a semantic protocol either explicitly or implicitly. Both are explained in more detail in the following sections.
If an IAP message uses explicit adherence to a specific semantic protocol, it means that the message explicitly contains the ID and version of the semantic protocol it adheres to. That means that all nodes receiving such an IAP message can see from the message itself what semantic protocol + version that the message adheres to.
Exactly how an IAP message will state its semantic protocol ID and version is not yet fully defined. One option is to use a set of ION Key + ION field pairs. If this option is chosen then we will define some standard ION Key field values that can be used to mark the key,value pairs explicitly. For instance, names like "spid" and "spv" or "pid" and "pv" could be used. Or perhaps numeric key values can be used for faster identification, like 0, 1 and 2.
Another option is to use the ION Complex Type ID + Complex Type Version fields, but somehow we feel that is option is misleading. These fields are intended to tell the type of an ION Object field, but the semantic protocol id and version do not really tell the "type" of an IAP message. A semantic protocol may consist of many message types, and the "type" of an individual IAP message should include the semantic protocol id, version and message type. Thus, using the Complex Type ID field for the semantic protocol ID and the Complex Type Version field for the semantic protocol version leaves the concrete message type out.
So far we think we will go with a set of standard key, value ION field pairs.
If an IAP message adheres to a certain semantic protocol implicitly, it does not contain any explicit information about what semantic protocol ID and version it adheres to. The communicating parties agree on that out of band. For instance, a service can describe in its documentation what semantic protocol ID and version it uses. All clients calling that service must then send IAP messages in accordance with that semantic protocol.
Implicit adherence is useful in situations where high performance is essential. Being able to leave out the semantic protocol id and version makes the IAP messages shorter, and thus faster to transmit and process.
Implicit adherence is also useful in situations where the coupling between two communicating nodes is very tight, and where you control the development of both nodes. For instance, if you have a system split up into several smaller services which communicate internally, and some of these services are not available to the outside world, then you may not have a need to explicitly tell what semantic protocol the services communicate via internally. Simply defining some standard message formats might be enough information.
Finally you may even have "services" that run within the same process - for instance in different threads within the same process. These can also communicate via IAP messages. In such situations you probably don't need to include an explicit semantic protocol ID and version in each message. Having just the fields needed to identify and process the message will be enough. What fields that will be depends entirely on the semantic protocol the "services" have decided to use.