[activemq-artemis] branch main updated: NO-JIRA update REST doc with caveats

[jb...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

jbertram pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/activemq-artemis.git


The following commit(s) were added to refs/heads/main by this push:
     new eefb748  NO-JIRA update REST doc with caveats
eefb748 is described below

commit eefb748552bea673920530ce87777fc6facb1117
Author: Justin Bertram <jb...@apache.org>
AuthorDate: Tue Jul 20 15:10:41 2021 -0500

    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 203344b..35d1e75 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