Web service API

How to use PageSeeder's Web service API

HTTP codes

Services

Whenever a fatal error occurs during the execution of a service, the following XML will be returned:

<error id="[Error ID]">
  <request>[Service URL]</request>
  <message>[Error Message]</message>
</error>

The HTTP status code will also be set accordingly depending on whether it is a client error (e.g. 400 for missing parameters, 500 for server errors)

Most errors occurring while a service is invoked have a specific identifier and are returned by the underlying generator. These are described in the documentation of each generator.

However, some errors are caught by the service framework as described below.

Core error codes

HTTP status: 400

0x0103 - Bad tunnel

When a service was invoked with the wrong HTTP method.

<error id="0103">
  <request>[Service URL]</request>
  <message>Unable to tunnel request through specified HTTP method</message>
</error>

0x0201 - Missing parameter

When a required parameter was not specified in the URL. The error message should return the list of missing required parameters.

<error id="0201">
  <request>[Service URL]</request>
  <message>Failed @Requires check: missing parameter '[name]'</message>
</error>

0x0202 - Group not found

When the {group} URL variable does not resolve to an existing group.

<error id="0202">
  <request>[Service URL]</request>
  <message>Failed @Requires check: missing Group instance</message>
</error>

0x204 - Member not found

When the {member} URL variable does not resolve to an existing member.

<error id="0204">
  <request>[Service URL]</request>
  <message>Failed @Requires check: missing Member instance</message>
</error>

0x208 - URI not found

When the {uri} URL variable does not resolve to an existing URI.

<error id="0208">
  <request>[Service URL]</request>
  <message>Failed @Requires check: missing URI instance</message>
</error>

0x2xx - Other failed requirement

When multiple requirements failed, the error code is a combination of the missing elements. For example, if a service was invoked on a non-existent member (0x0204) and with a missing parameter (0x0201), the combined code is 0x0205.

<error id="02xx">
  <request>[Service URL]</request>
  <message>Failed @Requires check: [...]</message>
</error>

HTTP status: 401

0x0101 - Failed permission check if the user is not logged in

<error id="0101">
  <request>[Service URL]</request>
  <message>Unauthorized access</message>
</error>

 HTTP status: 403

0x0101 - Failed permission check if the user is already logged in

When the user invoking the service does not have the required permission.

<error id="0101">
  <request>[Service URL]</request>
  <message>Access forbidden</message>
</error>

HTTP status: 404

0x0102 - Service Not Found

When there is no service corresponding to the specified URL

<error id="0102">
  <request>[Service URL]</request>
  <message>Unable to find requested service</message>
</error>

HTTP status: 406

0x0104 - Bad content type

When the content type requested cannot be provided with this service.

<error id="0104">
  <request>[Service URL]</request>
  <message>Unable to provide acceptable content type</message>
</error>

HTTP status: 500

0x0800 - Exception caught

When the underlying generator threw an exception.

<error id="0800">
  <request>[Service URL]</request>
  <message>Runtime exception thrown by generator</message>
</error>

0x0801 - Generator Exception

When the underlying generator threw a specific exception.

<error id="0801">
  <request>[Service URL]</request>
  <message>Exception thrown by generator on purpose</message>
</error>

HTTP status: 502

0x0802 - Database error

When the underlying generator threw a database error.

<error id="0802">
  <request>[Service URL]</request>
  <message>Database exception thrown by generator</message>
</error>

HTTP status: 503

0x0600 - Generator not found

When the generator bound to the service could not be found in the classpath. This generally indicates a configuration or deployment error: the PageSeeder services configuration references a generator which cannot be found.

<error id="0600">
  <request>[Service URL]</request>
  <message>Unable to find generator class</message>
</error>

0x0601 - Generator instantiation error

When the underlying generator could not be instantiated because an error occurred.

<error id="0601">
  <request>[Service URL]</request>
  <message>Unable to instantiate the generator</message>
</error>

0x0602 - Generator initialization error

When the underlying generator could not be initialized because an error occurred while invoking the init() method.

<error id="0602">
  <request>[Service URL]</request>
  <message>Unable to initialize the generator, init() method failed</message>
</error>

Created on , last edited on