AbleDocs ADapi allows users and companies to submit document accessiblity remediation requests on-demand. ADapi supports both configuration-based automated remediation of pre-defined classes of user documents through the ADStream service, as well as technician-performed document accessibility remediations through our ADService workflow.
Users are required to sign up with AbleDocs for ADapi access. Please contact your AbleDocs representative or email
ADapi supports a simplified system for submitting remediation requests as multipart/form-data requests, as well as a more flexible system for submitting remediation requests in JSON format.
ADapi only accepts https connections and requires TLS 1.2 or greater.
To get started with making AbleDocs ADapi requests:
POST to /authorize with a multipart form-data request or with a JSON object body containing your username and password, and optionally a time to live (ttl) parameter specifying the maximum amount of time the returned JWT should be valid for.
Multipart form-data example:Content-Type: multipart/form-data; boundary=AaB03x
--AaB03x
Content-Disposition: form-data; name="username"
Name
--AaB03x
Content-Disposition: form-data; name="password"
PW
--AaB03x
Content-Disposition: form-data; name="ttl"
3600
--AaB03x
{
"username" : "Name",
"password" : "PW",
"ttl" : "3600"
}
Keep the returned JWT token as this is your authentication credential for all other ADapi calls. Supply the JWT token to ADapi calls in the Authorization field of you request header:
Authorization: Bearer [JWT token]
POST to /requests with a multipart form-data request containing a PDF file for remediation and the type of remediation service desired. For those who are looking to quickly set up automated PDF document remediation, you'll want to specify "ADStream" as your remediation type. The file to remediate should be specified with a content type of application/pdf and a content disposition type of form-data and name "file"
Multipart form-data example:Content-Type: multipart/form-data; boundary=AaB03x
--AaB03x
Content-Disposition: form-data; name="remediationType"
ADStream
--AaB03x
Content-Disposition: form-data; name="file"
Content-Type: application/pdf
(contents of PDF as binary data)
--AaB03x
There are a number of optional parameters you may supply for your request call; please see below for more details.
On successful request submission, a 202 ACCEPTED code will be returned, along with a JSON object representing the created remediation request. Use the "id" value to refer to this remediation request.
Use a GET call to /requests/{requestID} to obtain the status of your remediation request, where {requestID} is the "id" field value for the request that was returned from the remediation request creation step above. This call will return a JSON object representing the remediation request. Monitor the "status" field - when its value changes to "Completed", then PDF file remediation is finished and you may obtain the result.
When the remediation request is Completed, note the value of the "outputFile" field in the returned remediation request. You'll use this to retrieve the remediated document rendition.
You may need to poll multiple times before the remediation completes. We recommend allowing at least 3 seconds between polling calls. ADapi callers may also provide a callback that will be called when a remediation request has a status change - see below for more details.
Use a GET call to /files/{fileID}/data to obtain the remediated PDF file for your remediation request, where {fileID} is the "outputFile" value obtained from the remediation request.
A 200 OK HTTP response code will be sent for files which have associated file data. File data for a remediated PDF file will be returned in binary format with MIME type application/pdf.
User authentication is performed via the /authorize endpoint. The /authorize endpoint will accept POST calls with either multipart form-data or with JSON object data.
JSON: POST a JSON object containing your username and password, and optionally a time to live (ttl) specifying how long, in seconds, the returned JWT is valid for.
Multipart form-data: POST a multipart/form-data encoded payload containing your username and password, and optionally a time to live (ttl) specifying how long, in seconds, the returned JWT is valid for.
On success, the /authorize endpoint returns a 200 response with a MIME body type of application/jwt containing the JWT token as a Base64 encoded string. Use the returned JWT token exactly as returned in the authorization header for subsequent ADapi calls. Refer to the API documentation for more information about the fields contained within the JWT token.
If an invalid username or password is supplied, a 403 Forbidden is returned from the /authorize endpoint.
Returned JWT tokens are valid for 1200 seconds - 20 minutes - by default, unless a different validity period is specified via the 'ttl' parameter when calling /authorize. Calling ADapi endpoints with an expired token or with an invalid token will both result in a 401 Unauthorized return code.
Having obtained a valid JWT token, you may use this token to change your user account password if you desire. Use the /user/password endpoint to supply a new password for your user acccount. Your valid JWT token serves as your proof of authorization.
The /user/password API endpoint accepts a JSON object body containing a new password. Please see the API documentation for the form of this JSON body. Password changes take effect immediately. However, existing valid JWT tokens will continue to remain valid until their expiration time elapses.
Callers should POST to the /requests API endpoint to make a document remediation request. There are two supported workflows for making remediation requests:
For both the form-data and the JSON workflows, the "remediationType" parameter is required. This is a string and must be one of the following values:
For the form-data based workflow, the "file" parameter is required. This represents the file for accessiblity remediation. Callers are required to supply a valid MIME type for the Content-Type field. If a file is not supplied, the /requests endpoint will return an HTTP 400 Bad Request error code.
For the JSON based workflow, the "inputFile" parameter is required. This represents the ID of the File object to perform accessibility tagging and remediation upon. If the inputFile is missing when a JSON based remediation request is submitted for processing via the /requests/{requestID}/submit endpoint, an HTTP 400 Bad Request error code will be returned. See below for more information on this workflow.
For both the form-data and the JSON based workflows, the following parameters are optional:
A valid JWT bearer token is required for ADapi calls to post remediation requests. Callers are required to supply this in the header in the Authorization field:
Authorization: Bearer [JWT token]
On success, a 202 ACCEPTED http response code will be sent, along with a JSON object body representing the created remediation request:
{
id : string (uuid): the ADapi identifier for this remediation request
docType: string, will be empty if not supplied
errors: array of error object (as documented below. Will be empty at creation if no error)
fileType: string, will be empty if not supplied
guid: string, will be empty if not supplied
inputFile: string (uuid): the ADapi identifier for the input file uploaded
outputFile: string (uuid): the ADapi identifier for the remediated document rendition. This will be empty for newly created remediation requests.
remediationType: string, (one of “ADService” or “ADStream")
status: string, (will be "submitted" at creation)
version: integer
}
While the inputFile and outputFile are currently single ID values, callers should be prepared to receive and process individual ID values or arrays of ID values for both these parameters for future compatibility.
Multipart form-data example:Content-Type: multipart/form-data; boundary=AaB03x
--AaB03x
Content-Disposition: form-data; name="guid"
33ae675f-855c-4ba9-a627-3a403c83954c
--AaB03x
Content-Disposition: form-data; name="version"
1.0
--AaB03x
Content-Disposition: form-data; name="fileType"
PDF
--AaB03x
Content-Disposition: form-data; name="docType"
Prospectus
--AaB03x
Content-Disposition: form-data; name="remediationType"
ADStream
--AaB03x
Content-Disposition: form-data; name="file"
Content-Type: application/pdf
(contents of PDF as binary data)
--AaB03x
Remediation requests made with JSON data as provided input to ADapi go through a multi-step user process. First, users create a File ADapi object for the input file to be remediated, and then associate file data to that File ADapi object. Then, the ID of that File object is supplied to the remediation request call. Finally, the remediation request is submitted to ADapi for processing. While more complex and involving a greater number of calls vs. the multipart/form-data remediation request workflow, the JSON data remediation request workflow provides greater flexibility to callers.
Callers should POST to the /files API endpoint to create an ADapi File object. The following parameter is required:
Callers may supply the following optional parameter:
The POST to the /files API endpoint will return a JSON object representing the File ADapi object, which will include an "id" value.
To associate data with the File object, callers should PUT to the /files/{fileID}/data API endpoint, where {fileID} is the File object ID value returned when creating the File object.
Once data is associated to the File object by a caller, then the caller should POST to the /requests ADapi endpoint to create the remediation Request object. Required and optional parameters are as listed above in "Making remediation requests", with the addition of the following parameter:
On success a 202 ACCEPTED code will be returned along with a JSON object representing the remediation request, as documented above in "Making remediation requests".
Unlike the multipart/form-data submission workflow, with the JSON data workflow the remediation request is created in a Pending status and must be submitted in order for ADapi processing to be initiated. Once a remediation Request is created, callers should PUT to the /requests/{requestID}/submit ADapi endpoint to initiate accessiblity remediation for the File contained within the Request. For ADStream remediation requests, processing is initiated upon request submission. For ADService remediation requests, submission will cause the request to be queued for accessibility remediation by an AbleDocs remediation technician.
When the status of a remediation request becomes Completed, the remediated rendition of the document associated with a remediation request is ready for download. The remediated file is stored by ID in the Request object's "outputFile" data field. Using this ID, the File object can be accessed as follows:
GET /files/{fileID}
Where {fileID} is the value of the file in the "outputFile" data field of the Request object.
The File object contains information about the file. To download the file data:
GET /files/{fileID}/data
Where {fileID} is the ID for the File object to download the data for. This call will return the file data directly as a binary transfer, with the MIME type set to the file MIME type stored for the File object if it is known.
AbleDocs ADapi document accessiblity remediation requests include a Status field containing the current workflow stage for any given remediation Request object.
The stages of a remediation Request are as follows:
ADapi callers may determine that the status of an accessiblity document Request object has changed in one of two ways:
When a callback is supplied for a given Request, the callback is called for every change in Request status.
Remediation requests have no mechanism for resubmission. For requests that are aborted with errors, any errors in the input file for remediation should be corrected and a new remediation request submitted.
ADapi offers both automated and human-performed accessibility remediation for documents. ADService remediations are performed by the expert remediation staff at AbleDocs and do not need to be of any specific layout or class of document. PDF, Word, Excel and PowerPoint files are all accepted for ADService remediations.
ADStream remediations are designed for automated remediation of PDF documents where these can be categorized into document types or classes based on their layout and characteristics. For example, an institution may generate personalized invoices for millions of customers every month, where these invoices all have a mix of static and variable content and a consistent pattern to their layout for each invoice.
All ADStream remediations require a corresponding processing template. As part of your ADapi onboarding process, AbleDocs and your institution will work to identify and classify each different type of document that is suitable for automated ADStream processing. AbleDocs will create an ADStream processing template for each document type. Once templated, each different class of document will be given a different document type string. This document type string should be supplied to remediation requests in the "docType" input parameter for the remediation request. When processing the remediation request, ADapi will search for an ADStream processing template with a name matching the document type passed in the "docType" remediation input field. If no match is made, an HTTP 400 Bad Request will be returned when attempting to submit the remediation request.
In some workflows, you may not be able to supply document type strings for remediation requests. To support these workflows, AbleDocs is able to set up input document name match strings for processing templates. When the "docType" string is not supplied or is empty for an ADStream remediation request, ADapi will fall back to attempting to match document templates based on the input file name string supplied when you created a FileInfo object for your input file.
For successfully processed ADStream remediation requests, the name of the template used for processing is stored in the request's "templateUsed" field. If a language code was obtained from the definition of the processing template (and not supplied when creating the request), the request's "langCode" field will be updated to reflect this language code.
ADapi will reject ADStream remediation requests where a template match cannot be made. In these cases, an HTTP 400 Bad Request will be returned from the remediation request submission call, with the error message returned indicating that a template match could not be made.