Entities are single objects in the ShareFile API. Entities are always identifies by a URL, using the following pattern:
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.
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.
ShareFile OData entities will include an odata.metadata field that identifies the class of the element.
A full specification of the metadata element can be found at the ODATA site.
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
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:
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:
These are the built-in filter functions and operators supported by ShareFile, each with an example on the Items endpoint:
|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|
|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)|
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.
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.