docs/documentation/web_service_api.php

   1 <?php\r
   2 /************************************************************************/\r
   3 /* AContent                                                             */\r
   4 /************************************************************************/\r
   5 /* Copyright (c) 2010                                                   */\r
   6 /* Inclusive Design Institute                                           */\r
   7 /*                                                                      */\r
   8 /* This program is free software. You can redistribute it and/or        */\r
   9 /* modify it under the terms of the GNU General Public License          */\r
  10 /* as published by the Free Software Foundation.                        */\r
  11 /************************************************************************/\r
  12 \r
  13 define('TR_INCLUDE_PATH', '../include/');\r
  14 \r
  15 include(TR_INCLUDE_PATH.'vitals.inc.php');\r
  16 include(TR_INCLUDE_PATH.'header.inc.php');\r
  17 ?>\r
  18 <div class="output-form" style="line-height:150%">\r
  19 \r
  20 <h1>AContent Web Service API</h1>\r
  21 <p>Access AContent from remote applications through its web service API. This is version 0.1, dated Jun 2010.</p>\r
  22 <p>AContent provides a search API that allows users to send search requests to AContent. AContent returns results in REST format. AContent also has an \r
  23 <a href="<?php echo TR_BASE_HREF;?>documentation/oauth_web_server">OAuth web service API</a> for viewing, downloading, importing and \r
  24 exporting content from remote applications. </p>\r
  25 \r
  26 <h2 id="TableOfContents">Table of Contents</h2>\r
  27 \r
  28     <div id="toc">\r
  29       <ul>\r
  30         <li><a href="<?php echo TR_BASE_HREF.'documentation/web_service_api.php'; ?>#search">Search Web Service</a>\r
  31           <ul>\r
  32             <li><a href="<?php echo TR_BASE_HREF.'documentation/web_service_api.php'; ?>#request_format">Search request format</a></li>\r
  33             <li><a href="<?php echo TR_BASE_HREF.'documentation/web_service_api.php'; ?>#response_format">Search response format</a></li>\r
  34           </ul>\r
  35         </li>\r
  36         <li><a href="<?php echo TR_BASE_HREF.'documentation/web_service_api.php'; ?>#urls">URLs to view, download, import, export course</a>\r
  37           <ul>\r
  38             <li><a href="<?php echo TR_BASE_HREF.'documentation/web_service_api.php'; ?>#view">View course</a></li>\r
  39             <li><a href="<?php echo TR_BASE_HREF.'documentation/web_service_api.php'; ?>#download">Download course</a></li>\r
  40             <li><a href="<?php echo TR_BASE_HREF.'documentation/web_service_api.php'; ?>#import">Import course into AContent</a></li>\r
  41           </ul>\r
  42         </li>\r
  43       </ul>\r
  44     </div>\r
  45 \r
  46 <div id="search">\r
  47 <h2 id="request_format">Search request format</h2>\r
  48 \r
  49 <p>Below is a table of the parameters you can use to send a request to AContent to search through the repository\r
  50 by keywords. AContent returns the matching results in REST format.</p>\r
  51 \r
  52 <p>URL:<br />\r
  53 <kbd><?php echo TR_BASE_HREF; ?>search.php</kbd> <br />\r
  54 (replace with the address of your own server if you want to call a private instance of AContent)</p>\r
  55 \r
  56 <table class="data" rules="all">\r
  57 <tbody><tr>\r
  58 <th>Parameter</th><th>Description</th><th>Default value</th>\r
  59 </tr>\r
  60 \r
  61 <tr>\r
  62   <th>id</th>\r
  63   <td>The "Web Service ID" generated once successfully registering into AContent. \r
  64   This ID is a 32 characters long string. It can always be found on your "Profile" page.</td>\r
  65   <td>None, must be given.</td>\r
  66 </tr>\r
  67 \r
  68 <tr>\r
  69   <th>keywords</th>\r
  70   <td>The keywords to search for.</td>\r
  71   <td>None, must be given.</td>\r
  72 </tr>\r
  73 \r
  74 <tr>\r
  75   <th>start</th>\r
  76   <td>Start receiving from this record number</td>\r
  77   <td>0. Optional</td>\r
  78 </tr>\r
  79 \r
  80 <tr>\r
  81   <th>maxResults</th>\r
  82   <td>Number of results to return.</td>\r
  83   <td>10. Optional</td>\r
  84 </tr>\r
  85 </tbody></table>\r
  86 <br />\r
  87 \r
  88 <span style="font-weight: bold">Sample search request</span>\r
  89 <p><?php echo TR_BASE_HREF; ?>search.php?id=fb170575596b4a5b52a87da39ef59586&keywords=atutor+all&start=10&maxResults=25</p>\r
  90 <p>Goal: Search for keywords "atutor all". Return search results from record #10 and maximum 25 results returned.</p>\r
  91 \r
  92 <h2 id="response_format">Search response format</h2><br/>\r
  93 <span style="font-weight:bold">Success REST Response</span>\r
  94 <p>A REST success response for the validation of a document (invalid) will look like this:</p>\r
  95 \r
  96 <pre style="background-color:#F7F3ED;"> \r
  97 &lt;?xml version=&quot;1.0&quot; encoding=&quot;ISO-8859-1&quot;?&gt;\r
  98 &lt;resultset&gt;\r
  99   &lt;summary&gt;\r
 100     &lt;numOfTotalResults&gt;11&lt;/numOfTotalResults&gt;\r
 101 \r
 102     &lt;numOfResults&gt;3&lt;/numOfResults&gt;\r
 103     &lt;lastResultNumber&gt;3&lt;/lastResultNumber&gt;\r
 104   &lt;/summary&gt;\r
 105 \r
 106   &lt;results&gt;\r
 107 \r
 108     &lt;result&gt;\r
 109       &lt;courseID&gt;3&lt;/courseID&gt;\r
 110       &lt;title&gt;another import - welcome to atutor11sdf&lt;/title&gt;\r
 111       &lt;description&gt;&lt;/description&gt;\r
 112 \r
 113       &lt;creationDate&gt;2010-01-13 13:51:53&lt;/creationDate&gt;\r
 114     &lt;/result&gt; \r
 115     &lt;result&gt;\r
 116 \r
 117       &lt;courseID&gt;4&lt;/courseID&gt;\r
 118       &lt;title&gt;an introduction to data and information&lt;/title&gt;\r
 119 \r
 120       &lt;description&gt;this work is licensed under a creative commons attribution-noncommercial-sharealike 2.0 http://creativecommons.org/licenses/by-nc-sa/2.0/uk/&lt;/description&gt;\r
 121       &lt;creationDate&gt;2010-01-13 13:52:07&lt;/creationDate&gt;\r
 122     &lt;/result&gt; \r
 123     &lt;result&gt;\r
 124       &lt;courseID&gt;7&lt;/courseID&gt;\r
 125 \r
 126       &lt;title&gt;atutor howto 1.4.3&lt;/title&gt;\r
 127       &lt;description&gt;documentation for students, instructors, and administrators.&lt;/description&gt;\r
 128       &lt;creationDate&gt;2010-02-02 12:07:43&lt;/creationDate&gt;\r
 129     &lt;/result&gt; \r
 130 \r
 131   &lt;/results&gt;\r
 132 \r
 133 &lt;/resultset&gt;\r
 134 </pre>\r
 135 \r
 136 <br />\r
 137 <span style="font-weight:bold">Error Response</span>\r
 138 \r
 139 <pre style="background-color:#F7F3ED;"> \r
 140 &lt;?xml version=&quot;1.0&quot; encoding=&quot;ISO-8859-1&quot;?&gt;\r
 141 &lt;errors&gt;\r
 142   &lt;totalCount&gt;1&lt;/totalCount&gt;\r
 143   &lt;error code=&quot;401&quot;&gt;\r
 144 \r
 145     &lt;message&gt;Empty keywords&lt;/message&gt;\r
 146   &lt;/error&gt;\r
 147 \r
 148 &lt;/errors&gt;\r
 149 </pre>\r
 150 \r
 151 </div>\r
 152 \r
 153 <div id="urls">\r
 154 <h2 id="view">View course URL</h2>\r
 155 <kbd><?php echo TR_BASE_HREF;?>home/course/index.php?_course_id=10</kbd><br />\r
 156 <p>_course_id is the "courseID" element returned in the REST search result</p>\r
 157 <p>This URL leads to the first content page of the lesson.</p>\r
 158 \r
 159 <h2 id="download">Download course URL</h2>\r
 160 <kbd><?php echo TR_BASE_HREF;?>home/imscc/ims_export.php?course_id=10</kbd><br />\r
 161 <p>course_id is the "courseID" element returned in the REST search result</p>\r
 162 <p>This URL returns a zipped common cartridge of the lesson.</p>\r
 163 </div>\r
 164 \r
 165 <h2 id="import">Import common cartridge or content package into AContent</h2>\r
 166 <p>An AContent user ID with author privilege is required for this action. If you\r
 167 don't have an AContent ID yet, <a href="<?php echo TR_BASE_HREF;?>register.php">register</a>.</p> \r
 168 \r
 169 <p>After an AContent user ID has been created, the first step is to go through the\r
 170 <a href="<?php echo TR_BASE_HREF;?>documentation/oauth_server_api.php">\r
 171 OAuth authentication process</a> to get an OAuth access token. The \r
 172 authentication process prompts users to login with an AContent user ID, after which an\r
 173 access token is returned. This access \r
 174 token must be sent along with the import request as a user privilege check. The access\r
 175 token can be used repeatedly until its expiration. After the\r
 176 user is confirmed as an valid author, the common cartridge or content package is retrieved\r
 177 from the request "url" parameter and imported as a new AContent lesson. The \r
 178 ID of the newly-imported lesson is returned at success.</p>\r
 179 \r
 180 <kbd><?php echo TR_BASE_HREF;?>home/ims/ims_import.php?oauth_token=xxx&url=xxx</kbd><br />\r
 181 \r
 182 <p>oauth_token is the valid access token returned by an AContent OAuth server.<br />\r
 183 url points to a zip file of a common cartridge or a content package.<br />\r
 184 Refer to <a href="<?php echo TR_BASE_HREF;?>documentation/oauth_server_api.php#import">\r
 185 Importing Common Cartridges or Content Packages into AContent via OAuth</a> for detailed \r
 186 request parameters and success/fail responses.</p>\r
 187 \r
 188 </div>\r
 189 <?php include(TR_INCLUDE_PATH.'footer.inc.php'); ?>\r