buildingsmart/documents-api

part of the openCDE portfolio

documents-api's Issues

Link Swagger Hub and update it

We're using the swagger.yaml file here in this repository to create the Swagger specification. We should host that directly in Swagger Hub.

@ykulbak knows how to do this😀

Implementation note / recommendation required for upload completion end point

When a large file is uploaded, it may take up to several minutes for upload completion call to finish stitching all parts together and complete the upload. Because of this, idle timeout may be triggered on many load balancers's default configuration.

Examples for LB idle timeouts:

• Oracle OCI LBaaS HTTP idle timeout of 60 seconds
• AWS ELB Connection idle timeout of 60 seconds.

To ensure the upload completion does not timeout on large files, I suggest we add an implementation note / recommendation under Upload Completion for servers to periodically send whitespace characters back to keep the connection from timing out. This is similar to what AWS does for CompleteMultipartUpload.

Get approval from bSI for the logo

Alternatively, we should get a logo directly from bSI.

We'll keep the placeholder until then.

Indicate breach of polling frequency limit

Currently, it's undefined how a server will behave it receives too many polling requests in a given period. As a result, a client may continue to blindly retry (or worse, stop polling altogether).

Would it be out of the question to codify into the specification that if a server should respond with 429 Too Many Requests[1] if/when it decides that it has received too many polling requests from the client?

That specific response code would allow client implementations to understand what has gone wrong and to take corrective actions to reduce its impact: whether that action would be to go into a slower polling interval, reduce the number of documents that it's attempting to poll for in a single request, or simply notify the end user.

1: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429

Incosistency in visual

Hello there,

Last week we ran into an issue while implementing the OpenCDE API that turned out to be caused by an inconsistency in the documentation.

The chart shown in 3.2.1. Document Download Example of the Documents-API mentions that after the user has selected documents in the UI, the local_callback_url should be called with a URL parameter called selected_url:

However, the documentation itself states under 3.2.1.1.3. User Selects Documents in CDE UI that it actually should be selected_documents_url:

To avoid further issues, it would be nice if the chart would be updated.

Edit: code format for selected_url

Best regards

Decision: Include Acknowledgements / History?

Should we add a section at the bottom of the repository to list the companies that participated in the original project, or not?

Any input and feedback is welcome😀

State between download documents and upload documents

Hi there,

We are running into an issue that we feel should not be happening. Our system supports aggregating documents from different folders (like search, or creating so-called smart folders that aggregate documents based on a property like file extension).

We think this is great, cause this means that users can open documents across folders in the client application and are not bound to their folder structure. However, that also means that documents with the same name can open simultaneously in the client application. And in the case of having documents with the same name (and if it can happen, you have to take it into account), the issue arises when a user then decides to upload the files.

The only things we identified that are supported to distinguish files are:

for the file: file_name and some randomly generated session_file_id in the client application that does not relate to anything else, both useless in our case to map files to documents in our system

Then there is the option for the server_context, but in our case that also won't work as the state of the smart folder or search can change over the course of the user downloading document to the client application and starting to upload.

Are we missing something obvious in the OpenCDE documents protocol or is this not taken into account? Why doesn't the protocol prescribe using the document_id provided in the document download in the upload flow as well?

Regards

Add link to Swagger Hub in README and publish Swagger Hub API Definition

It's available here:
https://app.swaggerhub.com/apis/buildingSMART/Documents-API/1.0

At the moment, the API on Swagger Hub is not set to public yet. We should set it and then link it in the README.

upload_session query param in upload_documents_url

Referring to the documentation at upload_documents_url

It looks like the request and response are both documented in openapi spec, but the upload_session query parameter is not part of it. When generating either server-stub or client, in most frameworks there is no way to shoehorn it in. It would be really nice to use the generated code for these calls instead of manually coding them.

Perhaps there is a good reason for this, but why can't the upload_session be part of the request (json)? I understand this is kind of a private path on the CDE (CDE generating the URL and also consuming it), but still.