Retrieving the Files service document
Added by IBM contributorIBM | Edited by IBM contributorElizabeth Bowling on November 5, 2015
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

The first step you must perform if you plan to update resources made available through the Atom APIs is to retrieve the service document for the application.

The Files service document defines work spaces for libraries, files, and collections. Each workspace has a set of collections that correspond to views in the product user interface. For example, the Files workspace has the My Files, Shared with me, and Shared by me collections. The collection addresses provides a reference to the corresponding feeds.

Authentication

This method does not require authentication to retrieve public resources. If authentication is provided, the user must have 'View' access to the service endpoint.

Service Document Details

The Atom Publishing Protocol Service Document is the container for service information associated with one or more Workspaces. A Workspace is a server-defined group of Collections of resources available for editing. The Service Document also contains elements identifying product version and supported operations.

Collection Types

Each collection in the service document must have a type to deterministically identify the collection. The type of the collection is specified by a category child element with a constant term as seen in the example below. This is introduced as the collection title should be localized.

<collection href="http://example.com:9080/files/form/api/libraries/feed">

   <category scheme="http://www.ibm.com/xmlns/prod/sn/collection" term="libraries"/>

   <title xmlns="http://www.w3.org/2005/Atom" type="text">Libraries Feed</title>

   <accept></accept>

</collection>

Term Description
libraries This collection enumerates the set of libraries managed by this service
recentUpdates This collection enumerates a set of recent updates to content in this service
myDocuments This collection enumerates a set of document resources owned by the authenticated user
sharedWithMe This collection enumerates a set of document resources shared with the authenticated user
sharedByMe This collection enumerates a set of document resources shared by the authenticated user
publicCollections This collection enumerates a set of public collections

A service provider must provide at minimum a single collection of type libraries . Additional collection types can be provided as appropriate for the behavior exposed by the service provider.

The following represents a minimal service document:

<service xmlns="http://www.w3.org/2007/app">

   <workspace>

      <title xmlns="http://www.w3.org/2005/Atom" type="text">Libraries</title>

      <collection href="http://pdm60.rtp.raleigh.ibm.com:9080/files/form/api/libraries/feed">

         <category scheme="http://www.ibm.com/xmlns/prod/sn/collection" term="libraries"/>

         <title xmlns="http://www.w3.org/2005/Atom" type="text">Libraries Feed</title>

         <accept></accept>

      </collection>

   </workspace>

</service>

Version Information and Supported Operations

Information about the current product version and a list of supported operations is added to this document in order to allow 3rd parties to more successfully use the API and be more easily flexible if some servers do not support all operations.

Version Information
Version Information will be provided by a element that is used in other feeds. It will be modifiedt o include an API version number.

Example:

uri="http://www.ibm.com/xmlns/prod/sn">Lotus Connections - Files</generator> 

Supported Operations
This section lists the operations that this server supports. Currently, this is not an exhaustive list of all operations that the server could support.

This is the complete list of possible operations that could be defined in this section of the service document. Some of the operations will require additional information such as a URI template to indicate the proper way to call the service which would include parameters and return values. Others simply indicate whether a particular feature is supported and therefore does not have any additional information.

Operation Id Description
recommend.users Indicates if the server supports recommendations and if so the service definition for retrieving the list of recommending users.
people.search Indicates if the server supports people search and if so the service definition for performing the search.
recyclebin Indicates if the server supports the recycle bin concept and if so the service definition for retrieving the contents of the recycle bin.
shareby.emailaddress Indicates if the server supports sharing by email address.
restrict.download.info Indicates if the list of users who have download a document and the version they have download is available. Existence of this means that only the Owner of the document and those assigned as Editor can see this information
restrict.shares.view Indicates if the list of users that have been shared with is available. Existence of this means that only the Owner of the document and those assigned as Editor can see this information
multiPhaseFileUpload If present, multi-phase upload API is supported. It need configuration of mod_ibm_upload.

subCollection

If present, nested folder API is supported.

Example This is an example of what each operation would look like if it were supported. The service definitions are for HTTP GET methods only in this version of the document. The syntax aligns with concepts from CMIS for exposing URI templates for extended capability.

