This post is part of a series. Click here for the ‘home page’
Interaction with a service involves performing actions against the service. This interaction can be:
- A message exchange (e.g. returning the result of a complex financial calculation)
- Modifying the shared state of an entity (e.g. crediting a bank account)
In order to interact with a service we need two things: an information model and a behavioural model.
1. Information Model
The information model explains the information that may be exchanged with the service. It includes both structure (syntax) and semantics (meaning).
When evaluating your architecture for structure/syntax consider such things as:
- Whether the data types are unambiguously defined (e.g. date formats, time formats, scale and precision of numbers).
- Whether the character encoding is specified.
- Whether the structure is as compact as it can be. Larger messages take longer to transmit and process.
- Whether cardinality is clearly defined.
- Whether data validation rules are clearly defined (valid ranges for values, minimum/maximum, values, required vs. optional values)?
When evaluating your architecture for semantics/meaning consider such things as:
- Whether the service definition clearly explains the meaning of various entities used by the service.
- Whether the understanding of various data elements is helped or hindered by the structure/syntax of the message (e.g. a data element ‘Line 1′ has no meaning by itself but if it is nested beneath an ‘address’ element then it make sense).
- Whether all jargon and abbreviations have been eliminated. It may be easy for your organisation to understand but if you open up services to external parties they may be confused.
- Whether there is a domain model with clearly understood semantics available for your industry. Does your information model conform to it?
- Whether the interaction expected is documented sufficiently to remove ambiguity. For example, what would happen if you invoke a “DebitAccount” service with a negative value (will the request be rejected or will it in fact credit the account).
2. Behaviour Model
The behaviour model encompasses two things. Firstly, it explains what actions can be invoked on the service and secondly, it explains the process (or sequence of events) that needs to be used to invoke those actions (e.g. first request a security token, then pass the token when invoking the desired action). OASIS has labelled the former the ‘action model’ and the latter the ‘process model’.
When evaluating the action model of your architecture consider such things as:
- Whether all actions have clear, unambiguous names. For example, actions called “UpdateAccountD” and “UpdateAccountC” are confusing whereas “DebitAccount” and “CreditAccount” are much clearer.
- Whether there are any unexpected ‘side effects’ for consumers of invoking an action. For example, actions that imply read-only retrieval of data (e.g. GetBalance) should not be updating data.
- Whether all “implied” effects of actions are clearly communicated. For example, if you invoke an action to close a bank account it may trigger other actions that the consumer may not be aware of (e.g. letter sent to client).
- Whether all dependencies on other services are clearly documented?.
- Since all requests for interaction will be validated, are all business rules (validations) clearly documented?
- Should you provide ‘cut down’ versions of your true capabilities (e.g. for security or resourcing reasons). For example, in ATMs you can only withdraw a certain amount per day. Banks do not have this limitation, but they choose to impose it on consumers of their ATM service.
When evaluating the process model of your architecture consider such things as:
- If the interaction requires a sequence of events, is this sequence clearly documented?
- How are exceptions/errors handled if the interaction process breaks down? Will there be some temporary state persisted? How will it be cleaned up?
- Do consumers know if the service idempotent or not (i.e. will repeated invocation of the service produce the same result each time or will the result change each time)
- If the service is invoked as part of a transaction, how will the service handle this?
- Is the service “long running”? Are there people/manual processes involved?