Single Message Argument
A web service receives data through an RPC API . Service developers are using a Code-First strategy (see The Book for more information).
How can a web service with an RPC API become less brittle and easily accommodate new parameters over time without breaking clients?
RPC APIs can be especially brittle. Services with this type of API often have long parameter lists. If the need ever arises to add or remove parameters, one often can't avoid a breaking change. Service operations with these kinds of "flat APIs" are inherently inflexible and fragile. How can services with RPC APIs become more flexible and support the introduction of new parameters in a way that is backward compatible?
Design each service operation such that it only receives a single message parameter that contains all of the data for a request.
The Single-Message Argument pattern suggests that service developers who use a Code-First strategy should refrain from creating signatures with long parameter lists. Signatures like these typically signal the underlying framework to impose a strict ordering of parameters which, in turn, increases client-service coupling and makes it more difficult to evolve the client and service at different rates. RPC APIs can instead be designed to receive a single message argument. Each child element in these messages may be required or optional, the allowed values may be constrained or open-ended, and the order in which data is serialized may be prescribed or be allowed to vary. By deliberately pushing all arguments down into a single message argument, the service designer has more control over message formatting and serialization.