<operations>

    <operation id="recommend.users">

        <uritemplate> <template>http://localhost:9080/files/basic/api/library/{library-id}/document/{document-id}/recommendedby/feed?{-join|&|page,pageSize,sI,identifiers} <mediatypes> <mediatype>application/json</mediatype> <mediatype>application/xml</mediatype> </mediatypes> </uritemplate>

    </operation>

    <operation id="people.search">

        <uritemplate>

            <template>http://localhost:9080/files/basic/api/people/feed?{-join|&|self,userid,sK,searchString,searchType,page,pageSize,sI,includeExtendedAttributes,format}</template>

            <mediatypes>

                <mediatype>application/json</mediatype>

            </mediatypes>

        </uritemplate>

    </operation>

    <operation id="recyclebin">

        <uritemplate>

            <template>http://localhost:9080/files/basic/api/library/{library-id}/view/recyclebin/feed?{-join|&|sK,page,pageSize,sI,sO}</template>

            <mediatypes>

                <mediatype>application/atom+xml</mediatype>

            </mediatypes>

        </uritemplate>

    </operation>

    <operation id="multiPhaseFileUpload"/>

    <snx:operation id="subCollection">

         <snx:uritemplate>

            <snx:template>https://filesvm004.cn.ibm.com:9443/files/basic/api/collection/{collection-id}/feed</snx:template>

            <snx:mediatypes>

               <snx:mediatype>application/atom+xml</snx:mediatype>

            </snx:mediatypes>

         </snx:uritemplate>

      </snx:operation>

    <operation id="shareby.emailaddress"/>

    <operation id="restrict.download.info"/>

    <operation id="restrict.shares.view"/>

</operations>

Input
Method URI Description
GET /files/{auth}/api/introspection Retrieves the Files service document for the user whose credentials are used to authenticate the request.
Name Type Optional Description
auth
enumerated No The authorization protocol being used by your application to access Connections Cloud.
Authorized values:
  • basic
  • oauth
Name Type Optional Description
Authorization
enumerated No The authentication mechanism selected by your application to access the API.
Basic is the Base64 encoding of the IBM Connections Cloud username and password: Base64(username:password). For example, Base64(twatson@us.ibm.com:password).
Bearer is the oauth 2.0 access token that is generated when the user grants your application access to IBM Connections Cloud services.
See the reference topic "OAuth 2.0 APIs for web server flow" for more information.
Authorized values:
  • bearer
  • basic
Output
Content Type: application/atom+xml
Code Description
200
OK. Indicates that the request was received successfully.
401
Unauthorized. Returned when no authenticated user or no userid, email, or key parameter are provided on the request.
Examples
To retrieve the service document for the Files application:
> GET /files/basic/api/introspection HTTP/1.1

> Authorization: Basic xxx

> Host: enterprise.example.com:9087

