default

Description

This service accepts GET, HEAD or OPTIONS requests for a file (document) stored on PageSeeder, checks access permission and fetches the file.

If publication=true and publicationid is not specified then the publications for this document (that the current member can access) are ordered alphabetically by display title (then by ID) and the first publication is used.

URL

There are three ways to invoke this service depending on document identifier:

The extension {ext} is optional and only used for clients who might need to infer the media type from the file extension. PageSeeder always returns the media type in the response headers.

HTTP caching

The HTTP cache headers returned depend on the publication (if any) and whether there is any content transcluded from other documents as follows:

Comparisons

You can also use this service to return the result of a comparison between:

• two versions of a document (with version and compare parameters)
• two document events occurring on a document (with versionid and compareid parameters)
• a document and another document

You can compare PSML documents.

If the value is a float or ISO 8601 date (i.e. yyyy-mm-dd) and none match, the closest previous version is loaded.

The table below summarizes the parameter used to select the state of the document to compare.

Parameters

behavior

This parameter affects the value of the Content-Disposition  HTTP response header which indicates if the content is expected to be displayed inline in the browser or as an attachment that is downloaded and saved locally. The filename directive is always included.

If this parameter is set to download, the Content-Disposition set to attachment to trigger a download. For example:

Content-Disposition=attachment; filename="sample.psml"

Otherwise, the response includes the Content-Disposition set to inline. For example:

Content-Disposition=inline; filename="sample.psml"

compare

This parameter specifies which version to compare with the selected version. It is the equivalent of the version parameter for the comparison document.

compareid

The ID of a document history event to compare the selected document with, it is the equivalent of the versionid parameter for the comparison document.

When specified, this parameter overrides the compare parameter.

compareuriid

This parameter lets you specify a URI ID to compare the document with another document (requires compare or compareid).

compare-diffx

This parameter selects the type of markup returned by the comparison algorithm. If no compareid or compare parameter is specified in the request, it compares with current version.

When set to none, only the markup of the selected document is returned as if no comparison occurred but it still includes <compareto> and <compare> elements.

Combined

When set to combined, the comparison markup includes both insertions (<ins>) and deletions (<del>) in the same document, which lets the user see the changes as a single view.

In the combined view, the <diff> element contains all the changes, as in the following example:

<document id="198523" schemaversion="1.4" date="2022-10-19T13:55:53+11:00" 
          version="0.2" level="portable">
  <documentinfo> ... </documentinfo>
  <fragmentinfo>
    <locator id="275249" fragment="1" editid="676296" modified="2022-10-19T13:55:47+11:00">
      <compare>
        <content>
          <fragment id="1">
            <heading level="1">Simple document</heading>
          </fragment>
        </content>
        <diff>
          <fragment xmlns:diff="https://www.pageseeder.org/diffx" id="1">
            <heading level="1">
              <diff:del>Simple</diff:del>
              <diff:ins>Sample</diff:ins>
              document
            </heading>
          </fragment>
        </diff>
      </compare>
    </locator>
  </fragmentinfo>
  <section id="title">
    <fragment id="1">
      <heading level="1">Sample document</heading>
    </fragment>
  </section>
  <section id="content"> ... </section>
</document>

Split

When set to split, the comparison markup returns the selected document with insertions (<ins>) and the compared document with deletions (<del>). The split view lets use compare document side-by-side and which each side showing the version of the document they correspond to.

In the split view, the <diff> element only shows deletions, and insertions are shown inline in the regular content.

<document id="198523" schemaversion="1.4" date="2022-10-19T13:55:53+11:00" 
          version="0.2" level="portable">
  <documentinfo> ... </documentinfo>
  <fragmentinfo>
    <locator id="275249" fragment="1" editid="676296" 
             modified="2022-10-19T13:55:47+11:00">
      <compare>
        <content>
          <fragment id="1">
            <heading level="1">Simple document</heading>
          </fragment>
        </content>
        <diff>
          <fragment xmlns:diff="https://www.pageseeder.org/diffx" id="1">
            <heading level="1">
              <diff:del>Simple</diff:del>
              document
            </heading>
          </fragment>
        </diff>
      </compare>
    </locator>
  </fragmentinfo>
  <metadata>
    <properties/>
  </metadata>
  <section id="title">
    <fragment xmlns:diff="https://www.pageseeder.org/diffx" id="1">
      <heading level="1">
        <diff:ins>Sample</diff:ins>
        document
      </heading>
    </fragment>
  </section>
  <section id="content"> ... </section>
