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.

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.

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.

label

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

notification

Defines how a member will be notified of events in a particular group:

  • none  Receive only special group announcements (aka Announcements only);
  • essential Receive only relevant task assignments and replies to posts;
  • immediate Receive all normal new comments and tasks immediately (aka Normal);
  • daily Essential plus a new comment and task digest daily;
  • weekly Essential plus a new comment and task digest weekly.

For more information see Notification.

notify

Defines who will get notified of the comment, task, workflow, edit note, document or URL update:

  • normal  notify based on each member's notification settings;
  • announce  will ignore members' individual notifications settings;
  • minimal  will only notify the discussion authors, assigned member and depending on status the group approvers (discussion authors are not included for workflows);
  • silent  no notification.

Note

If comment contentype is not text/plain notify will automatically default to silent. If a reviewer or below adds a comment/task notify will be forced to normal but this can be overridden if authenticated as an administrator.

For more information see Notification.

path

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

port

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

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'.

Note

The system will tolerate values other than the ones defined in the group properties; and will not thrown an error if different values are used. However, it is better practice to always use parameter values that match the group properties.

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.

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 depending on whether it is a task status or a document status.

  • For tasks, the default status values are 'Open', 'Resolved', 'Closed'.
  • For workflows, they are 'Initiated', 'In progress', 'Complete', 'Suspended', 'Terminated'

Note

The system will tolerate values other than the ones defined in the group properties; and will not thrown an error if different values are used. However, it is better practice to always use parameter values that match the group properties.

yes|no

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

Paging

Services that return collections of objects generally provide a paging mechanism using the page and pagesize parameters. Unless specified otherwise, if the parameter value for the page or page size is a not positive integer, it is ignored and the service falls back on the default value.

pagesize

This parameter defines the maximum number of objects to return for each page. Services should specify which elements are counted.

If the parameter value for the page size is not a positive integer, it is ignored and fallback on the default for that service.

page

The page returns the collection of objects that correspond to that page after the entire collection has been divided up based on the pagesize parameter. Many services implement the paging efficiently so that the entire collection needn't be loaded.

If the parameter value for the page is a not positive integer, it is ignored and defaults to 1. If the requested page number is greater than the number of pages, an empty collection is returned.

Other conventions

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

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.

Created on , last edited on