source: trunk/tools/ws.htm @ 18079

Last change on this file since 18079 was 18079, checked in by mistic100, 12 years ago

feature 2751: Redesign web API, webservices explorer

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