</document>

compare-position

This parameter lets you specify the position of the compare document in the publication. This is useful in case a document is referenced multiple times within a single publication as it affects the numbering.

The position parameter requires both publication=true and compareuriid and is ignored otherwise. If it is not specified, this services assumes that the first instance of the document in the publication.

compare-publicationid

The ID of the publication for the compare document. This parameter lets you compare the selected document with another document from a different publication.

It requires publication=true and compareuriid.

fragment

The fragment ID of the PSML to return. If specified only the corresponding <document-fragment> element is returned and it can be used to compare the same fragment in different documents.

It only applies to PSML documents or when the psml=true parameter is specified. Requires PageSeeder v6.0008 or higher.

group

The group for the document edits. For backward compatibility, pre v6 different groups could have different edits)

If you specify a group, PageSeeder also checks that you have permission to use that group.

position

This parameter lets you specify the position of this document in the publication. This is useful in case a document is referenced multiple times within a single publication as it affects the numbering.

The position parameter requires publication=true as it has no effect outside the context of a publication. If it is not specified, this services assumes that the first instance of the document in the publication.

publication

A Boolean parameter to indicate whether to use the publication version or document version.

When set to true, the service returns the publication version and adjusts the numbering for the publication. It also computes the last modified date based on the Table of Contents (TOC) of the publication which affects the caching response.

When set to false, the service returns the document version and adjusts the numbering as if the document was standalone. The last modified date is the URI’s last modified date.

publicationid

The ID of the publication context for version and numbering. This parameter is ignored unless publication=true.

If this parameter is empty, the service returns the document version instead and does not compute the numbering.

ps-reload

Use ps-reload=true to force PageSeeder to refresh the PSML document cache for this document only. This parameter has no effect on non-PSML documents, unless psml=true is also specified.

psml

This Boolean parameter indicates whether this service returns the raw content or the corresponding PSML metadata document.

This parameter has no effect for PSML documents.

For example, when requesting and image with /ps/uri/123.png, this service returns the image file.

When setting the psml to true, the service returns the following instead:

<document id="123" schemaversion="1.3" 
          date="2022-08-04T09:18:52+10:00" version="current"
          level="metadata">
  <documentinfo>
    <uri id="123" external="false" mediatype="image/png" size="58665"
         modified="2022-08-04T09:18:52+10:00"
         scheme="http" host="ps.example.org" port="80"
         path="/ps/sample/demo/overview.png"
         decodedpath="/ps/sample/demo/overview.png">
      <displaytitle>overview.png</displaytitle>
    </uri>
  </documentinfo>
  <fragmentinfo/>
  <metadata/>
</document>

transclude

This Boolean parameter indicates whether the content for xrefs of type transclude should be included inline with the content.

If set to false the xref in the returned PSML contains the display text or is empty, for example:

<blockxref id="123" frag="2"
           display="document" type="transclude" uriid="456"
           href="/ps/sample/demo/info.psml" urititle="Info"
           mediatype="application/vnd.pageseeder.psml+xml">Info
</blockxref>

If set to true, PageSeeder pulls the transcluded content and injects it inside the xref in the returned PSML, as in the following example:

<blockxref id="123" frag="2" 
           display="document" type="transclude" uriid="456"
           href="/ps/sample/demo/info" urititle="Info"
           mediatype="application/vnd.pageseeder.psml+xml">
  <locator id="7" fragment="2" editid="8" modified="2022-10-14T15:04:51+11:00"/>
  <fragment id="2">
    <para>This content has been transcluded</para>
  </fragment>
</blockxref>

The transclude parameter has no effect if the returned content is not PSML or during comparisons as it only applies if no compare* parameters.

version

The version parameter selects the version of the PSML document or PSML metadata document to return.

The value of the compare parameter can be:

• original – a special keyword referring to the original state of the document when it was created or uploaded
• current – a special keyword referring to the current state of the document
• The name of an existing document version

When the specified version does not exist:

• If the value is an ISO 8601 date (i.e. yyyy-mm-dd), the closest previous date is loaded.
  Example: if versions 2020-10-11 an 2022-01-03 exist and the parameter is 2022-01-01 , the version selected for comparison is 2020-10-11.
