ShareFile API
  • Not Currently Logged In |
    Log In
  • ||
    Logout
  • arrow Getting Started
    • Quick Start Guide
    • OData Implementation
    • FAQ
    • Authentication
    • Postman
    • Storage Zones
  • Get an API Key
  • arrow API Entities
    • AccessControls
    • Accounts
    • Apps
    • AsyncOperations
    • Capabilities
    • ConnectorGroups
    • Devices
    • EncryptedEmails
    • FavoriteFolders
    • Favorites
    • FolderTemplates
    • Groups
    • Items
    • Metadata
    • Policies
    • Reports
    • Sessions
    • Shares
    • StorageCenters
    • Users
    • WebhookClients
    • WebhookSubscriptions
    • Workflows
    • Zones
  • arrowWebhooks
    • Overview
    • Events
    • Payloads
    • Signature Keys
  • arrowHow-To Guides
    • Common Use Cases
    • Troubleshooting
  • arrowCode Samples
    • C#(.NET)
    • Command Line / CURL
    • PHP
    • Python
    • Ruby
    • VB(.NET)
  • arrowSDKs
    • PowerShell
    • .NET
    • JavaScript

REST API Quick Start Guide

Where to Access the API

You will access your API using the same subdomain as you do to you access the ShareFile Web Portal. If you login to the portal with https://mycompany.sharefile.com, then the starting point for your ShareFile API will be at: 

https://mycompany.sf-api.com/sf/v3

How to Access the API

The ShareFile REST API uses a subset of the ODATA specification. ODATA is a HTTP-based REST API, with standards for how to describe objects and actions. You can get more details about ODATA here and additional details about the ShareFile API ODATA implementation here.

In order to try out the API operations you will need an HTTP utility or browser extension. Some freely available examples of such are:

  • Fiddler - Windows based application
  • Postman - Chrome plugin
  • Poster - Firefox plugin
  • CURL - command line tool available of most platforms

You will also need an OAuth2 key. See theOAuth2 Getting Started Guide.

So what do some requests and responses look like?

Here is the first request you might make after authenticating, retrieving the contents of your home folder. 

https://mycompany.sf-api.com/sf/v3/Items

The document above is a JSON serialization of the authenticated user's Home Folder. ShareFile uses the ODATA v3 JSON Light specification, all Entities are serialized using JSON and other Content-Type requests are not supported.

To see the folder contents you can add the $expand=Children ODATA query parameter to the url, which will return the additional "Children@odata.count" and "Children" elements, with the number of child items, and the items themselves respectively.

Try a request like:

https://mycompany.sf-api.com/sf/v3/Items?$expand=Children

Notice that each element has a "url" parameter. You can use that to retrieve the data for that object.

That's a lot of data though - imagine if there had been more than two items. Want to cut down on some of the fields that you may not particularly care about? Try adding a $select:

https://mycompany.sf-api.com/sf/v3/Items?$expand=Children&$select=FileCount,Id,Name,Children/Id,Children/Name,Children/CreationDate

This will return just the FileCount, Id and Name for the Home folder, and the Id, Name, CreationDate for any Children Items.

Authentication

ShareFile supports linking of elements across domains. As described above, a Connector service may contain Folders and Files references by a sharefile.com account. In this case, the client may be redirected to a Connector service when browsing a Folder structure. Just like an HTML browser, the ShareFile API client must expect authentication challenges when going from one domain to another. Domains may accept different authentication methods and session cookies. Clients are responsible for responding the challenges and keeping the session cookies within their own domains – clients must never pass cookies from one domain to another.

So What's Next?

The previous examples were some simple HTTP GETs of the Items resource. At some point you will also want to create, update, or delete a resource. These actions are covered by standard HTTP verbs, POST, PATCH, DELETE.

Or take a look a some of the sample code that is available to help you get started.