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.