Message API
How can clients send commands, notifications (i.e. events), or other information to remote systems over HTTP while avoiding direct coupling to remote procedures?
There are many occasions in which message design cannot be driven entirely by the service owner. This is especially true in large organizations or in scenarios where business partners exchange data.
Service developers in situations like these need an API style that recognizes a set of related messages, but does not tie those messages to specific procedures.
Define messages which are not derived from the signatures of remote procedures. These messages may carry information on specific topics, tasks to execute, and events. Have the client send the message to a designated URI. Once the message is received at the server, examine its contents to determine the correct procedure to execute.
Services that have Message APIs receive one or more self-descriptive
message types at a given URI. Message APIs often use standardized
formats like SOAP, however they may avoid these formats too. Message APIs are often called Document APIs.
Clients use these services by sending messages to a designated URI.
Once the message is sent, the client may optionally block while waiting
for a response. When a message arrives at the server, a web service
deserializes and inspects the message, then selects an appropriate
procedure (i.e. handler) to process the request. The web service provides
a layer of indirection by insulating the client from the actual handler
(i.e. remote procedure). Once the handler has been invoked, it may
process the client's request and return a response. The client can then
extract the results and resume execution.