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://www.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>