Building Single-Page Applications with DocuSign and CORS: Part 1
Thanks for visiting this older post. If you’re interested in CORS access to the eSignature REST API, check out its new CORS feature:
- CORS is here!
- OAuth for CORS applications
- Live CORS examples on CodePen
- Building a bulletproof CORS application
- DocuSign Developer Center CORS documentation
The original post:
This is the first part of a multipart series on building Single-Page Apps that integrate with the DocuSign Signature REST API. Check back for part 2!
“I feel the need, the need for speed!”
Your customers, users, and clients want your apps to be blazingly fast. And they don’t want the hassle or security concerns of downloading and installing a traditional client app: they want to use their browser.
To provide a snappy, responsive user experience, modern applications are often built as “client-side” applications, also known as “Single-Page Apps” (SPAs), or “Progressive Web Apps”.
Single-Page Applications (SPAs) are web apps that load a single HTML page and then dynamically update that page as the user interacts with the app.
With this software pattern, first popularized by the Gmail application, significant portions of the application execute within the browser itself. The browser-based JavaScript code makes API calls to its servers to store and retrieve data. The JavaScript app then creates the HTML needed to display the data to the user.
Instead of the classic web browser/server app technique of sending pages of html to the browser over the internet, SPA apps only send and receive data across the wire.
Today, the most advanced pattern of this type is the Progressive Web App. It provides the many advantages of an SPA app compared with a standard multi-page web app and more:
- Fast and smooth UX with no page loads after the initial load.
- Easy versioning and updates of the app since it is delivered as a web page.
- Great performance on bandwidth limited mobile devices: only data is sent to and from the servers, not HTML.
- Easy development and debugging through the use of modern frameworks and browser debuggers.
- Fast downloads through use of web worker HTML5 technology.
- Reliability: Load instantly and don’t show “Network down” errors, even in airplane mode.
The Progressive Web App pattern adds the last two items in the list above. Even without them, SPAs and the modern libraries that support them have taken the app development world by storm versus older style “thick client” apps.
While SPAs started in the consumer space for products such as Gmail, Gmaps, and Facebook, SPA apps are also produced by business to business companies including DocuSign, Microsoft, Box, and many others.
Enterprise SPA apps
The advantages of SPAs also apply to enterprise apps. Microsoft wrote an article on creating SPAs for the enterprise in November of 2013. Consultants have also written guides for creating enterprise SPA apps.
Enterprises often have an easier time writing SPA apps than ISVs since many enterprises standardize on a specific set of supported browsers.
Communicating with the App’s servers
When an app is written in JavaScript and running inside a browser, how does it communicate with the outside world? Depending on the data, different techniques are used. In all of these examples, the app was downloaded from apps.example.com/client/spa_app1.html
JavaScript, CSS, and image files
These files can be downloaded from anywhere on the internet. For example, instead of storing a copy of the Bootstrap libraries on the apps.example.com server, it is common to direct your users’ browsers to download them from an open source Content Delivery Network (CDN). Similarly, JQuery and other libraries can be downloaded from Google’s Hosted Libraries CDN.
API Data
No app is an island, so your app needs to both read and write data to one or more API servers on behalf of its user.
The app’s own server might offer an API at apps.example.com/api/v1/xxx The SPA app can use AJAX to access that API.
But AJAX won’t work when the app tries to use the DocuSign API at www.docusign.net/restapi/v2 The AJAX request will fail with the error “Same-origin policy violation.” This policy requires that the protocol, port, and host of the page (apps.example.com) match the AJAX destination. Since www.docusign.com doesn’t match apps.example.com, the AJAX request will fail.
CORS to the rescue
The best answer for making API requests to servers from different companies or “origins” is to use Cross-Origin Resource Sharing (CORS).
CORS will enable our SPA app to make calls to the DocuSign API. Since DocuSign doesn’t support CORS at this time, I’ll show you how to easily implement a private CORS gateway for DocuSign in the next part of this series.
If you’d like DocuSign to implement CORS for your own SPA app, please send me an email via developers@docusign.com.
Additional resources
Stay up-to-date with DocuSign developer news and information by visiting these additional resources:
