Skip to main content

 API

PageSeeder Web services API documentation

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 expects and what is likely to cause an error.

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.

Always reference the parameter description for additional constraints.

integer

An integer value from -2,147,483,648 to 2,147,483, 647.

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 default timezone value is that of the server.

For example: 2018-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 default timezone value is that of the server.

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

enum

A value in a list of enumerated values. Generally, the list of possible values will be in the parameter description.

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) from the list of 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 global properties.

label

A valid label name, it can only contain the following characters [a-z][A-Z][0-9][-_] .

labels

A comma separated list of label names, it can only contain the following characters [a-z][A-Z][0-9][-_,] .

notification

Defines how a member receives an event notification for a particular group:

  • none – only notify of special group announcements (aka Announcements only).
  • essential – only notify relevant task assignments and replies to posts.
  • immediate – notify immediately for all new comments and tasks (aka Normal).
  • daily – Essential setting plus a digest daily of new comments and tasks.
  • weekly – Essential setting plus a weekly digest of new comments and tasks.

For more information, see Notification.

notify

Defines which members will receive a notification of the comment, task, workflow, document or URL update:

  • normal – notify according to the notification settings of each member.
  • announce – notify regardless of the member notification settings.
  • minimal – notify only the discussion authors, assigned member and depending on status, the group approvers. Discussion authors are not included for workflows.
  • silent – no notification.

If comment contentype is not text/plain, then  notify will automatically default to silent.

When a member with a role of Reviewer or below adds a comment/task, notify is forced to normal. This can be overridden if the member is 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 global properties.

priority

A parameter of type priority, should be one of the priority values defined in the Group Properties. It can only contain the following characters [a-z][A-Z][0-9][, -_] .

The default priority values are High, Medium, Low.

The system will tolerate values other than the ones defined in the group properties; and will not throw an error if different values are used. However, best practice recommends using parameter values that match the group properties.

publicationid

A valid publication ID contains only the following characters [a-z][A-Z][0-9][-_] and can be up to 250 characters long.

publicationtype

A valid value for a publication type contains only the following characters [a-z][A-Z][0-9][-] and can be up to 250 characters long.

scheme

A scheme as specified by RFC 3986 - 3.1 Scheme . PageSeeder does not enforce the use of a particular scheme, but there is no reason to use a scheme other than http or https. The default scheme is defined in the global properties.

status

A parameter of type status should be one of the status values defined in the Group Properties. Multiple properties define status values based on either task status or document status. It can only contain the following characters [a-z][A-Z][0-9][, -_] .

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

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, best practice recommends using parameter values that match the group properties.

Paging

Most services that return collections of objects provide a paging mechanism using the page and pagesize parameters.

Unless specified otherwise, if the value of  page or pagesize is not a positive integer, the system will ignore it and fall back to the default value.

pagesize

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

Unless specified otherwise the maximum possible value for the pagesize is 10000.

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.

The default value for page is 1, a request for a page number that greater than the available pages will return an empty collection.

Other conventions

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

The ‘v’ parameter

The v parameter on any service URL will 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 will invoke 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

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

Created on , last edited on