From a10f4f58c5d491ccafd8a7c33816b426d48e6314 Mon Sep 17 00:00:00 2001
From: Tim Otten <totten@civicrm.org>
Date: Wed, 27 Jan 2021 16:16:33 -0800
Subject: [PATCH] APIExplorer - Split "Rest" in two ("Rest" vs "curl")

We're serving a dual purpose of educating generally about the REST request,
and providing an example that is runnable.

However, we're not doing either well if the REST example is simultaneously
incorrect and an obscure block of text.

This splits it into two examples, one emphasizing general structure
and the other emphasizing precision/correctness.
---
 templates/CRM/Admin/Page/APIExplorer.js  | 11 ++++++++++-
 templates/CRM/Admin/Page/APIExplorer.tpl | 12 +++++++++++-
 2 files changed, 21 insertions(+), 2 deletions(-)

diff --git a/templates/CRM/Admin/Page/APIExplorer.js b/templates/CRM/Admin/Page/APIExplorer.js
index 45172a1b90..6ef22537bf 100644
--- a/templates/CRM/Admin/Page/APIExplorer.js
+++ b/templates/CRM/Admin/Page/APIExplorer.js
@@ -19,6 +19,7 @@
     chainTpl = _.template($('#api-chain-tpl').html()),
     docCodeTpl = _.template($('#doc-code-tpl').html()),
     joinTpl = _.template($('#join-tpl').html()),
+    restTpl = _.template($('#api-rest-tpl').html()),
 
     // The following apis do not use Api3SelectQuery so do not support advanced features like joins or OR
     NO_JOINS = ['Contact', 'Contribution', 'Pledge', 'Participant'],
@@ -699,6 +700,11 @@
    * Render the api request in various formats
    */
   function formatQuery() {
+    var http = {
+      url: CRM.config.resourceBase + "extern/rest.php",
+      method:  action.startsWith('get') ? 'GET' : 'POST',
+      query: {entity: entity, action: action, json: JSON.stringify(params), api_key: 'FIXME_USER_KEY', key: 'FIXME_SITE_KEY'}
+    };
     var i = 0, q = {
       smarty: "{crmAPI var='result' entity='" + entity + "' action='" + action + "'" + (params.sequential ? '' : ' sequential=0'),
       php: "$result = civicrm_api3('" + entity + "', '" + action + "'",
@@ -706,7 +712,9 @@
       cv: "cv api " + entity + '.' + action + ' ',
       drush: "drush cvapi " + entity + '.' + action + ' ',
       wpcli: "wp cv api " + entity + '.' + action + ' ',
-      rest: CRM.config.resourceBase + "extern/rest.php?entity=" + encodeURI(entity) + "&action=" + encodeURI(action) + "&api_key=FIXME_USER_KEY&key=FIXME_SITE_KEY&json=" + encodeURI(JSON.stringify(params))
+      curl: http.method === 'GET' ?
+        "curl '" + http.url + "?" + $.param(http.query) + "'"
+        : "curl -X " + http.method + " -d '" + $.param(http.query) +"' \\\n  '" + http.url + "'"
     };
     smartyPhp = [];
     $.each(params, function(key, value) {
@@ -743,6 +751,7 @@
     } else if (smartyPhp.length) {
       q.smarty = "{php}\n  " + smartyPhp.join("\n  ") + "\n{/php}\n" + q.smarty;
     }
+    $('#api-rest').html(restTpl(http));
     $.each(q, function(type, val) {
       $('#api-' + type).text(val);
     });
diff --git a/templates/CRM/Admin/Page/APIExplorer.tpl b/templates/CRM/Admin/Page/APIExplorer.tpl
index 2be5f1f3c4..f17588fafe 100644
--- a/templates/CRM/Admin/Page/APIExplorer.tpl
+++ b/templates/CRM/Admin/Page/APIExplorer.tpl
@@ -271,7 +271,7 @@
       <div id="api-generated-wraper">
         <table id="api-generated" border=1>
           <caption>{ts}Code{/ts}</caption>
-          <tr><td>Rest</td><td><pre id="api-rest"></pre></td></tr>
+          <tr><td>Rest</td><td><div id="api-rest"></div></td></tr>
           <tr><td>Smarty</td><td><pre class="linenums" id="api-smarty" title='smarty syntax (for get actions)'></pre></td></tr>
           <tr><td>Php</td><td><pre class="linenums" id="api-php" title='php syntax'></pre></td></tr>
           <tr><td>Javascript</td><td><pre class="linenums" id="api-json" title='javascript syntax'></pre></td></tr>
@@ -282,6 +282,7 @@
           {if $config->userSystem->is_wordpress}
             <tr><td><a href="http://wp-cli.org/" target="_blank">wp-cli</a></td><td><pre id="api-wpcli" title='wp-cli syntax'></pre></td></tr>
           {/if}
+          <tr><td><a href="https://curl.se/">curl</a></td><td><pre id="api-curl"></pre></td></tr>
         </table>
       </div>
       <div class="crm-submit-buttons">
@@ -347,6 +348,15 @@
 </div>
 </div>
 {strip}
+<script type="text/template" id="api-rest-tpl">
+  <pre><%- method %> <%- url %></pre>
+  <ul>{literal}
+    <% _.forEach(query, function(value, field){ %>
+      <li><b><%- field %></b>: <pre style="display: inline-block"><%- value %></pre></li>
+    <% }); %>
+  {/literal}</ul>
+</script>
+
 <script type="text/template" id="api-param-tpl">
   <tr class="api-param-row">
     <td>
-- 
2.25.1