Web service API

How to use PageSeeder's Web service API

Parameters

Most servlets and services accept or require parameters. For some parameters, specific constraints apply to their values.

The datatypes below provide an indication of what PageSeeder expect and what is likely to cause an error.

Note

The name of the datatype is not case sensitive. For example, string and String refer to the same type.

The 'v' parameter

The v parameter can be used on any service URL to call a specific version of the web services API. The value of this parameter is the corresponding PageSeeder version with an optional ;strict afterwards (e.g. v=5.9200;strict ).

Each service can have @since@deprecated and @obsolete PageSeeder version numbers associated with it. The ;strict suffix or the global PageSeeder property serviceStrict=true can be used to set strict mode.

The rules applied are as follows:

  • if requested service has @obsolete, return 410 "Gone" error AND set header:
 Warning: 299 - "Obsolete API [(strict)]" "[@obsolete]"
  • if requested service has @deprecated, set header:
Warning: 299 - "Deprecated API [(strict)]" "[@deprecated]"
  • if v is before @since on requested service, set header:
Warning: 299 - "Since API [(strict)]" "[@obsolete]"
  • if v is after or equal to @deprecated on requested service AND strict mode, return 410 "Gone" error
  • if v is before @since on requested service AND strict mode, return 404 "Not found" error

When there is no v parameter on the request, v is the current PS version.

Basic types

string (default)

A single string of characters.

This is the default type. If no data type is specified in the documentation, developers should assume that the parameter can accept any string value.

Unless specified otherwise, a string value has no maximum length and can contain any Unicode characters.

Additional constraints may apply, check the description for the parameter. 

long

A long value is a (64-bit signed two's complement) integer value. 

If it is the type used for an ID, such as a Member ID or Group ID, it must be strictly positive.

boolean

The value can be either "true" or "false". Unless specified otherwise, the value is case sensitive.

date

All dates should use the '-' delimited ISO 8601 calendar date format (YYYY-MM-DD). The timezone information is not required. Unless specified otherwise, the time zone of the server is used by default

For example: 2012-12-31

datetime

All dates should use the '-' delimited ISO 8601 calendar datetime format (YYYY-MM-DD'T'hh:mm:ssZ). The timezone information may be provided. Unless specified otherwise, the time zone of the server is used by default.

For example: 2012-11-23T22:35:12+10:00

enum

A value in a list of enumerated list of values.

Generally, the parameter description should provide the list of possible values.

email

A valid email address. See RFC 5322 - Internet Message Format .

url

A valid URL. See RFC 3986 - Uniform Resource Identifier .

mediatype

A valid media type (without any encoding information). It should generally be one of the media types defined in the MIME Properties.

Common types

The types below correspond to other commonly used types for parameters introduced to clarify and simplify the documentation. In some cases, the documentation may still refer to a basic type instead.

label

A valid label name, it can contain the following characters [a-z][A-Z][0-1][-_] but cannot start with a '-'.

path

A valid path using '/' as a file separator.

status

A parameter of type status, should be one of the status values defined in the Group Properties. There are multiple properties defining status values.

The default status values are 'Open', 'Resolved', 'Closed'.

priority

A parameter of type priority, should be one of the priority values defined in the Group Properties.

The default priority values are 'High', 'Medium', 'Low'.

scheme

A scheme as specified by RFC 3986 - 3.1 Scheme . Although PageSeeder does not enforce the use of any particular scheme , in practice there is no reason to use any scheme other than "http" or "https". The default scheme is defined in the Template Properties.

host

A host as specified by RFC 3986 - 3.2.2 Host . In most cases, a parameter of type host refers to a host in PageSeeder or one of its aliases. The default host is defined in the Template Properties.

port

A parameter of type port, should be a positive integer between 1 and 65535. See RFC 3986 - 3.2.3 Port . The default port is defined in the Template Properties.

yes|no

A parameter which value can only be 'Yes' or 'No'. This datatype is only used by Servlets.

Other conventions

When the plural is used, it usually indicates a comma separated list of values.

Created on , last edited on