API Reference

REST resources

1. File resource
   • upload file
     • upload file as multipart file
     • upload file as url
   • download file
   • get file info
2. Validation Job resource
   • create job
   • start job
   • cancel job
   • get job info
3. Status resource
   • get file storage info
   • get job service info
4. Profiles info
   • get list of profiles

File resource

Field	Type	Remarks	Description
id	string	read-only	Unique file resource identifier, generated by server
fileName	string		Original file name
contentSize	integer		File size in bytes
contentType	string		File mime type, i.e. application/pdf
contentMD5	string		File MD5 checksum

Operations

Create file resource

Create file resource from multipart file

Request:

POST /api/files
Content-Type: multipart/form-data; boundary=---------------------------<random-text>

-----------------------------<random-text>
Content-Disposition: form-data; name="contentMD5"

<file-md5-checksum>
-----------------------------<random-text>
Content-Disposition: form-data; name="file"; filename="veraPDF-test.pdf"
Content-Type: application/pdf
Content-Length: <file-size>

<file-content>

-----------------------------<random-text>--

Response:

Content-Type: application/json
{
    "id": "feafa5ff-ffce-4c14-aa8f-ca5710ef7df9",
    "contentMD5": "e8a45acde0ba34b5871c787720f72c47",
    "contentType": "application/pdf",
    "contentSize": 389194,
    "fileName": "veraPDF-test.pdf"
}

Validation errors:

• checksum doesn't match:

Status: 400 Bad Request
{
    "error": "Bad Request",
    "message": "Expected file checksum doesn't match obtained file checksum. Expected: {}, actual: {}",
    "timestamp": "2020-04-13T19:04:07.252735Z",
    "status": 400
}

Create file resource from url

Request:

POST /api/files/url?url=https://www.pdfa.org/wp-content/uploads/2019/06/TaggedPDFBestPracticeGuideSyntax.pdf

Response:

Content-Type: application/json
{
    "id": "a8e23984-7b38-474b-8051-824a0b33c836",
    "contentMD5": "e8a45acde0ba34b5871c787720f72c47",
    "contentType": "application/pdf",
    "contentSize": 389194,
    "fileName": "TaggedPDFBestPracticeGuideSyntax.pdf"
}

Validation errors:

• malformed url or damaged file:

Status: 500 Internal server error
{
    "error": "Internal Server Error",
    "message": "Error while extracting file from url and saving it on disk.",
    "timestamp": "2023-03-22T11:58:08.598894Z",
    "status": 500
}

Download file

Request:

GET /api/files/{fileId}

Response:

Content-Type: {contentType}
{content}

Get file data

Request:

GET /api/files/{fileId}
Accept: application/json

Response:

Content-Type: application/json
{
    "id": "feafa5ff-ffce-4c14-aa8f-ca5710ef7df9",
    "contentMD5": "e8a45acde0ba34b5871c787720f72c47",
    "contentType": "application/pdf",
    "contentSize": 389194,
    "fileName": "veraPDF-test.pdf"
}

Validation Job resource

Job

Field	Type	Remarks	Description
id	string	read-only	Unique job identifier, generated by server
status	string	read-only	Job status, one of: CREATED, WAITING, PROCESSING, CANCELLED, FINISHED
profile	string	required	Profile used to validate file
progress	string		Progress string, shows the current validation progress of a job
queuePosition	int		Job's current position number in a queue with waiting jobs
tasks	array		Array of job-tasks(source files for job)

Task

Field	Type	Remarks	Description
fileId	string	required	file resource identifier of PDF file to be validated
status	string	read-only	File processing status: CREATED, WAITING, PROCESSING, CANCELLED, FINISHED, ERROR
errorType	string	read-only	Error type (e.g. INTERNAL_ERROR)
errorMessage	string	read-only	Error message
validationResultId	string	read-only	Id of validation result stored as file resource

Operations

Create new job

Request - profile only:

POST /api/jobs
Content-type: application/json
{
    "profile": "TAGGED_PDF"
}

Response:

Content-type: application/json
{
    "id": "4b5f88f8-5157-4d2e-b2ff-21d0c9166d60",
    "profile": "TAGGED_PDF",
    "status": "CREATED",
    "progress": null,
    "queuePosition": null,
    "tasks": null
}

Request - with tasks:

POST /api/jobs
Content-type: application/json
{
    "profile": "TAGGED_PDF",
    "tasks": [
        {
            "fileId": {fileId}
        }
    ]
}

Response:

Content-type: application/json
{
    "id": "b9760f78-5fde-44c7-9094-e2fc6bd9d813",
    "profile": "TAGGED_PDF",
    "status": "CREATED",
    "progress": null,
    "queuePosition": null,
    "tasks": [
        {
            "fileId": "8ce1d35f-8acc-4176-b820-28c8419e301a",
            "status": "CREATED"
        }
    ]
}

Validation errors:

• Profile does not exist

Status: 400 Bad Request
{
    "error": "Bad Request",
    "message": "Argument parsing failed",
    "timestamp": "2020-05-08T18:31:46.126877Z",
    "status": 400
}

Start job execution

Request:

