Fc12api Fc12api
Total Page:16
File Type:pdf, Size:1020Kb
FC12API FC12API 1 FirstClass 12 API 1.1 Introduction 4 1.2 The index.html (Table of Contents) 7 1.3 API Developer Tool 8 1.4 Drill Down Navigation 31 1.5 Form Creation and Field Updates 36 1.6 Moving Items 41 FirstClass 12 API FC12API - 3 Introduction This section introduces the FirstClass 12 API and the structure of the files included in the API Toolkit. An important step will be to enter the URL and port of your instance of FCWS. What is an API? An application programming interface (API) is a protocol intended to be used as an interface by software components to communicate with each other. The FirstClass Web Services server (FCWS) is a Python implementation of a web server that facilitates access to FirstClass server data and functionality. The FirstClass web client (or any other web-based client) uses HTML 5.0 to communicate with the FirstClass web server. Requests issued to the FirstClass web server are translated into the FirstClass-proprietary protocol FCP and sent to the FirstClass server for processing. The FirstClass server responses are also encapsulated in the FCP protocol, which is then processed by the FirstClass web server and subsequently sent back to the web client. The API is documented and web developers can use this API to create applications that can present secure, authenticated data within their own applications. FC12API - 4 API Toolkit File Structure The API Toolkit is four different applications that will be described further in this document. The Index.html file is the table of contents and each of the different pages share content (either images or CSS) that is stored in the images and Commonjs folders. The above diagram shows the relationships in the file structure. The files will be described in more detail shortly. Referencing Your FCWS All of the applications must point to your instance of FCWS which, in itself must be configured to have a default server. For the API Tool, you must enter your server ipaddress and the port on which fcws is listening. Note: If you want to initiate a password change you will have to have and SSL Connection 1. default server 2. port FC12API - 5 Web Services API Guide The most current API documentation can be found in your FCWS/Docs folder on your own installation. This will be updated with each server update as required so be sure to check for changes after each server upgrade. FC12API - 6 The index.html (Table of Contents) This is your start page. From here you have access to all of the applications as well as the documentation. The Start Page The index.html file at the root of the API Toolkit folder provides a link to the documentation and a brief description of what each of the four different sample solutions. You can use this page to launch the documentation and each of the different examples into a separate tab or browser window. FC12API - 7 API Developer Tool The API Developer Tool is the main application that has been created to help web developers understand the API documentation and to provide some examples on how to retrieve and parse information returned from an API call to the FirstClass server. Introduction The API Developer tool provides the most visual information on how to use the API. FC12API - 8 Required Files The API Developer tool uses the following Files • API Developer Tool/APIDeveloperTool.html (the primary html file) • API Developer Tool/API.js (the primary javascript file) • API Developer Tool/APIStyles.css (the primary css file) • Commonjs/connection.js • Commonjs/jquery-1.8.3.min.js • Commonjs/jsLibs.js • Images/brand.png • images.title-icons.png FC12API - 9 Logging In The current implementation of the API requires an authenticated login. The tool allows you to choose between a base64 sha 512 hash encrypted or a clear text password. After clicking the Login button, you will see the following: FC12API - 10 1. The URL that is sent to the server along with any POST data that accompanies the request. 2. The data that is returned from the server in its raw JSON form. 3. A sample of how a web developer may wish to parse and display the returned data. The Interface The tool has a simple interface that allows you to expand and shrink the Data Received and Information / Sample Parsed Data sections so you can better view the content. 1. Each window has a resizing corner that you can use to increase or reduce the height. 2. You can dismiss the Data Received window entirely by clicking on the collapse button. This is a toggle so clicking again will expand it back to its previous size. FC12API - 11 Options A number of different options are available once logged in. An effort has been made to provide developers with a range of examples that might prove useful if they are trying to incorporate FirstClass content within their own web applications. FC12API - 12 Session Info Session Info provides the developer with a host of information that might be useful in crafting applications that will respond differently depending on the information retrieved from this option. FC12API - 13 Desktop Containers Selecting Desktop Containers will retrieve and display all containers on the user's desktop. This starts with the general call to open the user's desktop, fetching everything that is stored on the user's home screen This includes items that are invisible FC12API - 14 to the user. To display containers only, this section filters out and displays only visible containers to the viewer. People I Follow As mentioned above, retrieving the desktop retrieves everything that is stored on the user's home screen including items that are invisible to the user. To retrieve the People I follow, the desktop is retrieved and the developer must filter the results to FC12API - 15 display only people. My Watched Items Similar to other desktop items, to retrieve My Watched Items, the desktop is retrieved and the developer must filter the results to display only the watched items. FC12API - 16 My Drafts Similar to other desktop items, to retrieve My Drafts, the desktop is retrieved and the developer must filter the results to display only the draft items. FC12API - 17 The Pulse The Pulse returns and displays the current pulse entries for the logged in user. FC12API - 18 Unread Mail Items This Unread Mail Items option will list all of the unread mail items for the currently logged in user. FC12API - 19 Today's Events Today's Events returns a list of both events and tasks that are scheduled for the current day. FC12API - 20 My Résumé My Résumé returns the user's profile résumé and presents a sample of the retrieved information. FC12API - 21 Open Container by WebID Path When you view the JSON data that is retuned you will notice a WebID for every object. You can open a container if you specify the full path to that container. For example, I notice that when I opened the Desktop container, it has a WebID of FC12API - 22 DeskTop000000000000000000000 and on that desktop is the Documents folder which has a WebID of 8000000100012250000000000220 With this option, you can specify the full path DeskTop000000000000000000000/8000000100012250000000000220 to open and retrieve the contents of that container FC12API - 23 Status Update The Status Update is an example of a POST to FirstClass that will update the user's status and post to the Pulse. This requires the completion of a field first before submission. For all POST items, you must also submit a VKEY (one of 10 vkeys retrieved FC12API - 24 from the LOGINREPLY JSON data.) Returned with the data is also a replacement vkey that must replace the one used in this query. A subsequent retrieval of the pulse will show that the entry has been submitted. Change Password Change Password is another POST example that requires the old and new password to be submitted (POSTED) to the server. A password change requires both a vkey and that the clear text password be encrypted prior to submission. Once submitted, the FC12API - 25 vkey replacement must be made. In addition, a password change is only allowed if you have an SSL certificate and the API Server Address reflects this. ie, an SSL connection is required and this example checks for 'https' in the server address. If this criteria is met, you will be presented with a field to enter your old password and anther FC12API - 26 New Conference on Desktop The New Conference option is another example of a POST that requires a name and iconID. This creates the conference on the user's desktop and displays the resulting container and icon in the Information window. As with the PULSE entry, this too FC12API - 27 requires a vkey and vkey replacement upon completion. Enter: 1. A Conference Name 2. A valid Icon ID 3. Click on Create Conference FC12API - 28 Delete by WebID To delete an item, you need both the webID of the item and the webID of the parent container. This can be found during the opening of a container as per one of the previous examples. For example, when I opened the Documents folder (webID: FC12API - 29 8000000100012250000000000220) I noticed a file called New Form 1 that has a webID: 011F7ADF0003BCE8000000001600 and these two values can be used to delete the file. As this is a POST to the server, a vkey is required. FC12API - 30 Drill Down Navigation The navigation example demonstrates opening and closing of containers and viewing the names and subjects of items within it.