REST API Web Services Common Errors & Troubleshooting Tips

This article describes common errors that may arise when using Documoto's REST Web Services and tips for troubleshooting them. 

Article Topics

• Publishing a Media
• Exporting a Media
• Fetch Parts 
• Get Uploaded Files List
• Fetch Users
• REST Web Services Support
  

Publishing a Media

The introduction of Documoto's REST Web Services include a change to the way content is published through web service calls. Specifically, uploading and publishing content is now an asynchronous task including new endpoints to support the updated workflow.

Below are the steps to upload content to Documoto via REST Web Services:

1. Submit an uploadFilesToPublish request (/publishing/upload/v1?submitForPublishing=false) including the file(s) you wish to upload.
   • Be sure to set the submitForPublishing query parameter to True or False
     • False is the default
     • True will automatically submit the file(s) for publishing once uploaded
2. If submitForPublishing is True, Documoto will return a JobId. Use this job ID with the GetJobStatus API (/publishing/job-status/v1/:jobId) to check the status of the publishing job.
3. If submitForPublishing is False, the file(s) can be submitted after upload by using the  PublishFile API (/publishing/publish/v1/:file) and passing in the file name. This will return a JobId that can be used with the GetJobStatus API to confirm completion. 
4. Once publishing is complete, be sure to set Access Controls with the SetAccessControls API (/authorization/media/access-controls/v1)

Common Errors

Exporting a Media

Exporting Media with Documoto's REST Web Services is very similar to the REST Upload Media process. It is now a multistep, asynchronous process.

The steps to export a Media are as follows:

1. Start an Asynchronous Export with the ExportMedia API (media/export-async/v1/:identifier) by passing the Media Identifier of the desired media in a query parameter. This will return a Job ID to use in polling for completion.
2. Use the returned Job ID with the ExportAsyncPoll API (/media/export-async-poll/v1/:requestId) to poll for the job status.
3. Once the export job has been completed, use the ExportAsyncReults API (/media/export-async-result/v1/:requestId) by passing in the completed Job ID. This will return the exported media in a data handler containing a Base64 encoded copy of the media file(s).

Fetch Parts 

The REST Fetch Parts API is very similar to the SOAP version, but the results differ and could potentially cause confusion. 

For the REST Fetch Parts API, the Start and Limit parameters are very important as they specify how many results to return and where to start in the list. The Start parameter is zero-indexed, meaning the list starts at position zero rather than position one. If you notice a response that mentions more lines returned that what you are seeing, please ensure that the start value is correctly set, often times as 0 (zero).

Get Uploaded Files List

The REST version of the GetUploadedFilesList API (/publishing/upload/v1/) has changed slightly, allowing for a fileNameFilter value to be appended to the end of the request URL, eg. /publishing/upload/v1/12345-V23.xml. Partial fileNames can also be used, similar to a "Contains" search within the Documoto Library.

A full list of files residing in the Uploaded directory for a given tenant can be retrieved by passing a space in the filter (/publishing/upload/v1/ ).

Fetch Users

The REST Fetch Users API (/user/v1) allows an API user to fetch a list of Users for a specified Organization. While it may not be apparent in the Swagger Specs, the organizationName, start, and limit parameters must be used as query parameters in the GET request, eg. /user/v1?organizationName=Organization&start=0&limit=100. The start and limit parameters are optional and default to 0 and 100, respectively. 

REST Web Services Support 

Do you have an error not described here? Please contact your Documoto Customer Success Manager or Documoto Support at support@documoto.com.