> Accept: */*


Response returned by the server
HTTP/1.1 200 OK

X-LConn-Auth: true

Content-Type: application/atom+xml; charset=UTF-8

Last-Modified: Wed, 15 Jul 2009 21:18:13 GMT

Content-Language: en-US

Set-Cookie: JSESSIONID=xxx

Transfer-Encoding: chunked

Date: Wed, 15 Jul 2009 21:18:12 GMT

Server: WebSphere Application Server/6.1

Expires: Thu, 01 Dec 1994 16:00:00 GMT

Cache-Control: public, max-age=30, no-cache=set-cookie


<app:service>

  <generator version="3.0.0.0" uri="http://www.ibm.com/xmlns/prod/sn" apiVersion="1.0.1">

    IBM Connections - Files

  </generator>

  <app:workspace>

    <title type="text">Libraries</title>

    <app:collection href="https://enterprise.example.com/files/basic/api/libraries/feed">

      <category term="libraries" scheme="http://www.ibm.com/xmlns/prod/sn/collection"/>

      <title type="text">Libraries Feed</title>

      <app:accept/>

    </app:collection>

  </app:workspace>

  <app:workspace>

    <title type="text">Files</title>

    <app:collection 

     href="https://enterprise.example.com/files/basic/api/library/1b66a268-c615-49ab-9fdf-1ba12a13b9e2/feed">

      <category term="files" scheme="http://www.ibm.com/xmlns/prod/sn/collection"/>

      <title type="text">My Files</title>

      <app:accept>*/*</app:accept>

      <app:categories fixed="yes">

        <category term="document" scheme="tag:ibm.com,2006:td/type" label="document"/>

        <category term="draft" scheme="tag:ibm.com,2006:td/type" label="draft"/>

        <category term="page" scheme="tag:ibm.com,2006:td/type" label="page"/>

      </app:categories>

    </app:collection>

    <app:collection href="https://enterprise.example.com/files/basic/api/myshares/feed?direction=inbound">

      <category term="files" scheme="http://www.ibm.com/xmlns/prod/sn/collection"/>

      <title type="text">Shared with me</title>

      <app:accept/>

    </app:collection>

    <app:collection href="https://enterprise.example.com/files/basic/api/myshares/feed?direction=outbound">

      <category term="files" scheme="http://www.ibm.com/xmlns/prod/sn/collection"/>

      <title type="text">Shared by me</title>

      <app:accept/>

    </app:collection>

    <app:collection href="https://enterprise.example.com/files/basic/api/documents/feed?visibility=public">

      <category term="files" scheme="http://www.ibm.com/xmlns/prod/sn/collection"/>

      <title type="text">Documents Feed</title>

      <app:accept/>

    </app:collection>

    <app:collection 

     href="https://enterprise.example.com/files/basic/api/library/1b66a268-c615-49ab-9fdf-1ba12a13b9e2/view/

      recyclebin/feed">

      <category term="files" scheme="http://www.ibm.com/xmlns/prod/sn/collection"/>

      <title type="text">Removed Files</title>

      <app:accept/>

      <app:categories fixed="yes">

        <category term="document" scheme="tag:ibm.com,2006:td/type" label="document"/>

      </app:categories>

    </app:collection>

  </app:workspace>

  <app:workspace>

    <title type="text">Folders</title>

    <app:collection 

     href="https://enterprise.example.com/files/basic/api/collections/feed?creator=

      4fda6cc0-0101-102e-88dd-f78755f7e0ed">

      <category term="files" scheme="http://www.ibm.com/xmlns/prod/sn/collection"/>

      <title type="text">My Folders</title>

      <app:accept>application/atom+xml;type=entry;charset=UTF-8</app:accept>

      <app:categories fixed="yes">

        <category term="document" scheme="tag:ibm.com,2006:td/type" label="document"/>

      </app:categories>

    </app:collection>

    <app:collection href="https://enterprise.example.com/files/basic/api/collections/feed?visibility=private">

      <category term="files" scheme="http://www.ibm.com/xmlns/prod/sn/collection"/>

      <title type="text">Shared with me</title>

      <app:accept>application/atom+xml;type=entry;charset=UTF-8</app:accept>

      <app:categories fixed="yes">

        <category term="document" scheme="tag:ibm.com,2006:td/type" label="document"/>

      </app:categories>

    </app:collection>

    <app:collection href="https://enterprise.example.com/files/basic/api/collections/feed?visibility=public">

      <category term="files" scheme="http://www.ibm.com/xmlns/prod/sn/collection"/>

      <title type="text">Public Folders</title>

      <app:accept>application/atom+xml;type=entry;charset=UTF-8</app:accept>

      <app:categories fixed="yes">

        <category term="document" scheme="tag:ibm.com,2006:td/type" label="document"/>

      </app:categories>

    </app:collection>

  </app:workspace>

  <app:workspace>

    <title type="text">Recycle Bin</title>

    <app:collection 

     href="https://enterprise.example.com/files/basic/api/library/1b66a268-c615-49ab-9fdf-1ba12a13b9e2/view/

      recyclebin/feed">

      <category term="files" scheme="http://www.ibm.com/xmlns/prod/sn/collection"/>

      <title type="text">Removed Files</title>

      <app:accept/>

      <app:categories fixed="yes">

        <category term="document" scheme="tag:ibm.com,2006:td/type" label="document"/>

      </app:categories>

    </app:collection>

  </app:workspace>

</app:service>
GET /basic/api/introspection HTTP/1.1

Host: example.com

User-Agent: Thingio/1.0

Response returned by the server
<?xml version="1.0" encoding="UTF-8"?>
<service xmlns="http://www.w3.org/2007/app">
    <generator version="2.5.1.0" apiVersion="1.0.1" uri="http://www.ibm.com/xmlns/prod/sn">Lotus Connections - Files</generator>
    <operations>
        <operation id="recommend.users">
            <uritemplate> <template>http://localhost:9080/files/basic/api/library/{library-id}/document/{document-id}/recommendedby/feed?{-join|&|page,pageSize,sI,identifiers} <mediatypes> <mediatype>application/json</mediatype> <mediatype>application/xml</mediatype> </mediatypes> </uritemplate>
        </operation>
        <operation id="people.search">
            <uritemplate>
                <template>http://localhost:9080/files/basic/api/people/feed?{-join|&|self,userid,sK,searchString,searchType,page,pageSize,sI,includeExtendedAttributes,format}</template>
                <mediatypes>
                    <mediatype>application/json</mediatype>
                </mediatypes>
            </uritemplate>
        </operation>
    </operations>
    <workspace>
        <title xmlns="http://www.w3.org/2005/Atom" type="text"> Libraries </title>
        <collection href="http://example.com:9080/files/basic/api/libraries/feed">
            <title xmlns="http://www.w3.org/2005/Atom" type="text"> Libraries Feed </title>
            <accept></accept>
        </collection>
    </workspace>
    <workspace>
        <title xmlns="http://www.w3.org/2005/Atom" type="text"> Files </title>
        <collection href="http://example.com:9080/files/basic/api/library/6c06430f-c73c-4915-8cdb-78134c9d77cb/feed">
            <title xmlns="http://www.w3.org/2005/Atom" type="text"> My Files </title>
            <accept>*/*</accept>
            <categories fixed="yes">
                <category xmlns="http://www.w3.org/2005/Atom" term="document" scheme="tag:ibm.com,2006:td/type" label="document"> </category>
                <category xmlns="http://www.w3.org/2005/Atom" term="draft" scheme="tag:ibm.com,2006:td/type" label="draft"> </category>
                <category xmlns="http://www.w3.org/2005/Atom" term="page" scheme="tag:ibm.com,2006:td/type" label="page"> </category>
            </categories>
        </collection>
        <collection href="http://example.com:9080/files/basic/api/myshares/feed?direction=inbound">
            <title xmlns="http://www.w3.org/2005/Atom" type="text"> Shared with me </title>
            <accept></accept>
        </collection>
        <collection href="http://example.com:9080/files/basic/api/myshares/feed?direction=outbound">
            <title xmlns="http://www.w3.org/2005/Atom" type="text"> Shared by me </title>
            <accept></accept>
        </collection>
        <collection href="http://example.com:9080/files/basic/api/documents/feed?visibility=public">
            <title xmlns="http://www.w3.org/2005/Atom" type="text"> Documents Feed </title>
            <accept></accept>
        </collection>
    </workspace>
    <workspace>
        <title xmlns="http://www.w3.org/2005/Atom" type="text"> Collections </title>
        <collection href="http://example.com:9080/files/basic/api/collections/feed?creator=mshani">
            <title xmlns="http://www.w3.org/2005/Atom" type="text"> My Collections </title>
            <accept> application/atom+xml;type=entry;charset=UTF-8 </accept>
            <categories fixed="yes">
                <category xmlns="http://www.w3.org/2005/Atom" term="document" scheme="tag:ibm.com,2006:td/type" label="document"> </category>
                <category xmlns="http://www.w3.org/2005/Atom" term="page" scheme="tag:ibm.com,2006:td/type" label="page"> </category>
            </categories>
        </collection>
        <collection href="http://example.com:9080/files/basic/api/collections/feed?visibility=private">
            <title xmlns="http://www.w3.org/2005/Atom" type="text"> Shared with me </title>
            <accept> application/atom+xml;type=entry;charset=UTF-8 </accept>
            <categories fixed="yes">
                <category xmlns="http://www.w3.org/2005/Atom" term="document" scheme="tag:ibm.com,2006:td/type" label="document"> </category>
                <category xmlns="http://www.w3.org/2005/Atom" term="page" scheme="tag:ibm.com,2006:td/type" label="page"> </category>
            </categories>
        </collection>
        <collection href="http://example.com:9080/files/basic/api/collections/feed?visibility=public">
            <title xmlns="http://www.w3.org/2005/Atom" type="text"> Public Collections </title>
            <accept> application/atom+xml;type=entry;charset=UTF-8 </accept>
            <categories fixed="yes">
                <category xmlns="http://www.w3.org/2005/Atom" term="document" scheme="tag:ibm.com,2006:td/type" label="document"> </category>
                <category xmlns="http://www.w3.org/2005/Atom" term="page" scheme="tag:ibm.com,2006:td/type" label="page"> </category>
            </categories>
        </collection>
    </workspace>
</service>