Difference between revisions of "API keys"

From InsightWiki
Jump to navigation Jump to search
(Created page with "{{Additional module}} The Insight API is a tool used to extract data from Insight for use in other applications. The API is an additional module in Insight. <br> <br> After t...")
 
Line 1: Line 1:
 
{{Additional module}}
 
{{Additional module}}
The Insight API is a tool used to extract data from Insight for use in other applications. The API is an additional module in Insight. <br> <br>
+
The Insight API is a tool used to extract data from Insight for use in other applications. The API is an additional module in Insight and is managed via the API keys page. Several API keys can be configured, each of which can be used to extract a certain aspect of data from Insight. <br> <br>
  
After the Insight API has been purchased, you will need to enable it via the [[service controller]]. Run the service controller on the IIS server that hosts Insight. In the window you will see a checkbox for "enable unsecured API". This needs to be ticked before the API will work. <br> <br>
+
==Creating API keys==
  
Once the API is enabled, you can view a list of the operations it is able to perform by appending '''/insightapi.aspx?op=list''' to your Insight URL. For example, if the URL to access Insight was <nowiki>https://schoolwebsite/INSIGHT</nowiki> the URL to view the API operations would be <nowiki>https://schoolwebsite/INSIGHT/insightapi?op=list</nowiki> <br> <br>
+
New API keys are created using the Add button at the top of the page. An API key has the following options:
 +
{|class="wikitable
 +
!Field!!Purpose
 +
|-
 +
|Key||This is a randomly generated string that cannot be changed
 +
|-
 +
|Description||The title given to the key
 +
|-
 +
|Role||The API key will use the chosen [[roles]] when extracting data. This may affect the data that is extracted, for example by limited the date range over which behaviour information is extracted.
 +
|-
 +
|IP address range||A start and end address can be set to create an IP address range. The API key will only function in this range. This is used to add security to the API
 +
|Permissions||The information that the key is allowed to extract
 +
|} <br>
  
This will show you a list of the valid operations. You can click on each of the operations and the browser's address bar will show you the URL that you need to use to extract the relevant data. The URL would be something like: <nowiki>https://schoolwebsite/INSIGHT/insightapi.aspx?op=behaviourpoints</nowiki> <br> <br>
+
==Using API keys==
  
However this is not complete, you also need to append a string of text that tells Insight which pupil's data you wish to retrieve. You can use one of the following below: <br> <br>
+
A URL is needed to extract data from Insight using the API module. The URL is constructed as follows: <br> <br>
  
'''&unsecuredpupilid=XXXX''' ''where you replace XXXX with the pupil's ID number from SIMS'' <br>
+
<span style="color:#00F">https://insight.school.org</span>/insightapi/ashx?apikey=<span style="color:#F00">b25a5fd2-965c-4bc8-b425-dbdc5234e6aa</span>&op=<span style="color:#0F0">Assignments</span>&adno=<span style="color:#F0F">002467</span> <br> <br>
'''&unsecuredpupilupn=YYYYYY''' ''where you replace YYYYYY with the pupil's UPN number'' <br>
 
'''&unsecuredpupiladno=ZZZZZZ''' ''where you replace ZZZZZZ with the pupil's admission number'' <br> <br>
 
  
For example, a complete URL could be: <nowiki>https://schoolwebsite/INSIGHT/insightapi.aspx?op=behaviourpoints&unsecuredpupilid=1234</nowiki> <br> <br>
+
{|class="wikitable"
 
+
|style="background-color:#00F;"||Red
You must use IPsec in conjunction with the Insight API. The URL links are not password protected and if you do not use IPsec, anybody could access sensitive information about pupils at school if they guess the correct fields. <br> <br>
+
|-
 +
|style="background-color:#00F;"||Red
 +
|-
 +
|style="background-color:#00F;"||Red
 +
|-
 +
|style="background-color:#00F;"||Red
 +
|}
  
 
[[Category:Configuration]]
 
[[Category:Configuration]]
 
[[Category:Additional modules]]
 
[[Category:Additional modules]]
 
[[Category:Technical]]
 
[[Category:Technical]]

Revision as of 11:44, 7 April 2016

Addmod2.png Additional Module

The Insight API is a tool used to extract data from Insight for use in other applications. The API is an additional module in Insight and is managed via the API keys page. Several API keys can be configured, each of which can be used to extract a certain aspect of data from Insight.

Creating API keys

New API keys are created using the Add button at the top of the page. An API key has the following options:

Field Purpose
Key This is a randomly generated string that cannot be changed
Description The title given to the key
Role The API key will use the chosen roles when extracting data. This may affect the data that is extracted, for example by limited the date range over which behaviour information is extracted.
IP address range A start and end address can be set to create an IP address range. The API key will only function in this range. This is used to add security to the API Permissions The information that the key is allowed to extract


Using API keys

A URL is needed to extract data from Insight using the API module. The URL is constructed as follows:

https://insight.school.org/insightapi/ashx?apikey=b25a5fd2-965c-4bc8-b425-dbdc5234e6aa&op=Assignments&adno=002467

style="background-color:#00F;" Red
style="background-color:#00F;" Red
style="background-color:#00F;" Red
style="background-color:#00F;" Red