Citrix 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
    • migration-guide
    • 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
    • Java SE
    • PHP
    • Python
    • Ruby
    • VB(.NET)
  • arrowSDKs
    • PowerShell
    • .NET
    • JAVA
    • JavaScript
  • Change Log
  • V1 to V3 Migration

OData Implementation

Entities

Entities are single objects in the ShareFile API. Entities are always identifies by a URL, using the following pattern:

https://server/provider/version/entity(id)
  • Server - the API server domain name.
    • For ShareFile.com(host) accounts use myaccount.sf-api.com
    • For Storage Zone Connectors, use the external address you specify during Storage Zone configuration.
  • Provider: specify the type of API server. The known values are:
    • sf - for sharefile.com
    • cifs - for CIFS Storage Zone connector
    • sp - for SharePoint Storage Zone connector
    • Other providers may be created by third-parties.
  • Version - specifies the API version. Current default value should be v3. Changes that would cause backward compatibility issues will be done at a new version URL.
  • Entity - specifies a ‘class’ in the ShareFile data model – like Items, Users, etc.
  • Id - identifies a single Entity.

Example:

https://myaccount.sf-api.com/sf/v3/Items(id)

This URL identifies a single Item (File or Folder) in the account "myaccount".

All Entities are serialized using the ODATA v3 "JSON Light" specification, i.e. requests will return JSON formatted objects. For POST and PATCH requests that create or update data in ShareFile, the request body data must also be passed as JSON objects. Other Content-Type requests are not currently supported.

Metadata

ShareFile OData entities will include an odata.metadata field that identifies the class of the element.

Example:

A full specification of the metadata element can be found at the ODATA site.

Feeds

Feeds represent Collection of Entities and will contain additional fields that describe the collection.

  • value - a JSON array of the Collection
  • odata.count - the number of items in the Collection
  • odata.nextlink

Feeds are used every time a request returns a Collection of objects, Children of a Folder for example. The top-level folders of an authenticated user can be retrieved by using the following URL: 

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

A GET on this URL will retrieve a Feed of Items like below:

Common Query Parameters

While some operations will have their own set of query string parameters, the following can be used with any API call to affect the data that is returned:

  • $select
  • $expand
  • $top
  • $skip
  • $orderby
  • $filter

These are the built-in filter functions and operators supported by ShareFile, each with an example on the Items endpoint:

Function/Operator Usage Example
Equality (Property) eq (Value) /sf/v3/Items/Children?$filter=HasMultipleVersions eq true
Inequality (Property) ne (Value) /sf/v3/Items/Children?$filter=Id ne 'Box'
SubstringOf substringof('string searchString', string propertyName) eq boolean /sf/v3/Items/Children?$filter=substringof('foo', FileName) eq true
StartsWith startswith(string propertyName, 'string searchString') eq boolean /sf/v3/Items/Children?$filter=startswith(Id, 'fo') eq false
EndsWith endswith(string propertyName, 'string searchString') eq boolean /sf/v3/Items/Children?$filter=endswith(FileName, '.pdf') eq true
IsOf isof(ShareFile.Api.Models model) /sf/v3/Items/Children?$filter=isof(ShareFile.Api.Models.Folder)
And Filter and Filter /sf/v3/Items/Children?$filter=startswith(FileName,'foo') eq true and endswith(FileName, 'bar') eq true
Or Filter or Filter /sf/v3/Items/Children?$filter=isof(ShareFile.Api.Models.Note) or startswith(Id, 'no') eq true
GreaterThan (Property) gt (Value) /sf/v3/Items/Children?$filter=CreationDate gt date(9999-99-99)
LessThan (Property) lt (Value) /sf/v3/Items/Children?$filter=CreationDate lt date(9999-99-99)

Relationship Objects

By default, the API will not retrieve relationship objects, such as the Creator of a File, or Children of a Folder. You can ask the API to retrieve all relationships by appending $expand=* to the URI.

Actions

ODATA uses HTTP Verbs to describe Create, Read, Update, Delete operations (C.R.U.D.)

  • GET - Read
  • POST - Create
  • PATCH - Update
  • DELETE - Delete

GET operations do not cause changes in ShareFile data and return a JSON encoded response. POST and PATCH requests that create or update ShareFile entities must send the JSON object within the request body.