SAP Analytics Cloud File Repository API

[paul_brownsey]

The Q1 2025 release of SAP Analytics Cloud includes amongst its new features the File Repository API, which provides developers with programmatic access to metadata about all the objects stored in the Files area of SAP Analytics Cloud.

This API can be useful if you're building your own application that needs access to metadata about files stored in SAP Analytics Cloud. Use-cases include:

• Embedding lists of links to SAP Analytics Cloud content in your application
• Retrieving metadata from multiple SAP Analytics Cloud tenants to compare their contents
• Retrieving metadata for external cataloging purposes
• Retrieving metadata for other administrative/housekeeping purposes

The API includes two endpoints:

• /api/v1/filerepository/Resources is the main API endpoint that you use to query for file resources. You can also query for a specific resource by resourceId as in /api/v1/filerepository/Resources(‘11500004B0B75677E705DD8C9801AC29’)
• /api/v1/filerepository/$metadata describes the entities that are exposed by the API

Sample Results

For each file resource returned by the API, the default set of properties will be similar to what’s shown in the following example:

    {
      "resourceId": "11500004B0B75677E705DD8C9801AC29",
      "objectId": "STORY:t.1:11500004B0B75677E705DD8C9801AC29",
      "name": "Name of the file",
      "description": "Description of the file",
      "resourceType": "STORY",
      "resourceSubtype": "",
      "createdTime": "2025-01-16T22:28:23.538Z",
      "createdBy": "USER001",
      "modifiedTime": "2025-01-16T22:28:23.538Z",
      "modifiedBy": "USER001",
      "folderType": "PUBLIC",
      "parentFolderResourceId": "E3C80C0224E39749AB1B831D57408FC6",
      "workspaceId": null,
      "workspaceName": null,
      "openURL": "/sap/fpa/ui/tenants/b1567d/bo/story/11500004B0B75677E705DD8C9801AC29",
      "isMobile": true,
      "isTranslationEnabled": false,
      "isFeatured": false
    }

 

Authentication

Since the API today only supports GET requests, you can preview its functionality using just your web browser. Log on to SAP Analytics Cloud with your usual user account, and then go to https://your-SAC-tenant-URL/api/v1/filerepository/Resources to get an initial set of results.

To use the API programmatically, you first need to create an OAuth client in your SAP Analytics Cloud tenant. Then you need to authenticate from your application to SAP Analytics Cloud using that OAuth client. SAP Analytics Cloud supports several OAuth authentication flows. For details, see Setting up Authentication | SAP Help Portal.

A straightforward authentication flow is the OAuth client credentials grant type outlined in Basic Authentication Against the Token Service. If you take that approach, first create your OAuth client under System > Administration > App Integration, setting its API Access to “File Repository Read”, and its Authorization Grant to “Client Credentials”, as shown here:

 

Authorization to File Resources

By default, the API takes into account the SAP Analytics Cloud sharing permissions of the user that is making the API request. So, if you log on to SAP Analytics Cloud and then browse the API endpoint with your web browser at /api/v1/filerepository/Resources, the query results will include all files that are available to your user account in the Files > My Files view of the product UI, plus the files stored in any workspaces that your user belongs to.

If you have an administrative account in SAP Analytics Cloud—more specifically, if you are assigned a role that includes the Manage privilege on Public Files and/or Private Files—then you can alternatively have the API return all files that are available on the SAP Analytics Cloud tenant under the Files > System view in the product UI. To achieve this administrative view via the API, append the additional URL parameter applyManagePrivilege=true to the API URL (as in, /api/v1/filerepository/Resources?applyManagePrivilege=true).  

Note: If your application authenticates with the OAuth client credentials flow, then this URL parameter applyManagePrivilege=true can similarly be used to access an administrative view of all files on the SAP Analytics Cloud tenant.

 

Pagination and Total Results Count

The API paginates its results in batches of 50 resources. If your query results exceed 50 resources, then only the first 50 are initially returned, and the results body will include an "@odata.nextLink" annotation with a URL to follow to retrieve the next batch of results.

