API Reference - RomaPrograms/verapdf-webapp-server-1 GitHub Wiki

REST resources

  1. File resource
  2. Validation Job resource
  3. Status resource

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

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="sample.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
}
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, PROCESSING, FINISHED, ERROR
profile string required Profile used to validate file
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, QUEUED, PROCESSING, 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",
    "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",
    "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
}
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",
    "tasks": [
        {
            "fileId": "8ce1d35f-8acc-4176-b820-28c8419e301a",
            "status": "CREATED"
        }
    ]
}
Start job

Request:

POST /api/jobs/{jobId}/execution

Response - updated job:

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

Validation errors:

  • Job with passed id does not exist:
Status: 404 Not Found
  • Job was already started:
Status: 409 Conflict
{
    "error": "Conflict",
    "message": "Cannot start already started job with specified id: ",
    "timestamp": "2020-05-25T14:55:56.352907Z",
    "status": 409
}

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"
    }
}
⚠️ **GitHub.com Fallback** ⚠️