From eefb748552bea673920530ce87777fc6facb1117 Mon Sep 17 00:00:00 2001 From: Justin Bertram Date: Tue, 20 Jul 2021 15:10:41 -0500 Subject: [PATCH] NO-JIRA update REST doc with caveats --- docs/user-manual/en/rest.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/docs/user-manual/en/rest.md b/docs/user-manual/en/rest.md index 203344bb94..35d1e75bf4 100644 --- a/docs/user-manual/en/rest.md +++ b/docs/user-manual/en/rest.md @@ -3,7 +3,7 @@ The Apache ActiveMQ Artemis REST interface allows you to leverage the reliability and scalability features of Apache ActiveMQ Artemis over a simple REST/HTTP interface. The REST Interface implementation sits on top of an Apache ActiveMQ Artemis JMS API and -as such exposes JMS like concepts via REST. +as such exposes JMS-like concepts via REST. Using the REST interface Messages can be produced and consumed by sending and receiving simple HTTP messages that contain the content you want to push around. For instance, @@ -28,6 +28,25 @@ as a JMS message and distributed through core Apache ActiveMQ Artemis. Simple an Consuming messages from a queue or topic looks very similar. We'll discuss the entire interface in detail later. +## Caveats of Using the REST Interface + +Before adopting the REST interface it's important to recognize the potential trade-offs. + +* **There is no standard for REST messaging.** Any application which integrates with the + ActiveMQ Artemis REST messaging interface cannot then integrate with any other broker's + REST messaging interface without significant effort because every REST messaging + interface is different. Even the ActiveMQ Classic broker has its own REST messaging + interface which is different from Artemis'. +* **For most use-cases STOMP is better.** In just about any environment where a simple + HTTP client might be advantageous for messaging there usually also exists a STOMP client + implementation. STOMP is ubiquitous and *standardized* (i.e. it conforms to a public + specification) which means it can be used across various broker implementations with + few, if any, client changes. + +Messaging is almost always leveraged for _integrating_ disparate applications. Protocol +flexibility and interoperability are vital to such solutions. Consider these caveats +carefully before committing to a solution. + ## Goals of REST Interface Why would you want to use Apache ActiveMQ Artemis's REST interface? What are the goals