If you want to know how many total results your query has, you can include the $count=true parameter in your query URL.

The following example shows partial query results from the query URL /api/v1/filerepository/Resources?$count=true, including a total count of query results (i.e., 177), and a link to the second batch of results (i.e., “Resources?%24count=true&%24skiptoken=50”):

{
  "@odata.context": "$metadata#Resources",
  "@odata.count": 177,
  "@odata.nextLink": "Resources?%24count=true&%24skiptoken=50",
  "value": [
       // metadata for the first 50 resources will appear here
   ]
} 

To retrieve the second batch of results, you would go to /api/v1/filerepository/Resources?%24count=true&%24skiptoken=50. The results of that query will again include another @odata.nextLink annotation providing a link to the third batch of results. This will continue until you retrieve the last batch of results, at which point there will no longer be an @odata.nextLink included in the results.

 

Selecting, Sorting and Filtering

You can use the OData $select, $orderby and $filter query options to refine the results returned by the API. You can use these query options in conjunction with any of the properties that are returned for each resource by the API (e.g., resourceId, objectId, name, description, resourceType, resourceSubtype, createdTime, createdBy, etc.)

Use $select to reduce the number of properties returned by the API and thus reduce the size of its payload. For example, Resources?$select=resourceId,name,openURL will return just the resourceId, name, and openURL properties for each file resource.

Use $orderby to sort results. For example:

• Resources?$orderby=name%20asc will sort by name in ascending order.
• Resources?$orderby=modifiedTime%20desc will sort by modifiedTime in descending order.

Use $filter to restrict query results to just the files that match your filter criteria. For example:

• Resources?$filter=resourceType eq 'FOLDER' returns just the folder resources
• Resources?$filter=resourceType eq 'STORY' and resourceSubtype eq '' returns just the stories (where resourceSubtype is empty).
• Resources?$filter=resourceType eq 'STORY' and resourceSubtype eq 'INSIGHT' returns just the Data Analyzer Insights.
• Resources?$filter=modifiedTime gt 2024-07-31T12:29:52Z returns just the files modified after a specific timestamp. Note that no quotation marks are needed around the timestamp value.

The following are valid filter comparison operators:

• eq: equal
• ne: not equal
• gt: greater than
• ge: greater than or equal
• lt: less than
• le: less than or equal
• in: is a member of a list specified as (‘Member1’, ’Member2’)

You can combine filters and sort expressions to further refine the API query results, for example combining them as in Resources?$filter=resourceType eq 'FOLDER' and modifiedTime gt 2024-07-31T12:29:52Z&$orderby=modifiedTime desc

 

Expansion of Navigation Properties

You can retrieve additional metadata about each file resource by using the OData $expand query option.

For example, you can expand ancestorFolders to see a collection of the folders that each returned resource is contained within: Resources?$expand=ancestorFolders

Or you can expand dependencyObjects to see a collection of the file repository resources that each returned resource depends upon: Resources?$expand=dependencyObjects

You can further combine the use of the $expand query option with the OData “any” operator to iterate over dependencyObjects or ancestorFolders collections to do things like the following:

• Retrieve all objects that depend on a specific object (based on its resourceId): Resources?$expand=dependencyObjects&$filter=dependencyObjects/any(d:d/dependencyResourceId eq 'C41qg8uuay285i6wfudm5kga9s')
• Retrieve all objects that have an ancestor folder matching a specific name: Resources?$expand=ancestorFolders&$filter=ancestorFolders/any(a:a/name eq 'SAP_FI_FPA_S4_Financial_Planning')

Finally, you can expand all available navigation attributes at once to retrieve all possible metadata from the API: Resources?$expand=ancestorFolders,dependencyObjects,extendedProperties,extraProperty,usage,resourceEffectivePermissions

 

More Information

For more information about the File Repository API, see its documentation in the SAP Analytics Cloud REST API guide: https://help.sap.com/docs/SAP_ANALYTICS_CLOUD/14cac91febef464dbb1efce20e3f1613/132338a059c741209c910....