GET document source api - Tizra/Tizra-Customer-Tracker GitHub Wiki

(Server) GET information on Tizra Document sources

Access to Source contents (PDF files or attachments)

Files within a source are keyed by their names. The name of a file can include / characters, so that packages of files corresponding to a portion of a web site can be put in place, with their relative URLs continuing to work properly. These slashes do not correspond to directories on the server side, and it is not possible to get any kind of directory listings based on the internal slashes within file names.

The GET operation on the a Source file's management URL will return the content, with content-type, content-disposition, etc. all set as appropriate.

Access to Source metadata

Given the API URL for a resource, the MetaSources in that object can be access by appending the name of that source as a path-component to the object URL. So, for instance, the PdfSource content for an object with a management URL like this: https://secure.agilepdf.com/admin-api/3h5u1u/objects/11ax could be accessed at URLs based on https://secure.agilepdf.com/admin-api/3h5u1u/objects/11ax/PdfSource.

A GET operation on a source management URL like the one described above will return a record describing that source and its contents:

{
	"name": "PdfSource",
	"is-breakable": true,
	"files": [{
		"size": 4544013,
		"name": "AC!.pdf",
		"content-type": "application\/pdf",
		"url": "\/AC\/~~PdfSource\/AC!.pdf",
		"props": {
			"DisplayName": ""
		},
		"number-of-pages": 568,
		"date-uploaded": "2011-11-15 17:56:17.239"
	}]
}

or:

{
    "files": [
        {
            "content-type": "image/png", 
            "date-uploaded": "2012-10-16 12:41:09.565", 
            "name": "images/bkgrd_blue.png", 
            "number-of-pages": 1, 
            "props": {
                "DisplayName": "bkgrd_blue.png", 
                "isDownload": "false", 
                "isVisible": "true"
            }, 
            "size": 15397, 
            "url": "/AC/~~Attachments/images/bkgrd_blue.png"
        }, 
        {
            "content-type": "application/url", 
            "date-uploaded": "2014-03-27 17:25:27.528", 
            "name": "url-value/remote.htm", 
            "number-of-pages": 1, 
            "props": {
                "DisplayName": "This is a URL", 
                "isDownload": "false", 
                "isUrlName": "true", 
                "isVisible": "true", 
                "rel": "lightbox"
            }, 
            "size": 0, 
            "url": "/AC/~~Attachments/url-value/remote.htm"
        }
    ], 
    "is-breakable": false, 
    "name": "Attachments"
}

Sources have the following fields:

  • name contains the name of the file source, e.g. PdfSource, Attachments, etc.
  • is-breakable: If is-breakable is true, publishing the source will paginate the files in the source for delivery in the reader. If is-breakable is false, the resources it contains are attachments.
  • files: an array of records describing the resources in this source.

Files have several fields associated with them:

  • content-type the content type of the resource stored in the file. The content-type is used when delivering the contents, and to determine appropriate processing for the contents of a file. Tizra uses a special content-type application/url when no file is stored, only a reference to a URL for the content.
  • date-uploaded when this file was last updated.
  • name contains the name of the file (or the remote URL, if the file is not stored in Tizra).
  • props contains system properties relating to this file, and how it should be linked from the reader.
  • size the size of the file in bytes.
  • url If this is a file (and not a remote URL), this contains full path of the site URL for accessing this file on the Tizra delivery site.
  • number-of-pages Count of the number of pages in the file (or 1, if the source is not breakable).

The props dictionary holds system and presentation information about a file. The fields include:

  • DisplayName This is a human-oriented description of the file which is used as the link anchor when displaying the file to a user.
  • isVisible if true, the file will be visible in user attachment lists, if false, the file will not be listed or linked in user displays. Affects only visibilty of the file; this setting does not restrict access to the file if the URL is known. Generally used when HTML attachments are providing ancillary content, so that only the starting page appears in the attachment list, while images, javascripts, and other HTML assets are hidden from the list.
  • isDownload is true if the file should be delivered with Content-Disposition: attachment, which will cause browsers to download content rather than dislplay it in the browser.
  • isUrlName This boolean, if true, signals that the name of the file is actually a URL (which could be absolute, or a relative URL), that should be target of any links to the file generated in the reader or other site displays.
  • rel this holds the value that should be used for the rel attribute of an HTML link for this resource. This is used to configure javascript extensions for the display of content in the reader -- information about all links with a given rel value will be delivered to a jquery plugin that can handle display of the resource, allowing options like light-boxes, movie viewers, and the like to be configured.

Attachments are either access-controlled file content associated with the document, or external URLs for delivery in the reader. Attachments have a nominal "page count" of one, for administrative purposes.

Attachments have several properties (values in the props structure) that are managed in the administrative interfaces and which are used in rendering links to the file or controlling HTTP properties of the response when the file is requested (for instance whether Content-Disposition headers are set on on HTTP responses for file content so that browsers will download it rather than attempt to display it inline).

  • DisplayName (if present and not blank) is the name that will be used as the content of a link anchor in the downloads list for a site rather than the filename.
  • isDownload determines whether attachment headers will be added to HTTP results for the delivery of a file, causing browsers to download it rather than to display in in a browser if possible.