Skip to main content

 Services

Web services from /about to /webhooks

default

/uri/{uri} [GET]

Description

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

 This service does not use the /api prefix.

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:

IdentifierURL patternExample
URI ID/ps/uri/{uriid}{ext?}/ps/uri/123 or /ps/uri/123.gif
DocID/ps/docid/{docid}/ps/docid/myid123
Path/ps/uri?path={path}/ps/uri?path=/ps/sample/demo/doc.psml

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:

no publicationpublication root accessible to ps-grouppublication root NOT accessible to ps-group
transcluded content

Cache-Control: no-cache

Cache-Control: no-cache

Cache-Control: no-cache

NO transcluded content

Cache-Control: must-revalidate

ETag: [document etag]

Last-Modified: [document modified date]

Cache-Control: must-revalidate

ETag: [publication etag]

Last-Modified: [publication modified date]

Cache-Control: private, must-revalidate

ETag: [publication etag]

Last-Modified: [publication modified date]

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.

You can also compare the metadata of non-PSML documents if you set the psml parameter to true , otherwise the comparison parameters are ignored.

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.

Main documentCompare documentDescription
versioncompareDocument version, or current or original 
versionidcompareidDocument event ID
positioncompare-positionPosition within publication
publicationidcompare-publicationidPublication ID

You can compare a version of a document with its state by event ID (i.e. you can use version with compareid or versionid with compare.

Parameters

NameDescriptionRequiredTypeDefault value
behaviorIf set to download, add filename attachment headers to trigger download by browsernostring
compareuriidThe URI ID of the document to compare with.nolong[uriid]
compareidThe version ID to compare the selected version with (overrides compare) As of PageSeeder v5.99 it can be any event ID.nolong
compareThe version to compare the selected version with (applies to auto-numbering). If original or current, compare with original or current version. If the value is a float or ISO 8601 date and none match, the closest previous version is loaded.nostring
compare-diffxThe diffx markup to include for comparison, can be none, combined, split  (true=combined and if no compareid or compare, compare with current version)noenumnone
compare-positionThe position (instance number) of the compare document in the publication (requires publication=true and compareuriid )nointeger[first embedded position of URI]
compare-publicationidThe ID of the publication for compare document numbering (requires publication=true and compareuriid)nopublicationid[first publication found for URI]
fragment
The fragment ID of the PSML to returnnofragmentid
groupThe group for the document edits (for backward compatibility, pre v6 different groups could have different edits)nostring[the first user’s group with access]
ps-reloadWhether to refresh the document XML cache contents (requires psml=true for non-PSML documents)nobooleanfalse
psmlWhether to return PSML metadata for non-PSML filesnobooleanfalse
positionThe position (instance number) of this document in the publication (requires publication=true)nointeger[first embedded position of URI]
publicationWhether to use publication for version and adjustments (e.g. numbering) in contentnobooleanfalse
publicationidThe ID of the publication context for version and numbering, empty means standalone (requires publication=true)nopublicationid[first publication found for URI]
transcludeWhether to transclude content for transclude xrefs (only applies if no compare* parameters)nobooleanfalse
versionidThe version ID of the document/metadata to return (overrides version). As of PageSeeder v5.99 it can be any event ID.nolong
versionThe version of the document/metadata to return (applies to transclusions and auto-numbering). If ‘original’ or ‘current’, load original or current version. If the value is a float or ISO 8601 date and none match, the closest previous version is loaded.nostringcurrent

For backward compatibility parameter names can be prefixed by “ps-” and “docPath” can be used for "path".

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.

Before PageSeeder v5.99, this parameter could only be used for versions.

compareuriid

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

This is mostly useful when comparing document variations.

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.

For backward-compatibility, this service also support true instead of combined.

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>

The combined view is more compact and very effective when there are simple text changes, however, since it generates a document mixing both inserted and deleted content, it is more difficult to read and understand the changes when there are many complex changes.

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.

The transcluded content is only returned if the user has permission to access that content. This is only significant when the source document and target document are in different groups.

version

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

When comparing versions, the auto-numbering is applied and compared.

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.

Before PageSeeder v5.99, this parameter could only be used for versions.

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.

This service only considers permissions to the document for access control. If the document includes transclusions from groups that the users does not have permission to view, the transcluded content is not returned.

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.

HTTP HeaderValue
Content-Typeapplication/vnd.pageseeder.psml+xml 
Content-disposition inline; filename=simple_document.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:

HTTP HeaderValue
Content-Typeimage/png
Content-disposition inline; filename=overview.png

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

HTTP HeaderValue
Content-Typeapplication/vnd.pageseeder.psml+xml 
Content-disposition inline; filename=overview.png.psml
<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 to text/url, for example:

HTTP HeaderValue
Content-Typetext/url
Content-disposition inline; filename=psml.html.url
[InternetShortcut]
https://dev.pageseeder.com/psml.html

PageSeeder’s response might change in the future when downloading a raw URL file, if your API needs to download URLs, use the PSML version with psml=true.

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

HTTP HeaderValue
Content-Typeapplication/vnd.pageseeder.psml+xml 
Content-disposition inline; filename=psml.html.psml
<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:

HTTP HeaderValue
Content-Typeapplication/vnd.pageseeder.psml+xml 
Content-disposition inline; filename=demo.psml
<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

StatusDescription
HTTP CodeError condition
400Parameter versionid or compareid is not a valid number (long)
404No document matching URI ID, DocID or Path
404The compare URI ID could not be found
Created on , last edited on