Getting Started with SmartVault’s REST API

Most Viewed Article

SmartVault’s REST API is a service for developers using the SmartVault storage system. The API provides web, mobile, and on-premises applications the ability to easily access SmartVault’s document management capabilities.  The SmartVault API supports XML, JSON, and the Google Protocol Buffer format.

Before You Begin

Before you register for a developer account and start coding, thinking through a few questions will help you select the most appropriate tools from the SmartVault API for your situation.  Specifically, this process will define the authentication scheme, the interaction method, and the integration model that is best suited to your needs.

1. Authentication: What Kind of Application Are You Building?

  • PIN-Based Authentication. If you’re building a customer-facing web, rich, or mobile app, you will want to use PIN-Based Authentication.  Using this technique, the user inputs a PIN code into your application.  The mechanism for generating and capturing this PIN code varies based on your application’s ability to handle a callback from the SmartVault web server:
    • Direct Entry. With a rich application (e.g., a command-line or WinForms application), registering a callback can be difficult or impossible.  In these situations, your application will make an API call to request a PIN on the user’s behalf.  The SmartVault server will reply with a URI that the user can follow to retrieve a PIN, which is in turn manually entered into your application.  The PIN is then used to authenticate each API call for that user.
    • Redirect URI. With a web or mobile application, you can register redirect URI (a callback) with the SmartVault API, and then use standard OAuth to have your application obtain the PIN.  The user will be prompted to Allow or Deny your application to access his or her information, but is not required to manually enter any PIN code as in the Direct Entry approach.
  • Autonomous Authentication. If you’re building a server-to-server application, you will want to use Autonomous Authentication which is based on RSA keypairs.  In general, Autonomous Authentication is suitable in situations where you can completely control a private key.  Using this approach, your application will authenticate to SmartVault using public/private keys, and all communication will be done over HTTPS using TLS 1.3.

2. Interaction: What Language Are You Writing Your Application in?

  • The SmartVault REST API can be called directly and supports data exchange using JSON and XML. This approach is ideal for web applications.
  • We also have C# and Java wrapper libraries that can be downloaded here.  The libraries use a binary transfer protocol using Google’s Protocol Buffers and make it easy to write applications in these languages by removing the need to create and parse API requests and replies.  These libraries are ideal for rich applications as well as mobile applications, although such applications can certainly use the Direct method as well.

3. Integration: How Do You Want to Use the SmartVault Service?

  • Generic Model. This model is best viewed as a hard drive in the cloud.  In this model, the SmartVault API allows you to CRUD folders and documents, invite users, and manipulate access control on the objects in the cloud.  This approach is best when you need flexibility and want to manage provisioning and maintaining folder structures, determine where to store and find documents, and maintain the mapping between objects and documents.
  • Application Model. In this model, you provide SmartVault a pre-defined mapping of your objects to a folder structure, and SmartVault will create and maintain that mapping for you. This model reduces some flexibility, but simplifies provisioning and maintaining folder structures and object-document mapping.

 

Where To Go From Here

Now that you’ve given some thought as to what tools you will need to build your application, it would be a good idea to visit the Terminology and API Overview pages to get familiar with SmartVault’s REST API. Moreover, if you want to dive deeper into Autonomous and Pin-Based Authentication, be sure to check out these articles.

If you get stuck, post your questions in the Forum and our developers will gladly help.
 
 

Leave A Comment?