• If the value is a floating number, each part if evaluated separately to match the closest lower integer version is loaded
  Example 1: if versions 0.5 an 0.8 exist and the parameter is 0.7 , the version selected for comparison is 0.5.
  Example 2: if versions 1.1 an 1.2 exist and the parameter is 1.11 , the version selected for comparison is 1.2.
  Example 3: if versions 1.10 an 1.20 exist and the parameter is 1.11 , the version selected for comparison is 1.10.
• Otherwise, the original version is returned.

versionid

This parameter if the lets you retrieve the state of the document at the time of a specific document history event, including:

• Version – for version name or number, use the compare parameter instead
• Workflow events, for example when the document changes status or is assigned
• Individual edits
• Notes added to edits
• Comment mades to a fragment or the document

If the specified version id is 0, the original version is returned.

When specified, this parameter overrides the version  parameter.

Permission

You must have permission to view the document in order to invoke this service.

If you specify a group parameter, you must also have permission got access this group.

Response

The response depends mainly on:

• The media type of the document
• Whether the psml parameter is used

The parameters used for comparison and for publications affect the PSML being returned only.

If the content includes transclusion, the permissions of the user might affect their content.

PSML document example

When requesting a PSML document, for example /ps/uri/1234.psml, this service always returns the source PSML.

<document id="1234" schemaversion="1.4" 
          date="2022-10-19T10:57:11+11:00" version="current" level="portable">
  <documentinfo>
    <uri id="1234" external="false" mediatype="application/vnd.pageseeder.psml+xml"
         created="2022-10-19T10:57:11+11:00" 
         modified="2022-10-19T10:57:11+11:00" 
         scheme="http" host="ps.example.org" port="80"
         path="/ps/sample/documentation/simple_document.psml"
         decodedpath="/ps/sample/documentation/simple_document.psml"
         title="Simple document">
      <displaytitle>Simple document</displaytitle>
    </uri>
  </documentinfo>
  <fragmentinfo/>
  <metadata/>
  <section id="title">
    <fragment id="1">
      <heading level="1">Simple document</heading>
    </fragment>
  </section>
  <section id="content">
    <fragment id="2">
      <para/>
    </fragment>
  </section>
</document>

Image example

When using this service to retrieve non-PSML, it returns the actual content of the file with the  HTTP header to its native media type, for example:

If psml=true, this service returns the PSML metadata:

<document id="123" schemaversion="1.3" 
          date="2022-08-04T09:18:52+10:00" version="current"
          level="metadata">
  <documentinfo>
    <uri id="123" external="false" mediatype="image/png" size="58665"
         modified="2022-08-04T09:18:52+10:00"
         scheme="http" host="ps.example.org" port="80"
         path="/ps/sample/demo/overview.png"
         decodedpath="/ps/sample/demo/overview.png">
      <displaytitle>overview.png</displaytitle>
    </uri>
  </documentinfo>
  <fragmentinfo/>
  <metadata/>
</document>

URL example

When using this service to retrieve URLs, it returns the URL as an internet shortcut with the Content-Type HTTP header set to text/url, for example:

[InternetShortcut]
https://dev.pageseeder.com/psml.html

If psml=true, this service returns the PSML metadata:

<document id="209392" schemaversion="1.4" 
          date="2022-10-19T11:23:25+11:00" version="current" level="metadata">
  <documentinfo>
    <uri id="209392" external="true" mediatype="text/html" 
         created="2021-01-31T23:04:08+11:00"
         modified="2022-10-19T11:23:25+11:00" 
         scheme="https" host="dev.pageseeder.com" port="443"
         path="/psml.html" decodedpath="/psml.html" title="PSML">
      <displaytitle>PSML</displaytitle>
      <description>A complete reference of PageSeeder's markup language PSML</description>
    </uri>
  </documentinfo>
  <fragmentinfo/>
  <metadata/>
</document>

Folder example

When using this service to retrieve folder, it returns a 204 (no content) response.

If psml=true, this service returns the PSML metadata:

<document id="202882" schemaversion="1.4" 
          date="2023-06-28T16:26:24+10:00" version="current" level="metadata">
  <documentinfo>
    <uri id="202882" external="false" mediatype="folder" 
         created="2023-06-28T16:26:24+10:00" 
         modified="2023-06-28T16:26:24+10:00" 
         scheme="http" host="ps.example.org" port="80"
         path="/ps/sample/demo"
         decodedpath="/ps/sample/demo">
      <displaytitle>Demo</displaytitle>
    </uri>
  </documentinfo>
  <fragmentinfo/>
</document>

Error handling