source: trunk/tools/ws.htm @ 28575

Last change on this file since 28575 was 28495, checked in by mistic100, 10 years ago

display request url and params in WS explorer
  • Property svn:eol-style set to LF
File size: 18.8 KB
Line 
1<!DOCTYPE html>
2<html lang="en" dir="ltr">
3<head>
4  <meta charset="utf-8">
5  <title>Piwigo web API (web-services) explorer</title>
6
7  <link rel="stylesheet" href="http://cdn.jsdelivr.net/tiptip/1.3/tipTip.css">
8
9  <style>
10  /* BEGIN CSS RESET
11    http://meyerweb.com/eric/tools/css/reset
12    v2.0 | 20110126 | License: none (public domain) */
13  html, body, div, span, applet, object, iframe, h1, h2, h3, h4, h5, h6, p, blockquote, pre, a, abbr, acronym, address, big, cite, code,
14  del, dfn, em, img, ins, kbd, q, s, samp, small, strike, strong, sub, sup, tt, var, b, u, i, center, dl, dt, dd, ol, ul, li,
15  fieldset, form, label, legend, table, caption, tbody, tfoot, thead, tr, th, td, article, aside, canvas, details, embed,
16  figure, figcaption, footer, header, hgroup, menu, nav, output, ruby, section, summary, time, mark, audio, video
17  {margin:0;padding:0;border:0;font-size:100%;vertical-align:baseline;}
18
19  article, aside, details, figcaption, figure, footer, header, hgroup, menu, nav, section {display:block;}
20  body {line-height:1.1;}
21  blockquote, q {quotes:none;}
22  blockquote:before, blockquote:after, q:before, q:after {content:'';content:none;}
23  table {border-collapse:collapse;border-spacing:0;}
24  /* END CSS RESET */
25
26  html {font-family:"Corbel","Lucida Grande","Verdana",sans-serif;color:#222;font-size:13px;}
27
28  a {color:#247EBF;text-decoration:none;}
29  a:hover {color:#EB9C39;border-bottom-width:1px;border-style:dotted;text-shadow:1px 1px 0 #ddd;}
30
31  blockquote {border:1px solid #cdcdcd;background:#F9F9F9;padding:8px;}
32  hr {margin:10px 30px;color:#fff;}
33  ul {margin-left:25px;}
34  p {margin:8px 0;}
35
36  h1 {color:#fff;font-size:26px;padding:10px 15px;text-shadow:1px 1px 0 #999;
37    background:#45484d;background:linear-gradient(to bottom, #45484d 0%,#333333 100%);
38  }
39  h2 {color:#fff;font-size:20px;padding:5px 10px;text-shadow:1px 1px 0 #555;
40    background:#f2a841;background:linear-gradient(to bottom, #f2a841 0%,#ef6b13 100%);
41  }
42  h2#errorWrapper {color:#F42C00;font-weight:normal;
43    background:#eaeaea;background:linear-gradient(to bottom, #eaeaea 0%, #afafaf 100%);
44  }
45  h3 {display:inline-block;padding:5px 10px;color:#555;font-weight:bold;text-align:center;
46    border-radius:8px 8px 0 0;text-shadow:1px 1px 0 #bbb;
47    background:#f2f2f2;background:linear-gradient(to bottom, #f2f2f2 0%,#cecece 100%);
48  }
49
50  #the_header {border-bottom:1px solid #cdcdcd;margin-bottom:1px;}
51  #the_footer {background:#EAEAEA;border-top:1px solid #cdcdcd;padding:10px;clear:both;}
52
53  #the_methods {width:250px;float:left;border-style:solid;border-color:#cdcdcd;border-width:1px 1px 0 0;
54    background-image:url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAMAAAADCAIAAADZSiLoAAAAH0lEQVQImSXHMQEAMAwCMOrfK0jIjuVL2gLBzyHJtgd7wBdU3Vt/7AAAAABJRU5ErkJggg==);
55  }
56  #methodsList {font-size:1.1em;margin:5px 0 10px 10px;list-style:none;}
57  #methodsList li:before {content:"\203A\00A0";font-weight:bold;color:#EB9C39;font-size:1.1em;}
58  #methodsList li:hover:before {content:"\00A0\203A";}
59
60  #the_page {margin-left:252px;border-style:solid;border-color:#cdcdcd;border-width:1px 0 0 1px;}
61  #the_content {padding:10px;}
62
63  #methodParams {margin-right:230px;}
64  #methodParams thead td {background:#DEE3E9;font-weight:bold;padding:2px 5px;}
65  #methodParams td {padding:2px;border:1px solid #cdcdcd;vertical-align:middle;}
66  #methodParams tbody tr:nth-child(even) {background:#f7f7f7;}
67  #methodParams tbody tr td:first-child {font-family:monospace;font-size:0.95em;}
68  #methodParams td.mini {width:0px;text-align:center;}
69  #methodParams tfoot {font-size:0.95em;}
70  #methodParams td.input {text-align:center;}
71  #methodParams td.input input[type="text"] {width:97%;font-size:0.9em;background:#f7f7f7;border:1px solid #ccc;border-radius:2px;}
72  #methodParams td.input input[type="text"]:hover, #methodParams td.input input[type="text"]:focus {border-color:#C7E2F1;border-top-color:#96BCD7;background:#fff;}
73  #methodParams .type {display:inline-block;width:16px;height:16px;font-size:12px;line-height:16px;background:#ddd;border-radius:8px;font-weight:bold;text-align:center;color:#222;}
74  #methodParams .subtype {vertical-align:super;}
75
76  #testForm {float:right;}
77  #testForm td {padding:2px 0;}
78  #testForm tr:last-child td {padding:8px 0 5px 0;}
79  #testForm blockquote {width:200px;}
80
81  #introMessage {font-size:1.1em;}
82  #urlForm {margin-bottom:10px;}
83
84  a.button {color:#fff;padding:3px 8px;border:1px solid #91bb5c;font-size:0.9em;margin-right:3px;display:inline-block;
85    border-radius:5px;text-shadow:1px 1px 0 #666;
86    background:#84bb3c;background:linear-gradient(to bottom, #84bb3c 0%, #3f5a1d 100%);
87  }
88  a.button:hover {color:#E5FF00;}
89
90  .methodInfo {float:right;display:inline-block;width:16px;height:16px;font-size:12px;line-height:16px;background:#555;border-radius:8px;font-family:"Times New Roman",sans-serif;font-style:italic;font-weight:bold;text-align:center;color:#fff;}
91  .methodInfo:hover {border:none;text-shadow:none;background:#888;cursor:pointer;color:#fff;}
92  #tiptip_content { font-size:12px; }
93
94  #iframeWrapper {width:100%;height:300px;padding:3px 3px 20px 3px;background:#F9F9F9;border:1px solid #cdcdcd;overflow:hidden;position:relative;}
95  iframe {width:100%;height:100%;background:#fff;}
96
97  div.onlys {background:#faa;color:#fff;border:1px solid #f22;padding:.25em .5em;display:table;border-radius:4px;margin-bottom:0.5em;}
98  </style>
99
100</head>
101
102<body>
103<a name="top"></a>
104
105<div id="the_header">
106  <h1>Piwigo web API (web-services) explorer</h1>
107</div> <!-- the_header -->
108
109<div id="the_methods">
110  <h2>Available methods</h2>
111
112  <ul id="methodsList">
113  </ul>
114</div> <!-- the_methods -->
115
116<div id="the_page">
117  <h2 id="methodName" style="display:none;"></h2>
118  <h2 id="errorWrapper" style="display:none;"></h2>
119
120  <div id="the_content">
121    <form id="urlForm" style="display:none;">
122      <input type="text" name="ws_url" size="60">
123      <input type="submit" value="Go!">
124    </form>
125
126    <blockquote id="introMessage">
127      <p>
128        <b>API = Application Programming Interface.</b><br>
129        This is the way other applications can communicate with Piwigo. This feature is also know as Web Services.
130      </p>
131
132      <p>Examples:</p>
133      <ul>
134        <li>Wordpress (web blog software) can display random photos from a Piwigo gallery in its sidebar</li>
135        <li>Lightroom (photo management software for desktop) can create albums and upload photos to Piwigo</li>
136      </ul>
137
138      <p>
139        This page lists all API methods available on your Piwigo installation, part of the Piwigo core or added by third-party plugins.
140        For each method you can consult required and optional parameters, and even test them in direct live!
141      </p>
142
143      <p>
144        For more information you can consult our Wiki <a href="http://piwigo.org/doc/doku.php?id=dev:webapi:start" target="_blank">Piwigo Web API</a> and <a href="http://piwigo.org/forum" target="_blank">our forums</a>.
145      </p>
146    </blockquote> <!-- introMessage -->
147
148
149    <form id="methodWrapper" style="display:none;">
150      <div id="methodDescription" style="display:none;">
151        <h3>Description</h3>
152        <blockquote>
153        </blockquote>
154        <br>
155      </div> <!-- methodDescription -->
156
157      <div id="testForm">
158        <h3>Test</h3>
159        <blockquote>
160          <table>
161            <tr>
162              <td>Request format :</td>
163              <td>
164                <select id="requestFormat">
165                  <option value="get" selected>GET</option>
166                  <option value="post">POST</option>
167                </select>
168              </td>
169            </tr>
170            <tr>
171              <td>Response format :</td>
172              <td>
173                <select id="responseFormat">
174                  <option value="rest" selected>REST (xml)</option>
175                  <option value="json">JSON</option>
176                  <option value="php">PHP serial</option>
177                  <option value="xmlrpc">XML RPC</option>
178                </select>
179              </td>
180            </tr>
181            <tr>
182              <td colspan="2">
183                <a href="#" class="button" id="invokeMethod">INVOKE</a>
184                <a href="#" class="button" id="invokeMethodBlank">INVOKE (new window)</a>
185              </td>
186            </tr>
187          </table>
188        </blockquote>
189      </div> <!-- testForm -->
190
191      <div id="methodParams">
192        <h3>Method parameters</h3>
193        <table>
194          <thead>
195            <tr>
196              <td style="width:150px;">Name</td>
197              <td class="mini">Extra</td>
198              <td class="mini">Type</td>
199              <td style="width:300px;">Value</td>
200              <td class="mini">Send</td>
201            </tr>
202          </thead>
203
204          <tbody>
205          </tbody>
206
207          <tfoot>
208            <tr>
209              <td colspan="5">
210                <b>*</b>: required, <b>?</b>: optional, <b>[]</b>: can be an array (use a pipe | to split values)<br>
211                <b>B</b>: boolean, <b>I</b>: integer, <b>F</b>: float, <b>+</b>: positive, <b>&oslash;</b>: not null
212              </td>
213            </tr>
214          </tfoot>
215        </table>
216      </div> <!-- methodParams -->
217     
218      <div id="requestDisplay" style="display:none;">
219        <br>
220        <h3>Request</h3>
221        <blockquote>
222          <pre class="url"></pre>
223          <pre class="params"></pre>
224        </blockquote>
225      </div> <!-- requestDisplay -->
226
227      <br>
228      <h3>Result</h3>
229      <div id="iframeWrapper">
230        <iframe src="" id="invokeFrame" name="invokeFrame"></iframe>
231        <a href="#iframe-bottom" id="increaseIframe"><b>&darr;</b> increase height</a> &#8226;
232        <a href="#iframe-bottom" id="decreaseIframe"><b>&uarr;</b> decrease height</a>
233        <a name="iframe-bottom"></a>
234      </div>
235    </form> <!-- iframeWrapper -->
236
237    <!-- hidden form for POST submition -->
238    <form method="post" action="" target="" id="invokeForm" style="display:none;"></form>
239
240  </div> <!-- the_content -->
241
242</div> <!-- the_page -->
243
244<div id="the_footer">
245  Copyright &copy; 2002-2013 <a href="http://piwigo.org">Piwigo Team</a>
246</div> <!-- the_footer -->
247
248<script src="http://code.jquery.com/jquery-1.9.1.min.js"></script>
249<script src="https://cdn.jsdelivr.net/tiptip/1.3/jquery.tipTip.minified.js"></script>
250
251<script>
252// global vars
253var cachedMethods = new Array;
254var ws_url = "http://";
255
256// automatic detection of ws_url
257match = document.location.toString().match(/^(https?.*\/)tools\/ws\.html?/);
258if (match==null) {
259  askForUrl();
260}
261else {
262  ws_url = match[1]+'ws.php';
263  getMethodList();
264}
265
266// manual set of ws_url
267$("#urlForm").submit(function() {
268  ws_url = $(this).children("input[name='ws_url']").val();
269  getMethodList();
270  return false;
271});
272
273// invoke buttons
274$("#invokeMethod").click(function() {
275  invokeMethod($("#methodName").html(), false);
276  return false;
277});
278$("#invokeMethodBlank").click(function() {
279  invokeMethod($("#methodName").html(), true);
280  return false;
281});
282
283// resizable iframe
284$("#increaseIframe").click(function() {
285  $("#iframeWrapper").css('height', $("#iframeWrapper").height()+100);
286  adaptHeight();
287});
288$("#decreaseIframe").click(function() {
289  if ($("#iframeWrapper").height() > 200) {
290    $("#iframeWrapper").css('height', $("#iframeWrapper").height()-100);
291    adaptHeight();
292  }
293});
294
295// mask all wrappers
296function resetDisplay() {
297  $("#errorWrapper").hide();
298  $("#methodWrapper").hide();
299  $("#methodName").hide();
300  $("#urlForm").hide();
301  $("#methodDescription blockquote").empty();
302  $("#methodDescription").hide();
303  $("#requestDisplay").hide();
304  $("#invokeFrame").attr('src','');
305}
306
307// give the same size to methods list and main page
308function adaptHeight() {
309  $("#the_page").css('height', 'auto');
310  $("#the_methods").css('height', 'auto');
311
312  min_h = $(window).height()-$("#the_header").outerHeight()-$("#the_footer").outerHeight()-3;
313  h = Math.max(min_h, Math.max($("#the_methods").height(), $("#the_page").height()));
314
315  $("#the_page").css('height', h);
316  $("#the_methods").css('height', h);
317}
318
319// display error wrapper
320function displayError(error) {
321  resetDisplay();
322  $("#errorWrapper").html("<b>Error:</b> "+ error).show();
323  adaptHeight();
324}
325
326// display ws_url form
327function askForUrl() {
328  displayError("can't contact web-services, please give absolute url to 'ws.php'");
329  if ($("#urlForm input[name='ws_url']").val() == "") {
330    $("#urlForm input[name='ws_url']").val(ws_url);
331  }
332  $("#urlForm").show();
333}
334
335// parse Piwigo JSON
336function parsePwgJSON(json) {
337  try {
338    resp = jQuery.parseJSON(json);
339    if (resp==null | resp.result==null | resp.stat==null | resp.stat!='ok') {
340      throw new Error();
341    }
342  }
343  catch(e) {
344    displayError("unable to parse JSON string");
345    resp = {"stat": "ko", "result": "null"};
346  }
347
348  return resp.result;
349}
350
351// fetch methods list
352function getMethodList() {
353  resetDisplay();
354
355  $.ajax({
356    type: "GET",
357    url: ws_url,
358    data: { format: "json", method: "reflection.getMethodList" }
359  }).done(function(result) {
360    result = parsePwgJSON(result);
361
362    if (result!=null) {
363      methods = result.methods;
364
365      var ml = '';
366      for (var i=0; i<methods.length; i++)
367      {
368        ml += '<li><a href="#top">'+ methods[i]+'</a></li>';
369      }
370      $("#methodsList").html(ml).show();
371
372      adaptHeight();
373
374      // trigger method selection
375      $("#methodsList li a").click(function() {
376        selectMethod($(this).html());
377      });
378    }
379  }).error(function(jqXHR, textStatus, errorThrown) {
380    askForUrl();
381  });
382}
383
384// select method
385function selectMethod(methodName) {
386  $("#introMessage").hide();
387  $("#tiptip_holder").fadeOut(200);
388
389  if (cachedMethods[ methodName ]) {
390    fillNewMethod(methodName);
391  }
392  else {
393    $.ajax({
394      type: "GET",
395      url: ws_url,
396      data: { format: "json", method: "reflection.getMethodDetails", methodName: methodName }
397    }).done(function(result) {
398      result = parsePwgJSON(result);
399
400      if (result!=null) {
401                                if (result.options.post_only || result.options.admin_only) {
402                                        var onlys = '<div class="onlys">';
403                                        if (result.options.post_only) {
404                                                onlys+= 'POST only. ';
405                                        }
406                                        if (result.options.admin_only) {
407                                                onlys+= 'Admin only. ';
408                                        }
409                                        onlys+= '</div>';
410                                       
411                                        result.description = onlys + result.description;
412                                }
413        cachedMethods[ methodName ] = result;
414        fillNewMethod(methodName);
415      }
416    }).error(function(jqXHR, textStatus, errorThrown) {
417      displayError("unknown error");
418    });
419  }
420}
421
422// display method details
423function fillNewMethod(methodName) {
424  resetDisplay();
425
426  method = cachedMethods[ methodName ];
427
428  $("#methodName").html(method.name).show();
429
430  if (method.description != "") {
431    $("#methodDescription blockquote").html(method.description);
432    $("#methodDescription").show();
433  }
434
435  $("#requestFormat").val(method.options.post_only ? 'post' : 'get');
436
437  var methodParams = '';
438  if (method.params && method.params.length>0) {
439    for (var i=0; i<method.params.length; i++) {
440      var param = method.params[i],
441          isOptional = param.optional,
442          acceptArray = param.acceptArray,
443          defaultValue = param.defaultValue == null ? '' : param.defaultValue,
444          info = param.info == null ? '' : '<a class="methodInfo" title="'+ param.info.replace(/"/g, '&quot;') + '">i</a>',
445          type = '';
446
447      if (param.type.match(/bool/)) type+= '<span class=type>B</span>';
448      if (param.type.match(/int/)) type+= '<span class=type>I</span>';
449      if (param.type.match(/float/)) type+= '<span class=type>F</span>';
450      if (param.type.match(/positive/)) type+= '<span class=subtype>+</span>';
451      if (param.type.match(/notnull/)) type+= '<span class=subtype>&oslash;</span>';
452
453      // if an array is direclty printed, the delimiter is a comma where we use a pipe
454      if (typeof defaultValue == 'object') {
455        defaultValue = defaultValue.join('|');
456      }
457
458      methodParams+= '<tr>'+
459        '<td>'+ param.name + info +'</td>'+
460        '<td class="mini">'+ (isOptional ? '?':'*') + (acceptArray ? ' []':'') +'</td>'+
461        '<td class="mini">'+ type +'</td>'+
462        '<td class="input"><input type="text" class="methodParameterValue" data-id="'+ i +'" value="'+ defaultValue +'"></td>'+
463        '<td class="mini"><input type="checkbox" class="methodParameterSend" data-id="'+ i +'" '+ (isOptional ? '':'checked="checked"') +'></td>'+
464      '</tr>';
465    }
466        }
467  else {
468    methodParams = '<tr><td colspan="4">This method takes no parameters</td></tr>';
469  }
470
471  $("#methodParams tbody").html(methodParams);
472  $("#methodWrapper").show();
473
474  adaptHeight();
475
476  // trigger field modification
477  $("input.methodParameterValue").change(function() {
478    $("input.methodParameterSend[data-id='"+ $(this).data('id') +"']").attr('checked', 'checked');
479  });
480
481  // tiptip
482  $(".methodInfo").tipTip({
483    maxWidth:"300px",
484    defaultPosition:"right",
485    delay:0
486  });
487}
488
489// invoke method
490function invokeMethod(methodName, newWindow) {
491        var method = cachedMethods[ methodName ];
492
493  var reqUrl = ws_url +"?format="+ $("#responseFormat").val();
494
495  // GET
496  if ($("#requestFormat").val() == 'get') {
497    reqUrl+= "&method="+ methodName;
498
499    for (var i=0; i<method.params.length; i++) {
500      if (! $("input.methodParameterSend[data-id='"+ i +"']").is(":checked")) {
501        continue;
502      }
503
504      var paramValue = $("input.methodParameterValue[data-id='"+ i +"']").val();
505
506      var paramSplitted = paramValue.split('|');
507      if (method.params[i].acceptArray &&  paramSplitted.length > 1) {
508        $.each(paramSplitted, function(v) {
509          reqUrl+= '&'+ method.params[i].name +'[]='+ paramSplitted[v];
510        });
511      }
512      else {
513        reqUrl+= '&'+ method.params[i].name +'='+ paramValue;
514      }
515    }
516
517    if (newWindow) {
518      window.open(reqUrl);
519    }
520    else {
521      $("#invokeFrame").attr('src', reqUrl);
522    }
523   
524    $('#requestDisplay').show()
525      .find('.url').html(reqUrl).end()
526      .find('.params').hide();
527  }
528  // POST
529  else {
530    var params = {};
531   
532    var form = $("#invokeForm");
533    form.attr('action', reqUrl);
534
535    var t = '<input type="hidden" name="method" value="'+ methodName +'">';
536
537    for (var i=0; i<method.params.length; i++) {
538      if (! $("input.methodParameterSend[data-id='"+ i +"']").is(":checked")) {
539        continue;
540      }
541
542      var paramValue = $("input.methodParameterValue[data-id='"+ i +"']").val(),
543          paramName = method.params[i].name,
544          paramSplitted = paramValue.split('|');
545           
546      if (method.params[i].acceptArray &&  paramSplitted.length > 1) {
547        params[paramName] = [];
548       
549        $.each(paramSplitted, function(i, value) {
550          params[paramName].push(value);
551          t+= '<input type="hidden" name="'+ paramName +'[]" value="'+ value +'">';
552        });
553      }
554      else {
555        params[paramName] = paramValue;
556        t+= '<input type="hidden" name="'+ paramName +'" value="'+ paramValue +'">';
557      }
558    }
559
560    form.html(t);
561    form.attr('target', newWindow ? "_blank" : "invokeFrame");
562    form.submit();
563   
564    $('#requestDisplay').show()
565      .find('.url').html(reqUrl).end()
566      .find('.params').show().html(JSON.stringify(params, null, 4));
567  }
568
569  return false;
570}
571</script>
572
573</body>
574</html>
Note: See TracBrowser for help on using the repository browser.