Output formats

The ipernity API supports JSON, XML, SOAP, XML-RPC and PHP response formats.

Choose your response format

The format of response you choose is directly included in the URL used to call an API method.

http://api.ipernity.com/api/[method]/[format]

The format could be one of the following: json, xml, php.

General

An API response, regardless of output format, returns the following information:

• status : ok or error – in fact anything but "ok" is an error.
• code : the error code in case of failure.
• message : the error message.

JSON

JSON is the response format recommended by ipernity. With JSON, the API returns an object:

Success response

{"api" : {"status" : "ok"},
 "doc" : {"doc_id" : 1234567,
 "title" : "Nice car",
 ...
 }
}

Another example

{"api" : {"status" : "ok"},
 "docs" : {"page" : 1,
 "pages" : 8,
 "perpage" : 100,
 "total" : 800,
 "doc" : [{"doc_id" : 1234567, ... },
 {"doc_id" : 1234568, ... },
 ...
 ]
 }
}

Failed response

{"api" : {"status" : "error",
 "code" : 1,
 "message" : "Document not found"}
}

XML

Success response

<api status="ok">
 <doc doc_id="1234567" ... ></doc>
</api>

Another example

<api status="ok">
 <docs page="1" pages="8" perpage="100" total="800">
 <doc doc_id="1234567" ... ></doc>
 <doc doc_id="1234568" ... ></doc>
 ...
 </docs>
</api>

Failed response

<api status="error" code="1" message="Document not found">
</api>

SOAP

A response in SOAP format uses an XML envelope in a specific format.

Success response

<?xml version="1.0" encoding="utf-8" ?>
<s:Envelope
 xmlns:s="http://www.w3.org/2003/05/soap-envelope"
 xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/1999/XMLSchema">
 <s:Body>
 <x:ipernityResponse xmlns:x="urn:ipernity">
 [escaped-xml]
 </x:ipernityResponse>
 </s:Body>
</s:Envelope>

Failed response

<?xml version="1.0" encoding="utf-8" ?>
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope">
 <s:Body>
 <s:Fault>
 <faultcode>ipernity.error.[error-code]</faultcode>
 <faultstring>[error-message]</faultstring>
 <faultactor>http://api.ipernity.com.com/api/soap/</faultactor>
 <details>
 See http://www.ipernity.com/help/api for more details
 </details>
 </s:Fault>
 </s:Body>
</s:Envelope>

SOAP-XML

A response in SOAP format uses an XML envelope in a specific format but with unescaped XML response. To get this response format, specify the soapxml output format.

Success response

<?xml version="1.0" encoding="utf-8" ?>
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope">
 <s:Body>
 <ipernityResponse xmlns="http://www.ipernity.com/todo#">
 [xml]
 </ipernityResponse>
 </s:Body>
</s:Envelope>

XML-RPC

A response in XML-RPC uses an XML envelope in a specific format.

Success response

<?xml version="1.0" encoding="utf-8" ?>
<methodResponse>
 <params>
 <param>
 <value>
 <string>[escaped-xml]</string>
 </value>
 </param>
 </params>
</methodResponse>

Failed response

<?xml version="1.0" encoding="utf-8" ?>
<methodResponse>
 <fault>
 <value>
 <struct>
 <member>
 <name>faultCode</name>
 <value><int>[error-code]</int></value>
 </member>
 <member>
 <name>faultString</name>
 <value><string>[error-message]</string></value>
 </member>
 </struct>
 </value>
 </fault>
</methodResponse>