RESTHooks

Post date: Feb 05, 2015 7:7:3 PM

This blog post is intended to be a working draft to discuss the implementation of RESTHooks in QBO3.

QBO3 needs to implement RESTHooks, so third parties can be notified of when an async operation completes.

Sample use cases include:

• • Call ImportFile/Queue/Import, let me know when done

  • Call Decision/Save, let me know when the decision completes

  • Call ImportForm/Save, let me know when the task is completed

  • Call Attachment/Queue/Generate, let me know when the operation is done

  • Call {ClassName}/Queue/{Operation}, let me know when the operation is done

Provide RESTHook callback parameters:

• • Add them to the query string?

  • Add them as an HTTP header?

RESTHook actions:

• • Make an HTTP GET

  • Make an HTTP POST

  • Send an Email

  • Send an SMS

RESTHook payload:

• • A serialized object?  (E.g. ImportFile/Select?)

  • A serialized IQueue message?

  • An empty payload, but string-substitute parameters

What a RESTHook is NOT:

• • a mechanism to replace IService for complicated operations (e.g. no extra query lookups or data transformations when invoking the RESTHook)

Sample Use Case: Matrix/AsyncLookup

Matrix/AsyncLookup is used to bulk-process matrix calls.  The body of the post is an XML document containing Matrix inputs; we probably don't want to force a third party developer to mix their RESTHook into that.  

Thus, we could do the following on the request:

RESTHook on the query string:

GET http://localhost/Application/Matrix.ashx/AsyncLookup?Matrix=ABC 123&RESTHook=smtp:someone@example.com HTTP/1.1

Host: localhost

Connection: keep-alive

Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8

...

RESTHook in an HTTP Header:

GET http://localhost/Application/Matrix.ashx/AsyncLookup?Matrix=ABC 123 HTTP/1.1

Host: localhost

Connection: keep-alive

Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8

X-REST-Hook: smtp:someone@example.com

...

In either case, en email would go out to someone@example.com with some sort of body.

We might extend the queuing infrastructure to handle RESTHooks by considering them a callback.  Roughly:

• • HttpHandler: if we see a RESTHook header, inject a callback based on the operation

  • ?