Excerpt
Giles provides REST endpoints to specific functionality such as uploading or retrieving images. The following sections describe all so far available endpoints, their parameters, and what they return.

Table of Contents

Authentication

For all REST endpoints, a user has to send a valid API token (see for a description how to get a token) to authenticate. Some endpoints can be used without a token when requesting public files. Below descriptions indicate when an endpoint can be used without a token. In general, there are two ways to send a token: as request parameter or as Authorization header (this is the recommended way).

...

Code Block
accessToken=your-api-token

Add files to Giles

Status

colour	Red
title	POST

In theory, you can add any file type you want to Giles. However, only file types supported by Digilib or file types that Giles knows how to convert really make sense. Currently, Giles knows how to convert PDFs to images. Giles is globally configurable in regards to what image type it uses and what DPI when converting PDFs to images (default is tiff/600 dpi). Giles will create one image per PDF page and put all images together into one folder so that you can use Digilib's paginator feature. The original PDF is stored separately outside of Digilib's image folder.

...

Code Block

POST /giles/rest/files/upload HTTP/1.1
Host: giles-host
Authorization: token your-giles-token
Cache-Control: no-cache
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="files"; filename="test.png"
Content-Type: image/png

[content of file]

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="files"; filename="test.pdf"
Content-Type: application/pdf

[content of file]

Giles Single Application v0.6 and newer/Giles Ecosystem

Giles will respond with an progress id and a url to check the progress of the upload:

...

Once uploading has finished, you will retrieve the complete information as listed below.

Giles Ecosystem

Code Block

language	js
title	Upload Image Sample Response from Giles

[ {
  "documentId" : "DOC123edf",
  "uploadId" : "UPxx456",
  "uploadedDate" : "2016-09-20T14:03:00.152Z",
  "access" : "PRIVATE",
  "uploadedFile" : {
    "filename" : "uploadedFile.pdf",
    "id" : "FILE466tgh",
    "url" : "http://your-giles-host.net/giles/rest/files/FILE466tgh/content",
    "path" : "username/UPxx456/DOC123edf/uploadedFile.pdf",
    "content-type" : "application/pdf",
    "size" : 3852180
  },
  "extractedText" : {
    "filename" : "uploadedFile.pdf.txt",
    "id" : "FILE123cvb",
    "url" : "http://your-giles-host.net/giles/rest/files/FILE123cvb/content",
    "path" : "username/UPxx456/DOC123edf/uploadedFile.pdf.txt",
    "content-type" : "text/plain",
    "size" : 39773
  },
  "pages" : [ {
    "nr" : 0,
    "image" : {
      "filename" : "uploadedFile.pdf.0.tiff",
      "id" : "FILEYUI678",
      "url" : "http://your-giles-host.net/giles/rest/digilib?fn=username%FILEYUI678%2FDOC123edf0%2FuploadedFile.pdf.0.tiff",
      "path" : "username/UPxx456/DOC123edf/uploadedFile.pdf.0.tiff",
      "content-type" : "image/tiff",
      "size" : 2032405
    },
    "text" : {
      "filename" : "uploadedFile.pdf.0.txt",
      "id" : "FILE789UIO",
      "url" : "http://your-giles-host.net/giles/rest/files/FILE789UIO/content",
      "path" : "username/UPxx456/DOC123edf/uploadedFile.pdf.0.txt",
      "content-type" : "text/plain",
      "size" : 4658
    },
    "ocr" : {
      "filename" : "uploadedFile.pdf.0.tiff.txt",
      "id" : "FILE789U12",
      "url" : "http://your-giles-host.net/giles/rest/files/FILE789U12/content",
      "path" : "username/UPxx456/DOC123edf/uploadedFile.pdf.0.tiff.txt",
      "content-type" : "text/plain",
      "size" : 4658
    }
  }, {
    "nr" : 1,
    "image" : {
      "filename" : "uploadedFile.pdf.1.tiff",
      "id" : "FILE045tyhG",
      "url" : "http://your-giles-host.net/giles/rest/digilib?fn=username%2FFILE045tyhG%2FDOC123edf0%2FuploadedFile.pdf.1.tiff",
      "path" : "username/UPxx456/DOC123edf/uploadedFile.1.tiff",
      "content-type" : "image/tiff",
      "size" : 2512354
    },
    "text" : {
      "filename" : "uploadedFile.pdf.1.txt",
      "id" : "FILEMDSPfeVm",
      "url" : "http://your-giles-host.net/giles/rest/files/FILEMDSPfeVm/content",
      "path" : "username/UPxx456/DOC123edf/uploadedFile.pdf.1.txt",
      "content-type" : "text/plain",
      "size" : 5799
    },
    "ocr" : {
      "filename" : "uploadedFile.pdf.1.tiff.txt",
      "id" : "FILEMDSPfe12",
      "url" : "http://your-giles-host.net/giles/rest/files/FILEMDSPfe12/content",
      "path" : "username/UPxx456/DOC123edf/uploadedFile.pdf.1.tiff.txt",
      "content-type" : "text/plain",
      "size" : 5799
    }
  }

Giles Single Application v0.6 and newer

Code Block

language	js
title	Upload Image Sample Response from Giles

[ {
  "documentId" : "DOC123edf",
  "uploadId" : "UPxx456",
  "uploadedDate" : "2016-09-20T14:03:00.152Z",
  "access" : "PRIVATE",
  "uploadedFile" : {
    "filename" : "uploadedFile.pdf",
    "id" : "FILE466tgh",
    "url" : "http://your-giles-host.net/giles/rest/files/FILE466tgh/content",
    "path" : "username/UPxx456/DOC123edf/uploadedFile.pdf",
    "content-type" : "application/pdf",
    "size" : 3852180
  },
  "extractedText" : {
    "filename" : "uploadedFile.pdf.txt",
    "id" : "FILE123cvb",
    "url" : "http://your-giles-host.net/giles/rest/files/FILE123cvb/content",
    "path" : "username/UPxx456/DOC123edf/uploadedFile.pdf.txt",
    "content-type" : "text/plain",
    "size" : 39773
  },
  "pages" : [ {
    "nr" : 0,
    "image" : {
      "filename" : "uploadedFile.pdf.0.tiff",
      "id" : "FILEYUI678",
      "url" : "http://your-giles-host.net/giles/rest/digilib?fn=username%FILEYUI678%2FDOC123edf0%2FuploadedFile.pdf.0.tiff",
      "path" : "username/UPxx456/DOC123edf/uploadedFile.pdf.0.tiff",
      "content-type" : "image/tiff",
      "size" : 2032405
    },
    "text" : {
      "filename" : "uploadedFile.pdf.0.tiff.txt",
      "id" : "FILE789UIO",
      "url" : "http://your-giles-host.net/giles/rest/files/FILE789UIO/content",
      "path" : "username/UPxx456/DOC123edf/uploadedFile.pdf.0.tiff.txt",
      "content-type" : "text/plain",
      "size" : 4658
    }
  }, {
    "nr" : 1,
    "image" : {
      "filename" : "uploadedFile.pdf.1.tiff",
      "id" : "FILE045tyhG",
      "url" : "http://your-giles-host.net/giles/rest/digilib?fn=username%2FFILE045tyhG%2FDOC123edf0%2FuploadedFile.pdf.1.tiff",
      "path" : "username/UPxx456/DOC123edf/uploadedFile.1.tiff",
      "content-type" : "image/tiff",
      "size" : 2512354
    },
    "text" : {
      "filename" : "uploadedFile.pdf.1.tiff.txt",
      "id" : "FILEMDSPfeVm",
      "url" : "http://your-giles-host.net/giles/rest/files/FILEMDSPfeVm/content",
      "path" : "username/UPxx456/DOC123edf/uploadedFile.pdf.1.tiff.txt",
      "content-type" : "text/plain",
      "size" : 5799
    }
  }

...

Code Block
{ "errorCode" : "404", "errorMsg" : "Upload does not exist." }

v0.5 and older

For each uploaded file, Giles responds with either "success": 0 (upload was successful), or "success": 1 (upload failed).

Code Block

language	js
title	Upload Image Sample Response from Giles

[ {
  "documentId" : "DOCnbxbFU",
  "uploadId" : "UP50N1AV",
  "uploadedDate" : "2016-07-26T21:38:34.398Z",
  "access" : "PRIVATE",
  "files" : [ {
    "filename" : "your-file.jpeg",
    "path" : "http://your.host/giles/rest/digilib?fn=youruser/UP50N1AV/FILEz7JQFu/your-file.jpeg",
    "content-type" : "image/jpeg",
    "size" : 120830,
    "success" : 0,
	"id" : "FILE2FGTtG"
  }, {
    "filename" : "your-file-2.jpg",
    "path" : "http://your.host/giles/rest/digilib?fn=youruser/UP50N1AV/FILETAW3KI/your-file-2.jpg",
    "content-type" : "image/jpeg",
    "size" : 270769,
    "success" : 0,
	"id" : "FILE23rtG"
  } ]
} ]

Get all uploads of user

Status

colour	Yellow
title	GET

...

Code Block

[
  {
    "UPMDG2ddX4bDKk": [
      {
        "id": "FILE0fPS2iO6Ev7g",
        "filename": "myfirstfile.pdf"
      }
    ]
  },
  {
    "UPVrMKIv": [
      {
        "id": "FILEkUcHBh",
        "filename": "file2.0.tiff"
      }
    ]
  },
  {
    "UP7R6GOs": [
      {
        "id": "FILEkUcHBh",
        "filename": "myfile2.tiff"
      }
    ]
  }
]

Get image from Digilib

Status

colour	Yellow
title	GET

...

accessToken: an API token that is used to authenticate the uploading user (if possible use the Authorization header instead of this parameter)
fn: path to image in digilib
dw or dh: you need at least one size parameter, either width (dw) or height (dh) or both
any other digilib parameter (optional)

Get public image from Digilib

Status

colour	Yellow
title	GET

...

If the requested image is set to public, Giles will return the image from Digilib. Otherwise, you will receive an http status 403 Forbidden.

Get info about upload

Status

colour	Yellow
title	GET

...

Code Block

language	js
title	Upload Info Sample Response from Giles

[ "documentId" : "DOCOhcqLGMXL8dC",
  "uploadId" : "UPMDG2ddX4bDKk",
  "uploadedDate" : "2016-10-04T17:40:15.254Z",
  "access" : "PUBLIC",
  "uploadedFile" : {
    "filename" : "your-file.pdf",
    "id" : "FILE0fPS2iO6Ev7g",
    "url" : "https://your.host/giles/rest/files/FILE0fPS2iO6Ev7g/content",
    "path" : "youruser/UPMDG2ddX4bDKk/DOCOhcqLGMXL8dC/your-file.pdf",
    "content-type" : "application/pdf",
    "size" : 1453836
  },
  "extractedText" : {
    "filename" : "your-file.pdf.txt",
    "id" : "FILEjXRK3MKDjcqx",
    "url" : "https://your.host/giles/rest/files/FILEjXRK3MKDjcqx/content",
    "path" : "youruser/UPMDG2ddX4bDKk/DOCOhcqLGMXL8dC/your-file.pdf.txt",
    "content-type" : "text/plain",
    "size" : 84313
  },
  "pages" : [ {
    "nr" : 0,
    "image" : {
      "filename" : "your-file.pdf.0.tiff",
      "id" : "FILEgwyK2KjEiniN",
      "url" : "https://your.host/giles/rest/digilib?fn=youruser%2FUPMDG2ddX4bDKk%2FDOCOhcqLGMXL8dC%2Fyour-file.pdf.0.tiff",
      "path" : "youruser/UPMDG2ddX4bDKk/DOCOhcqLGMXL8dC/your-file.pdf.0.tiff",
      "content-type" : "image/tiff",
      "size" : 1938832
    },
    "text" : {
      "filename" : "your-file.pdf.0.txt",
      "id" : "FILEu3zp4FHaNBEz",
      "url" : "https://your.host/giles/rest/files/FILEu3zp4FHaNBEz/content",
      "path" : "youruser/UPMDG2ddX4bDKk/DOCOhcqLGMXL8dC/your-file.pdf.0.txt",
      "content-type" : "text/plain",
      "size" : 3461
    }
  }, {
    "nr" : 1,
    "image" : {
      "filename" : "your-file.pdf.1.tiff",
      "id" : "FILE1vgFj8feXHtG",
      "url" : "https://your.host/giles/rest/digilib?fn=username%2FUPMDG2ddX4bDKk%2FDOCOhcqLGMXL8dC%2Fyour-file.pdf.1.tiff",
      "path" : "youruser/UPMDG2ddX4bDKk/DOCOhcqLGMXL8dC/your-file.pdf.1.tiff",
      "content-type" : "image/tiff",
      "size" : 1938382
    },
    "text" : {
      "filename" : "your-file.pdf.1.txt",
      "id" : "FILER0t8JQ1WuU94",
      "url" : "https://your.host/giles/rest/files/FILER0t8JQ1WuU94/content",
      "path" : "youruser/UPMDG2ddX4bDKk/DOCOhcqLGMXL8dC/your-file.pdf.1.txt",
      "content-type" : "text/plain",
      "size" : 3930
    }
  }, {
    "nr" : 2,
    "image" : {
      "filename" : "your-file.2.tiff",
      "id" : "FILEzQaVarnXZy52",
      "url" : "https://your.host/giles/rest/digilib?fn=youruser%2FUPMDG2ddX4bDKk%2FDOCOhcqLGMXL8dC%2Fyour-file.pdf.2.tiff",
      "path" : "youruser/UPMDG2ddX4bDKk/DOCOhcqLGMXL8dC/your-file.pdf.2.tiff",
      "content-type" : "image/tiff",
      "size" : 1809905
    },
    "text" : {
      "filename" : "your-file.pdf.2.txt",
      "id" : "FILEFlTXtknorFua",
      "url" : "https://your.host/giles/rest/files/FILEFlTXtknorFua/content",
      "path" : "youruser/UPMDG2ddX4bDKk/DOCOhcqLGMXL8dC/your-file.pdf.2.txt",
      "content-type" : "text/plain",
      "size" : 3563
    }
  } ]
} ]

Get info about document

Status

colour	Yellow
title	GET

...

where {documentId} is the id of the upload you are requesting information about.

Giles Ecosystem

A response looks similar to this:

Code Block

{
  "documentId" : "DOCOhcqLGMXL8dC",
  "uploadId" : "UPMDG2ddX4bDKk",
  "uploadedDate" : "2016-10-04T17:40:15.254Z",
  "access" : "PUBLIC",
  "uploadedFile" : {
    "filename" : "your-file.pdf",
    "id" : "FILE0fPS2iO6Ev7g",
    "url" : "https://your.host/giles/rest/files/FILE0fPS2iO6Ev7g/content",
    "path" : "youruser/UPMDG2ddX4bDKk/DOCOhcqLGMXL8dC/your-file.pdf",
    "content-type" : "application/pdf",
    "size" : 1453836
  },
  "extractedText" : {
    "filename" : "your-file.pdf.txt",
    "id" : "FILEjXRK3MKDjcqx",
    "url" : "https://your.host/giles/rest/files/FILEjXRK3MKDjcqx/content",
    "path" : "youruser/UPMDG2ddX4bDKk/DOCOhcqLGMXL8dC/your-file.pdf.txt",
    "content-type" : "text/plain",
    "size" : 84313
  },
  "pages" : [ {
    "nr" : 0,
    "image" : {
      "filename" : "your-file.pdf.0.tiff",
      "id" : "FILEgwyK2KjEiniN",
      "url" : "https://your.host/giles/rest/digilib?fn=youruser%2FUPMDG2ddX4bDKk%2FDOCOhcqLGMXL8dC%2Fyour-file.pdf.0.tiff",
      "path" : "youruser/UPMDG2ddX4bDKk/DOCOhcqLGMXL8dC/your-file.pdf.0.tiff",
      "content-type" : "image/tiff",
      "size" : 1938832
    },
    "text" : {
      "filename" : "your-file.pdf.0.txt",
      "id" : "FILEu3zp4FHaNBEz",
      "url" : "https://your.host/giles/rest/files/FILEu3zp4FHaNBEz/content",
      "path" : "youruser/UPMDG2ddX4bDKk/DOCOhcqLGMXL8dC/your-file.pdf.0.txt",
      "content-type" : "text/plain",
      "size" : 3461
    },
    "ocr" : {
      "filename" : "your-file.pdf.0.tiff.txt",
      "id" : "FILEu3zp4FHaN567",
      "url" : "https://your.host/giles/rest/files/FILEu3zp4FHaN567/content",
      "path" : "youruser/UPMDG2ddX4bDKk/DOCOhcqLGMXL8dC/your-file.pdf.0.tiff.txt",
      "content-type" : "text/plain",
      "size" : 3461
    }
  }, {
    "nr" : 1,
    "image" : {
      "filename" : "your-file.pdf.1.tiff",
      "id" : "FILE1vgFj8feXHtG",
      "url" : "https://your.host/giles/rest/digilib?fn=youruser%2FUPMDG2ddX4bDKk%2FDOCOhcqLGMXL8dC%2Fyour-file.pdf.1.tiff",
      "path" : "youruser/UPMDG2ddX4bDKk/DOCOhcqLGMXL8dC/your-file.pdf.1.tiff",
      "content-type" : "image/tiff",
      "size" : 1938382
    },
    "text" : {
      "filename" : "your-file.pdf.1.txt",
      "id" : "FILER0t8JQ1WuU94",
      "url" : "https://your.host/giles/rest/files/FILER0t8JQ1WuU94/content",
      "path" : "youruser/UPMDG2ddX4bDKk/DOCOhcqLGMXL8dC/your-file.pdf.1.txt",
      "content-type" : "text/plain",
      "size" : 3930
    },
    "ocr" : {
      "filename" : "your-file.pdf.1.tiff.txt",
      "id" : "FILER123JQ1WuU94",
      "url" : "https://your.host/giles/rest/files/FILER123JQ1WuU94/content",
      "path" : "youruser/UPMDG2ddX4bDKk/DOCOhcqLGMXL8dC/your-file.pdf.1.tiff.txt",
      "content-type" : "text/plain",
      "size" : 3930
    }
  }, {
    "nr" : 2,
    "image" : {
      "filename" : "your-file.pdf.2.tiff",
      "id" : "FILEzQaVarnXZy52",
      "url" : "https://your.host/giles/rest/digilib?fn=youruser%2FUPMDG2ddX4bDKk%2FDOCOhcqLGMXL8dC%2Fyour-file.pdf.2.tiff",
      "path" : "youruser/UPMDG2ddX4bDKk/DOCOhcqLGMXL8dC/your-file.pdf.2.tiff",
      "content-type" : "image/tiff",
      "size" : 1809905
    },
    "text" : {
      "filename" : "your-file.pdf.2.txt",
      "id" : "FILEFlTXtknorFua",
      "url" : "https://your.host/giles/rest/files/FILEFlTXtknorFua/content",
      "path" : "youruser/UPMDG2ddX4bDKk/DOCOhcqLGMXL8dC/your-file.pdf.2.txt",
      "content-type" : "text/plain",
      "size" : 3563
    },
    "ocr" : {
      "filename" : "your-file.pdf.2.tiff.txt",
      "id" : "FILEFlTXtkn345ua",
      "url" : "https://your.host/giles/rest/files/FILEFlTXtkn345ua/content",
      "path" : "youruser/UPMDG2ddX4bDKk/DOCOhcqLGMXL8dC/your-file.pdf.2.tiff.txt",
      "content-type" : "text/plain",
      "size" : 3563
    }
  }

Giles Single Application

A response looks similar to this:

Code Block

{
  "documentId" : "DOCOhcqLGMXL8dC",
  "uploadId" : "UPMDG2ddX4bDKk",
  "uploadedDate" : "2016-10-04T17:40:15.254Z",
  "access" : "PUBLIC",
  "uploadedFile" : {
    "filename" : "your-file.pdf",
    "id" : "FILE0fPS2iO6Ev7g",
    "url" : "https://your.host/giles/rest/files/FILE0fPS2iO6Ev7g/content",
    "path" : "youruser/UPMDG2ddX4bDKk/DOCOhcqLGMXL8dC/your-file.pdf",
    "content-type" : "application/pdf",
    "size" : 1453836
  },
  "extractedText" : {
    "filename" : "your-file.pdf.txt",
    "id" : "FILEjXRK3MKDjcqx",
    "url" : "https://your.host/giles/rest/files/FILEjXRK3MKDjcqx/content",
    "path" : "youruser/UPMDG2ddX4bDKk/DOCOhcqLGMXL8dC/your-file.pdf.txt",
    "content-type" : "text/plain",
    "size" : 84313
  },
  "pages" : [ {
    "nr" : 0,
    "image" : {
      "filename" : "your-file.pdf.0.tiff",
      "id" : "FILEgwyK2KjEiniN",
      "url" : "https://your.host/giles/rest/digilib?fn=youruser%2FUPMDG2ddX4bDKk%2FDOCOhcqLGMXL8dC%2Fyour-file.pdf.0.tiff",
      "path" : "youruser/UPMDG2ddX4bDKk/DOCOhcqLGMXL8dC/your-file.pdf.0.tiff",
      "content-type" : "image/tiff",
      "size" : 1938832
    },
    "text" : {
      "filename" : "your-file.pdf.0.txt",
      "id" : "FILEu3zp4FHaNBEz",
      "url" : "https://your.host/giles/rest/files/FILEu3zp4FHaNBEz/content",
      "path" : "youruser/UPMDG2ddX4bDKk/DOCOhcqLGMXL8dC/your-file.pdf.0.txt",
      "content-type" : "text/plain",
      "size" : 3461
    }
  }, {
    "nr" : 1,
    "image" : {
      "filename" : "your-file.pdf.1.tiff",
      "id" : "FILE1vgFj8feXHtG",
      "url" : "https://your.host/giles/rest/digilib?fn=youruser%2FUPMDG2ddX4bDKk%2FDOCOhcqLGMXL8dC%2Fyour-file.pdf.1.tiff",
      "path" : "youruser/UPMDG2ddX4bDKk/DOCOhcqLGMXL8dC/your-file.pdf.1.tiff",
      "content-type" : "image/tiff",
      "size" : 1938382
    },
    "text" : {
      "filename" : "your-file.pdf.1.txt",
      "id" : "FILER0t8JQ1WuU94",
      "url" : "https://your.host/giles/rest/files/FILER0t8JQ1WuU94/content",
      "path" : "youruser/UPMDG2ddX4bDKk/DOCOhcqLGMXL8dC/your-file.pdf.1.txt",
      "content-type" : "text/plain",
      "size" : 3930
    }
  }, {
    "nr" : 2,
    "image" : {
      "filename" : "your-file.pdf.2.tiff",
      "id" : "FILEzQaVarnXZy52",
      "url" : "https://your.host/giles/rest/digilib?fn=youruser%2FUPMDG2ddX4bDKk%2FDOCOhcqLGMXL8dC%2Fyour-file.pdf.2.tiff",
      "path" : "youruser/UPMDG2ddX4bDKk/DOCOhcqLGMXL8dC/your-file.pdf.2.tiff",
      "content-type" : "image/tiff",
      "size" : 1809905
    },
    "text" : {
      "filename" : "your-file.pdf.2.txt",
      "id" : "FILEFlTXtknorFua",
      "url" : "https://your.host/giles/rest/files/FILEFlTXtknorFua/content",
      "path" : "youruser/UPMDG2ddX4bDKk/DOCOhcqLGMXL8dC/your-file.pdf.2.txt",
      "content-type" : "text/plain",
      "size" : 3563
    }
  }

Get full image from Giles

Status

colour	Yellow
title	GET

...

Versions Compared

Old Version 2

New Version 3

Key

Authentication

Add files to Giles

Giles Single Application v0.6 and newer/Giles Ecosystem

Giles Ecosystem

Giles Single Application v0.6 and newer

v0.5 and older

Get all uploads of user

Get image from Digilib

Get public image from Digilib

Get info about upload

Get info about document

Giles Ecosystem

Giles Single Application

Get full image from Giles

Page Comparison

Versions Compared

Old Version 2

New Version 3

Key

Authentication

Add files to Giles

Giles Single Application v0.6 and newer/Giles Ecosystem

Giles Ecosystem

Giles Single Application v0.6 and newer

v0.5 and older

Get all uploads of user

Get image from Digilib

Get public image from Digilib

Get info about upload

Get info about document

Giles Ecosystem

Giles Single Application

Get full image from Giles