v2.0.0 - Hosted documents by davidronk · Pull Request #18 · DocRaptor/docraptor-csharp

davidronk · 2020-07-30T20:58:34Z

V2.0.0 - Hosted Documents

See below for important changes

As a paid add-on, DocRaptor can provide long-term, publicly-accessible hosting for your documents. This allows you to provide a URL to your end users, third party tools like Zapier and Salesforce, or anyone else. We'll host the document on your behalf at a completely unbranded URL for as long as you want, or within the limits you specify.

When you create a hosted document, DocRaptor will generate your document as usual. Asynchronous documents work as usual, except that the download URL in the final status response will be an unbranded domain. Synchronous hosted document requests respond with a JSON object rather than a binary blob.

The JSON will look like this:

{
  "download_id": "123-456-abc",
  "download_url": "http://<<unbranded domain>>/download/123-456-abc",
  "number_of_pages": 1
}

The download URL is publicly-accessible and doesn't require authentication.

By default, hosted documents do not have limits on downloads or hosting time, though you may pass additional parameters to the document generation call to set your own limits. Learn more about the specific options in the hosted API documentation.

Important API Changes

Constructor Argument Casing

The casing on the Doc model constructor arguments have been changed to reflect best reflect C# coding style best practices. This means that when we build a Doc the arguments are now camelCased where the used to be PascalCase.

This is a breaking change.

Before:

Doc doc = new Doc(
  Test: true,
  DocumentContent: "<html><body>Hello World</body></html>",
  Name: "docraptor-csharp.pdf",
  DocumentType: Doc.DocumentTypeEnum.Pdf
);

After:

Doc doc = new Doc(
  test: true,
  documentContent: "<html><body>Hello World</body></html>",
  name: "docraptor-csharp.pdf",
  documentType: Doc.DocumentTypeEnum.Pdf
);

DocStatus

To avoid confusion between the status of an asynchronous document and a hosted document the AsyncDocStatus model has been removed in favor of a shared, DocStatus model. This means that when you create an async document or hosted document both will return a DocStatus.

This is a breaking change.

Before:

When checking the status of an async document docraptor.GetAsyncDocStatus returned an AsyncDocStatus.

AsyncDoc response = docraptor.CreateAsyncDoc(doc);
AsyncDocStatus status_response;
Boolean done = false;

while(!done) {
  status_response = docraptor.GetAsyncDocStatus(response.StatusId);

After:

Now when checking the status of an async document docraptor.GetAsyncDocStatus returns a DocStatus.

AsyncDoc response = docraptor.CreateAsyncDoc(doc);
DocStatus status_response;
Boolean done = false;

while(!done) {
  status_response = docraptor.GetAsyncDocStatus(response.StatusId);

Checking the status of a hosted async document works the same way. docraptor.GetAsyncDocStatus returns a DocStatus.

AsyncDoc response = docraptor.CreateHostedAsyncDoc(doc);
DocStatus status_response;
Boolean done = false;

while(!done) {
  status_response = docraptor.GetAsyncDocStatus(response.StatusId);

Creating a synchronous hosted document works in a similar way, but because it is synchronous the docraptor.CreateHostedDoc method will return a DocStatus upon completion.

DocStatus status_response = docraptor.CreateHostedDoc(doc);

Example

Here is a quick example on how to create a hosted document with C#.

using DocRaptor.Client;
using DocRaptor.Model;
using DocRaptor.Api;
using System;
using System.IO;
using System.Threading;

class SyncTest {
  static void Main(string[] args) {
    Configuration.Default.Username = "YOUR_API_KEY_HERE"; // you will need a real api key to test hosted documents
    DocApi docraptor = new DocApi();

    Doc doc = new Doc(
      test: true,
      documentContent: "<html><body>Hello World</body></html>",
      name: "docraptor-csharp.pdf",
      documentType: Doc.DocumentTypeEnum.Pdf
    );

    DocStatus status_response = docraptor.CreateHostedDoc(doc);
    Console.WriteLine("Your document is now available for public download at {0}", status_response.DownloadUrl);
  }
}

- bumped swagger to 2.4.14 - updated docraptor.yaml - updated script/build to use generated build.sh for heavy lifting - updated libraries used in script/build - added System libraries when running tests Co-authored-by: Alex Overbeck <[email protected]> Co-authored-by: Nathan Acuff <[email protected]>

Why is this change needed? -------------------------- The strict parameter was causing some funny business. For whatever reason having a default value on a non-required parameter caused issues during instantiation with named parameters. The valid values for it are "none" and "html" How does it address the issue? ------------------------------ Since it's not a required parameter we removed the default value. We also fixed the valid values for the strict parameter to match the api. https://docraptor.com/documentation/api#api_strict Thirdly we moved pipeline down after the required fields so the important fields are listed first. Co-authored-by: Alex Overbeck <[email protected]>

Also switch to dependent libraries that swagger pulls in

The .swagger-codegen-ignore file tells swagger which files to leave alone during codegen. If big changes are made it would be worth letting swagger regenerate these but for the most part what we already have there is correct. Co-authored-by: Alex Overbeck <[email protected]>

- updated existing examples for swagger c# changes - created hosted document examples

- Added JsonSubTypes dependency - Updated example to match named parameter changes - verified and removed fixes for generated client section

- Renamed DocStatus > AsyncDocStatus - Created DocStatus that mirrors all the fields of AsyncDocStatus Co-authored-by: Alex Overbeck <[email protected]>

This reverts commit 6ab079e. This commit was designed to increase backwards compatibility but after further discussion it was decided that the added complexity was less desirable. Additionally there are already breaking changes in this new version that will need address and this would be a minor one.

mediocretes and others added 13 commits July 17, 2020 11:24

Regenerated code from new yaml file

962284c

Update tests to match swagger named parameter changes

700bf10

Switch to swagger build script

4a58959

Also switch to dependent libraries that swagger pulls in

Create hosted document tests

767bd26

Updated examples

9004daf

- updated existing examples for swagger c# changes - created hosted document examples

Reset RestSharp dependency to 105.2.3

1f635b4

Reverted from swagger README to previous one

e514bdd

- Added JsonSubTypes dependency - Updated example to match named parameter changes - verified and removed fixes for generated client section

Bring back AsyncDocStatus to prevent breaking changes.

6ab079e

- Renamed DocStatus > AsyncDocStatus - Created DocStatus that mirrors all the fields of AsyncDocStatus Co-authored-by: Alex Overbeck <[email protected]>

Set csharp agent to 2.0.0

f07ac33

jason-o-matic approved these changes Jul 31, 2020

View reviewed changes

davidronk merged commit 5accfbe into master Aug 3, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

v2.0.0 - Hosted documents#18

v2.0.0 - Hosted documents#18
davidronk merged 13 commits intomasterfrom
hosted_documents

davidronk commented Jul 30, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

davidronk commented Jul 30, 2020

V2.0.0 - Hosted Documents

See below for important changes

Important API Changes

Constructor Argument Casing

Before:

After:

DocStatus

Before:

After:

Example

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants