API Guide v2.0

1. The Connectbeam API's are Web Service APIs based on the REST protocol.
2. The API end-point <base-url> refers to <connectbeaminstallation-url>/cbapp/restapi
   For example, if your Connectbeam installation url is http://tagging.mycompany.com, then the <base-url> is http://tagging.mycompany.com/cbapp/restapi.
3. As per the REST standard, we use HTTP methods (delete, put, post, get) to perform the actions instead of specifying the action in the query parameters (for example, …/?action=add).
4. Mapping of HTTP methods to CRUD actions
   
   

   HTTP	Method	CRUD Action Description
   POST	CREATE	Create a new resource
   GET	RETRIEVE	Retrieve a representation of the resource
   PUT	UPDATE	Update a resource
   DELETE	DELETE	Delete a resource

5. The resource Type (method name) and Connectbeam API Version are required parameters.
   For example, <base-url>?Type=Bookmark & Version=1
6. All input comes as query parameters. There is no XML input.
7. All responses (results) are in XML and in UTF8 (response mime type = text/xml;charset=utf-8).
8. The values of the parameters that you pass in should be UTF-8 encoded if they contain any special characters (like spaces) or non-latin characters.
   
   
   Note: Only the values of the parameters should be encoded and not the parameters themselves. So do not encode the entire URL. For example, to update a bookmark, you would have the URL as:
     PUT http://localhost/cbapp/restapi?Type=Bookmark& Version=1&userId=joe@company.com& bookmarkId=2&Title=<new-title>
   In the above example, you would encode only the "<new-title>" and not "Title=<new-title>" (or the entire URL).
9. The API doesn't authenticate the userid parameter that is passed to the API. It is up to the API client to do any validation/authentication of the user and pass their userid as a parameter to the API. If the userid passed doesn't exist, then we return an error.
   
   
   Note: The userid parameter should not be confused with the apiuser. Apiuser is the one who makes the API calls. The credentials for the apiuser is checked by Login API. At this time, apiuser can be any Admin user.
10. HTTP response code is set accordingly (e.g., 200, 400, etc) for all responses. If the HTTP error code >= 400, then the response should be read from error stream (as opposed to reading from input stream).
11. Hungarian notation is used for naming in the XML.
    For example, Hungarian notation to represent "alltags" is "AllTags".
12. The client authenticates initially using the Login API. If the login is successful, then we return a cookie named "connectbeam". This cookie needs to be sent with every API call.
13. Format of a typical XML response of search results in case of success:
    The HTTP Status code is set accordingly. Also where relevant, HTTP headers are set accordingly.
    

    <?xml version="1.0" encoding="UTF-8"?>
    <Response>
      <TimeStamp> 2008-03-25 05:29:30 PM GMT </TimeStamp>
      <APIVersion> 1.0 </APIVersion>
      <CurrentPage> 1 </CurrentPage>
      <TotalPages> 20 </TotalPages>
      <PageSize> 10 </PageSize>
      <Bookmarks>
        <Bookmark> … </Bookmark>
        <Bookmark> … </Bookmark>
      </Bookmarks>
    </Response>

14. Format of a typical XML response in case of failure:
    The HTTP Status code is set accordingly. Also where relevant, HTTP headers are set accordingly.
    

    <?xml version="1.0" encoding="UTF-8"?>
    <Response>
      <TimeStamp> 2008-03-25 05:29:30 PM GMT </TimeStamp>
      <APIVersion> 1.0 </APIVersion>
      <Errors>
        <Error>
          <Code> 0 </Code>
          <Message> Wrong Page Number </Message>
          <Detail> The given page number is more than the number
                   of available pages. </Detail>
        </Error>
        <Error> … </Error>
      </Errors>
    </Response>

    Note: In version 1, the code is always 0 and the detail is same as message.
    
    
15. We have standardized the XML elements across various responses. For example, the format of the <Community> element is same across various responses. So for some responses, not all values inside the <Community> element are needed. In those cases you may find the value as '0' or 'unknown' for that element.
16. An empty list is returned for empty search results.
    For example, if you are search for 'Joe' using the People Search API where 'Joe' is not present, then the XML returns an empty result.
    

    <?xml version="1.0" encoding="UTF-8"?>
    <Response>
      ...
      <Users></Users>
    </Response>

17. If the UserId parameter is used on an API call, it is always validated. Further, for an API where the UserId is optional, an error will be reported if the value for the UserId is invalid (for example, if the UserId does not exist in the system).
18. There is no pagination for tags. All tags (limited to the first 500) that match a criteria are returned in a single response.
19. The names of the query-parameters are case-sensitive i.e., BookmarkId is valid but BookMARKid is not valid.
20. In the xml response from the server, the DateWeight and TagCount attributes associated with each tag provides the information to build up a tag cloud using the APIs.
21. In all the APIs (except the Login API) where userId parameter is used, a new attribute, AuthId, is available to identify a user. In Connectbeam Spotlight, a user can be fetched by Email Id or Login Id. The AuthId parameter indicates whether the value passed for userId is an Email Id or a Login Id. Though this parameter is optional, it is highly recommended that you use it for consistency.

    	  
    PARAMETER
      AuthId: <optional> EMAIL_ADDR | LOGIN_ID
    
      Value "EMAIL_ADDR" indicates the passed userId is Email ID of the user. 
      Value "LOGIN_ID" indicates the passed userId is External ID of the user.
      Default value is "EMAIL_ADDR".

back to top