2014-07-06 13:21:10 +02:00
<!DOCTYPE html>
< html lang = "en" dir = "ltr" >
< head >
< meta charset = "utf-8" >
< title > Piwigo web API (web-services) explorer< / title >
< link rel = "stylesheet" href = "http://cdn.jsdelivr.net/tiptip/1.3/tipTip.css" >
< style >
/* BEGIN CSS RESET
http://meyerweb.com/eric/tools/css/reset
v2.0 | 20110126 | License: none (public domain) */
html, body, div, span, applet, object, iframe, h1, h2, h3, h4, h5, h6, p, blockquote, pre, a, abbr, acronym, address, big, cite, code,
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,
fieldset, form, label, legend, table, caption, tbody, tfoot, thead, tr, th, td, article, aside, canvas, details, embed,
figure, figcaption, footer, header, hgroup, menu, nav, output, ruby, section, summary, time, mark, audio, video
{margin:0;padding:0;border:0;font-size:100%;vertical-align:baseline;}
article, aside, details, figcaption, figure, footer, header, hgroup, menu, nav, section {display:block;}
body {line-height:1.1;}
blockquote, q {quotes:none;}
blockquote:before, blockquote:after, q:before, q:after {content:'';content:none;}
table {border-collapse:collapse;border-spacing:0;}
/* END CSS RESET */
html {font-family:"Corbel","Lucida Grande","Verdana",sans-serif;color:#222;font-size:13px;}
a {color:#247EBF;text-decoration:none;}
a:hover {color:#EB9C39;border-bottom-width:1px;border-style:dotted;text-shadow:1px 1px 0 #ddd;}
blockquote {border:1px solid #cdcdcd;background:#F9F9F9;padding:8px;}
hr {margin:10px 30px;color:#fff;}
ul {margin-left:25px;}
p {margin:8px 0;}
h1 {color:#fff;font-size:26px;padding:10px 15px;text-shadow:1px 1px 0 #999;
background:#45484d;background:linear-gradient(to bottom, #45484d 0%,#333333 100%);
}
h2 {color:#fff;font-size:20px;padding:5px 10px;text-shadow:1px 1px 0 #555;
background:#f2a841;background:linear-gradient(to bottom, #f2a841 0%,#ef6b13 100%);
}
h2#errorWrapper {color:#F42C00;font-weight:normal;
background:#eaeaea;background:linear-gradient(to bottom, #eaeaea 0%, #afafaf 100%);
}
h3 {display:inline-block;padding:5px 10px;color:#555;font-weight:bold;text-align:center;
border-radius:8px 8px 0 0;text-shadow:1px 1px 0 #bbb;
background:#f2f2f2;background:linear-gradient(to bottom, #f2f2f2 0%,#cecece 100%);
}
#the_header {border-bottom:1px solid #cdcdcd;margin-bottom:1px;}
#the_footer {background:#EAEAEA;border-top:1px solid #cdcdcd;padding:10px;clear:both;}
#the_methods {width:250px;float:left;border-style:solid;border-color:#cdcdcd;border-width:1px 1px 0 0;
background-image:url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAMAAAADCAIAAADZSiLoAAAAH0lEQVQImSXHMQEAMAwCMOrfK0jIjuVL2gLBzyHJtgd7wBdU3Vt/7AAAAABJRU5ErkJggg==);
}
#methodsList {font-size:1.1em;margin:5px 0 10px 10px;list-style:none;}
#methodsList li:before {content:"\203A\00A0";font-weight:bold;color:#EB9C39;font-size:1.1em;}
#methodsList li:hover:before {content:"\00A0\203A";}
#the_page {margin-left:252px;border-style:solid;border-color:#cdcdcd;border-width:1px 0 0 1px;}
#the_content {padding:10px;}
#methodParams {margin-right:230px;}
#methodParams thead td {background:#DEE3E9;font-weight:bold;padding:2px 5px;}
#methodParams td {padding:2px;border:1px solid #cdcdcd;vertical-align:middle;}
#methodParams tbody tr:nth-child(even) {background:#f7f7f7;}
#methodParams tbody tr td:first-child {font-family:monospace;font-size:0.95em;}
#methodParams td.mini {width:0px;text-align:center;}
#methodParams tfoot {font-size:0.95em;}
#methodParams td.input {text-align:center;}
#methodParams td.input input[type="text"] {width:97%;font-size:0.9em;background:#f7f7f7;border:1px solid #ccc;border-radius:2px;}
#methodParams td.input input[type="text"]:hover, #methodParams td.input input[type="text"]:focus {border-color:#C7E2F1;border-top-color:#96BCD7;background:#fff;}
#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;}
#methodParams .subtype {vertical-align:super;}
#testForm {float:right;}
#testForm td {padding:2px 0;}
#testForm tr:last-child td {padding:8px 0 5px 0;}
#testForm blockquote {width:200px;}
#introMessage {font-size:1.1em;}
#urlForm {margin-bottom:10px;}
a.button {color:#fff;padding:3px 8px;border:1px solid #91bb5c;font-size:0.9em;margin-right:3px;display:inline-block;
border-radius:5px;text-shadow:1px 1px 0 #666;
background:#84bb3c;background:linear-gradient(to bottom, #84bb3c 0%, #3f5a1d 100%);
}
a.button:hover {color:#E5FF00;}
.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;}
.methodInfo:hover {border:none;text-shadow:none;background:#888;cursor:pointer;color:#fff;}
#tiptip_content { font-size:12px; }
#iframeWrapper {width:100%;height:300px;padding:3px 3px 20px 3px;background:#F9F9F9;border:1px solid #cdcdcd;overflow:hidden;position:relative;}
iframe {width:100%;height:100%;background:#fff;}
div.onlys {background:#faa;color:#fff;border:1px solid #f22;padding:.25em .5em;display:table;border-radius:4px;margin-bottom:0.5em;}
< / style >
< / head >
< body >
< a name = "top" > < / a >
< div id = "the_header" >
< h1 > Piwigo web API (web-services) explorer< / h1 >
< / div > <!-- the_header -->
< div id = "the_methods" >
< h2 > Available methods< / h2 >
< ul id = "methodsList" >
< / ul >
< / div > <!-- the_methods -->
< div id = "the_page" >
< h2 id = "methodName" style = "display:none;" > < / h2 >
< h2 id = "errorWrapper" style = "display:none;" > < / h2 >
< div id = "the_content" >
< form id = "urlForm" style = "display:none;" >
< input type = "text" name = "ws_url" size = "60" >
< input type = "submit" value = "Go!" >
< / form >
< blockquote id = "introMessage" >
< p >
< b > API = Application Programming Interface.< / b > < br >
This is the way other applications can communicate with Piwigo. This feature is also know as Web Services.
< / p >
< p > Examples:< / p >
< ul >
< li > Wordpress (web blog software) can display random photos from a Piwigo gallery in its sidebar< / li >
< li > Lightroom (photo management software for desktop) can create albums and upload photos to Piwigo< / li >
< / ul >
< p >
This page lists all API methods available on your Piwigo installation, part of the Piwigo core or added by third-party plugins.
For each method you can consult required and optional parameters, and even test them in direct live!
< / p >
< p >
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 > .
< / p >
< / blockquote > <!-- introMessage -->
< form id = "methodWrapper" style = "display:none;" >
< div id = "methodDescription" style = "display:none;" >
< h3 > Description< / h3 >
< blockquote >
< / blockquote >
< br >
< / div > <!-- methodDescription -->
< div id = "testForm" >
< h3 > Test< / h3 >
< blockquote >
< table >
< tr >
< td > Request format :< / td >
< td >
< select id = "requestFormat" >
< option value = "get" selected > GET< / option >
< option value = "post" > POST< / option >
< / select >
< / td >
< / tr >
< tr >
< td > Response format :< / td >
< td >
< select id = "responseFormat" >
< option value = "rest" selected > REST (xml)< / option >
< option value = "json" > JSON< / option >
< option value = "php" > PHP serial< / option >
< option value = "xmlrpc" > XML RPC< / option >
< / select >
< / td >
< / tr >
< tr >
< td colspan = "2" >
< a href = "#" class = "button" id = "invokeMethod" > INVOKE< / a >
< a href = "#" class = "button" id = "invokeMethodBlank" > INVOKE (new window)< / a >
< / td >
< / tr >
< / table >
< / blockquote >
< / div > <!-- testForm -->
< div id = "methodParams" >
< h3 > Method parameters< / h3 >
< table >
< thead >
< tr >
< td style = "width:150px;" > Name< / td >
< td class = "mini" > Extra< / td >
< td class = "mini" > Type< / td >
< td style = "width:300px;" > Value< / td >
< td class = "mini" > Send< / td >
< / tr >
< / thead >
< tbody >
< / tbody >
< tfoot >
< tr >
< td colspan = "5" >
< b > *< / b > : required, < b > ?< / b > : optional, < b > []< / b > : can be an array (use a pipe | to split values)< br >
< b > B< / b > : boolean, < b > I< / b > : integer, < b > F< / b > : float, < b > +< / b > : positive, < b > ø < / b > : not null
< / td >
< / tr >
< / tfoot >
< / table >
< / div > <!-- methodParams -->
2015-07-05 19:03:18 +02:00
< div id = "requestDisplay" style = "display:none;" >
< br >
< h3 > Request< / h3 >
< blockquote >
< pre class = "url" > < / pre >
< pre class = "params" > < / pre >
< / blockquote >
< / div > <!-- requestDisplay -->
2014-07-06 13:21:10 +02:00
2015-07-05 19:03:18 +02:00
< br >
2014-07-06 13:21:10 +02:00
< h3 > Result< / h3 >
< div id = "iframeWrapper" >
< iframe src = "" id = "invokeFrame" name = "invokeFrame" > < / iframe >
< a href = "#iframe-bottom" id = "increaseIframe" > < b > ↓ < / b > increase height< / a > •
< a href = "#iframe-bottom" id = "decreaseIframe" > < b > ↑ < / b > decrease height< / a >
< a name = "iframe-bottom" > < / a >
< / div >
< / form > <!-- iframeWrapper -->
<!-- hidden form for POST submition -->
< form method = "post" action = "" target = "" id = "invokeForm" style = "display:none;" > < / form >
< / div > <!-- the_content -->
< / div > <!-- the_page -->
< div id = "the_footer" >
Copyright © 2002-2013 < a href = "http://piwigo.org" > Piwigo Team< / a >
< / div > <!-- the_footer -->
< script src = "http://code.jquery.com/jquery-1.9.1.min.js" > < / script >
< script src = "https://cdn.jsdelivr.net/tiptip/1.3/jquery.tipTip.minified.js" > < / script >
< script >
// global vars
var cachedMethods = new Array;
var ws_url = "http://";
// automatic detection of ws_url
match = document.location.toString().match(/^(https?.*\/)tools\/ws\.html?/);
if (match==null) {
askForUrl();
}
else {
ws_url = match[1]+'ws.php';
getMethodList();
}
// manual set of ws_url
$("#urlForm").submit(function() {
ws_url = $(this).children("input[name='ws_url']").val();
getMethodList();
return false;
});
// invoke buttons
$("#invokeMethod").click(function() {
invokeMethod($("#methodName").html(), false);
return false;
});
$("#invokeMethodBlank").click(function() {
invokeMethod($("#methodName").html(), true);
return false;
});
// resizable iframe
$("#increaseIframe").click(function() {
$("#iframeWrapper").css('height', $("#iframeWrapper").height()+100);
adaptHeight();
});
$("#decreaseIframe").click(function() {
if ($("#iframeWrapper").height() > 200) {
$("#iframeWrapper").css('height', $("#iframeWrapper").height()-100);
adaptHeight();
}
});
// mask all wrappers
function resetDisplay() {
$("#errorWrapper").hide();
$("#methodWrapper").hide();
$("#methodName").hide();
$("#urlForm").hide();
$("#methodDescription blockquote").empty();
$("#methodDescription").hide();
2015-07-05 19:03:18 +02:00
$("#requestDisplay").hide();
2014-07-06 13:21:10 +02:00
$("#invokeFrame").attr('src','');
}
// give the same size to methods list and main page
2015-07-05 19:03:18 +02:00
function adaptHeight() {
2014-07-06 13:21:10 +02:00
$("#the_page").css('height', 'auto');
$("#the_methods").css('height', 'auto');
min_h = $(window).height()-$("#the_header").outerHeight()-$("#the_footer").outerHeight()-3;
h = Math.max(min_h, Math.max($("#the_methods").height(), $("#the_page").height()));
$("#the_page").css('height', h);
$("#the_methods").css('height', h);
}
// display error wrapper
function displayError(error) {
resetDisplay();
$("#errorWrapper").html("< b > Error:< / b > "+ error).show();
adaptHeight();
}
// display ws_url form
function askForUrl() {
displayError("can't contact web-services, please give absolute url to 'ws.php'");
if ($("#urlForm input[name='ws_url']").val() == "") {
$("#urlForm input[name='ws_url']").val(ws_url);
}
$("#urlForm").show();
}
// parse Piwigo JSON
function parsePwgJSON(json) {
try {
resp = jQuery.parseJSON(json);
if (resp==null | resp.result==null | resp.stat==null | resp.stat!='ok') {
throw new Error();
}
}
catch(e) {
displayError("unable to parse JSON string");
resp = {"stat": "ko", "result": "null"};
}
return resp.result;
}
// fetch methods list
function getMethodList() {
resetDisplay();
$.ajax({
type: "GET",
url: ws_url,
data: { format: "json", method: "reflection.getMethodList" }
}).done(function(result) {
result = parsePwgJSON(result);
if (result!=null) {
methods = result.methods;
var ml = '';
for (var i=0; i< methods.length ; i + + )
{
ml += '< li > < a href = "#top" > '+ methods[i]+'< / a > < / li > ';
}
$("#methodsList").html(ml).show();
adaptHeight();
// trigger method selection
$("#methodsList li a").click(function() {
selectMethod($(this).html());
});
}
}).error(function(jqXHR, textStatus, errorThrown) {
askForUrl();
});
}
// select method
function selectMethod(methodName) {
$("#introMessage").hide();
$("#tiptip_holder").fadeOut(200);
if (cachedMethods[ methodName ]) {
fillNewMethod(methodName);
}
else {
$.ajax({
type: "GET",
url: ws_url,
data: { format: "json", method: "reflection.getMethodDetails", methodName: methodName }
}).done(function(result) {
result = parsePwgJSON(result);
if (result!=null) {
if (result.options.post_only || result.options.admin_only) {
var onlys = '< div class = "onlys" > ';
if (result.options.post_only) {
onlys+= 'POST only. ';
}
if (result.options.admin_only) {
onlys+= 'Admin only. ';
}
onlys+= '< / div > ';
result.description = onlys + result.description;
}
cachedMethods[ methodName ] = result;
fillNewMethod(methodName);
}
}).error(function(jqXHR, textStatus, errorThrown) {
displayError("unknown error");
});
}
}
// display method details
function fillNewMethod(methodName) {
resetDisplay();
method = cachedMethods[ methodName ];
$("#methodName").html(method.name).show();
if (method.description != "") {
$("#methodDescription blockquote").html(method.description);
$("#methodDescription").show();
}
$("#requestFormat").val(method.options.post_only ? 'post' : 'get');
var methodParams = '';
if (method.params & & method.params.length>0) {
for (var i=0; i< method.params.length ; i + + ) {
var param = method.params[i],
isOptional = param.optional,
acceptArray = param.acceptArray,
defaultValue = param.defaultValue == null ? '' : param.defaultValue,
info = param.info == null ? '' : '< a class = "methodInfo" title = "'+ param.info.replace(/" / g , ' & quot ; ' ) + ' " > i< / a > ',
type = '';
if (param.type.match(/bool/)) type+= '< span class = type > B< / span > ';
if (param.type.match(/int/)) type+= '< span class = type > I< / span > ';
if (param.type.match(/float/)) type+= '< span class = type > F< / span > ';
if (param.type.match(/positive/)) type+= '< span class = subtype > +< / span > ';
if (param.type.match(/notnull/)) type+= '< span class = subtype > ø < / span > ';
// if an array is direclty printed, the delimiter is a comma where we use a pipe
if (typeof defaultValue == 'object') {
defaultValue = defaultValue.join('|');
}
methodParams+= '< tr > '+
'< td > '+ param.name + info +'< / td > '+
'< td class = "mini" > '+ (isOptional ? '?':'*') + (acceptArray ? ' []':'') +'< / td > '+
'< td class = "mini" > '+ type +'< / td > '+
'< td class = "input" > < input type = "text" class = "methodParameterValue" data-id = "'+ i +'" value = "'+ defaultValue +'" > < / td > '+
'< td class = "mini" > < input type = "checkbox" class = "methodParameterSend" data-id = "'+ i +'" ' + ( isOptional ? ' ' : ' checked = "checked" ' ) + ' > < / td > '+
'< / tr > ';
}
}
else {
methodParams = '< tr > < td colspan = "4" > This method takes no parameters< / td > < / tr > ';
}
$("#methodParams tbody").html(methodParams);
$("#methodWrapper").show();
adaptHeight();
// trigger field modification
$("input.methodParameterValue").change(function() {
$("input.methodParameterSend[data-id='"+ $(this).data('id') +"']").attr('checked', 'checked');
});
// tiptip
$(".methodInfo").tipTip({
maxWidth:"300px",
defaultPosition:"right",
delay:0
});
}
// invoke method
function invokeMethod(methodName, newWindow) {
var method = cachedMethods[ methodName ];
var reqUrl = ws_url +"?format="+ $("#responseFormat").val();
// GET
if ($("#requestFormat").val() == 'get') {
reqUrl+= "& method="+ methodName;
for (var i=0; i< method.params.length ; i + + ) {
if (! $("input.methodParameterSend[data-id='"+ i +"']").is(":checked")) {
continue;
}
var paramValue = $("input.methodParameterValue[data-id='"+ i +"']").val();
var paramSplitted = paramValue.split('|');
if (method.params[i].acceptArray & & paramSplitted.length > 1) {
$.each(paramSplitted, function(v) {
reqUrl+= '& '+ method.params[i].name +'[]='+ paramSplitted[v];
});
}
else {
reqUrl+= '& '+ method.params[i].name +'='+ paramValue;
}
}
if (newWindow) {
window.open(reqUrl);
}
else {
$("#invokeFrame").attr('src', reqUrl);
}
2015-07-05 19:03:18 +02:00
$('#requestDisplay').show()
.find('.url').html(reqUrl).end()
.find('.params').hide();
2014-07-06 13:21:10 +02:00
}
// POST
else {
2015-07-05 19:03:18 +02:00
var params = {};
2014-07-06 13:21:10 +02:00
var form = $("#invokeForm");
form.attr('action', reqUrl);
var t = '< input type = "hidden" name = "method" value = "'+ methodName +'" > ';
for (var i=0; i< method.params.length ; i + + ) {
if (! $("input.methodParameterSend[data-id='"+ i +"']").is(":checked")) {
continue;
}
2015-07-05 19:03:18 +02:00
var paramValue = $("input.methodParameterValue[data-id='"+ i +"']").val(),
paramName = method.params[i].name,
paramSplitted = paramValue.split('|');
2014-07-06 13:21:10 +02:00
if (method.params[i].acceptArray & & paramSplitted.length > 1) {
2015-07-05 19:03:18 +02:00
params[paramName] = [];
$.each(paramSplitted, function(i, value) {
params[paramName].push(value);
t+= '< input type = "hidden" name = "'+ paramName +'[]" value = "'+ value +'" > ';
2014-07-06 13:21:10 +02:00
});
}
else {
2015-07-05 19:03:18 +02:00
params[paramName] = paramValue;
t+= '< input type = "hidden" name = "'+ paramName +'" value = "'+ paramValue +'" > ';
2014-07-06 13:21:10 +02:00
}
}
form.html(t);
form.attr('target', newWindow ? "_blank" : "invokeFrame");
form.submit();
2015-07-05 19:03:18 +02:00
$('#requestDisplay').show()
.find('.url').html(reqUrl).end()
.find('.params').show().html(JSON.stringify(params, null, 4));
2014-07-06 13:21:10 +02:00
}
return false;
}
< / script >
< / body >
< / html >