POST /api/jobs/{jobId}/execution

Response:

Content-type: application/json
{
    "id": "0d622806-a359-426e-af53-705cd7c05d03",
    "profile": "TAGGED_PDF",
    "status": "WAITING",
    "progress": null,
    "queuePosition": 0,
    "tasks": [
        {
            "fileId": "f7033d3a-ecae-40ed-bfc0-124b23f7e7b6",
            "status": "WAITING"
        }
    ]
}

Cancel job execution

Request:

POST /api/jobs/{jobId}/cancel

No response

Get job info

Request:

GET /api/jobs/{jobId}

Response - created job:

Content-type: application/json
{
    "id": "b9760f78-5fde-44c7-9094-e2fc6bd9d813",
    "profile": "TAGGED_PDF",
    "status": "CREATED",
    "progress": null,
    "queuePosition": null,
    "tasks": [
        {
            "fileId": "8ce1d35f-8acc-4176-b820-28c8419e301a",
            "status": "CREATED"
        }
    ]
}

Response - processing job:

Content-type: application/json
{
    "id": "b9760f78-5fde-44c7-9094-e2fc6bd9d813",
    "profile": "TAGGED_PDF",
    "status": "PROCESSING",
    "progress": "Contrast detection 0%",
    "queuePosition": null,
    "tasks": [
        {
            "fileId": "8ce1d35f-8acc-4176-b820-28c8419e301a",
            "status": "PROCESSING"
        }
    ]
}

Response - cancelled job (if job was cancelled while waiting in the queue):

Content-type: application/json
{
    "id": "b9760f78-5fde-44c7-9094-e2fc6bd9d813",
    "profile": "TAGGED_PDF",
    "status": "CANCELLED",
    "progress": null,
    "queuePosition": null,
    "tasks": [
        {
            "fileId": "8ce1d35f-8acc-4176-b820-28c8419e301a",
            "status": "CANCELLED",
        }
    ]
}

Get validation result file

Request:

GET /api/jobs/{jobId}

Response - if job processing finished successfully:

Content-type: application/json
{
    "id": "b9760f78-5fde-44c7-9094-e2fc6bd9d813",
    "profile": "TAGGED_PDF",
    "status": "FINISHED",
    "progress": null,
    "queuePosition": null,
    "tasks": [
        {
            "fileId": "8ce1d35f-8acc-4176-b820-28c8419e301a",
            "status": "FINISHED",
            "validationResultId": "09a0a566-5f32-4e1d-a3cf-36b10d4300c5"
        }
    ]
}

Response - if job was cancelled during validation:

Content-type: application/json
{
    "id": "b9760f78-5fde-44c7-9094-e2fc6bd9d813",
    "profile": "TAGGED_PDF",
    "status": "CANCELLED",
    "progress": null,
    "queuePosition": null,
    "tasks": [
        {
            "fileId": "8ce1d35f-8acc-4176-b820-28c8419e301a",
            "status": "CANCELLED",
            "validationResultId": "09a0a566-5f32-4e1d-a3cf-36b10d4300c5"
        }
    ]
}

Then use obtained {validationResultId} as a query parameter to obtain JSON file from file resource:

Request:

GET /api/files/{validationResultId}

Response:

Content-Type: {contentType}
{content}

Note that the JSON file with validation result follows the following schema

Status

Operations

Get file storage build version info

Request:

GET /api/status/file-storage/info

Response:

Content-Type: application/json
{
    "build": {
        "artifact": "local-storage-service-server",
        "name": "local-storage-service-server",
        "time": "2020-04-03T08:29:51.906Z",
        "version": "0.1.0-SNAPSHOT",
        "group": "org.verapdf"
    }
}

Get job service build version info

Request:

GET /api/status/job-service/info

Response:

Content-Type: application/json
{
    "build": {
        "artifact": "job-service-server",
        "name": "job-service-server",
        "time": "2020-04-03T08:29:51.906Z",
        "version": "0.1.0-SNAPSHOT",
        "group": "org.verapdf"
    }
}

Profiles

Operations

Get list of profiles

Request:

GET /api/profiles

Response:

Content-Type: application/json
[
    {
        "profileName": "WCAG_2_1_COMPLETE",
        "humanReadableName": "WCAG 2.1 (All)",
        "enabled": true
    },
    {
        "profileName": "WCAG_2_1",
        "humanReadableName": "WCAG 2.1 (Extra)",
        "enabled": true
    },
    {
        "profileName": "PDFUA_1_MACHINE",
        "humanReadableName": "PDF/UA-1 (Machine)",
        "enabled": true
    },
    {
        "profileName": "PDFUA_1_HUMAN",
        "humanReadableName": "PDF/UA-1 (Human)",
        "enabled": false
    },
    {
        "profileName": "TAGGED_PDF",
        "humanReadableName": "Tagged PDF",
        "enabled": true
    },
    {
        "profileName": "PDFA_1_A",
        "humanReadableName": "PDF/A-1A",
        "enabled": false
    },
    {
        "profileName": "PDFA_1_B",
        "humanReadableName": "PDF/A-1B",
        "enabled": false
    }
]