Difference between revisions of "API keys"

From InsightWiki
Jump to navigation Jump to search
Line 45: Line 45:
 
'''<span style="color:#00F"><nowiki>https://insight.school.org</nowiki></span>/insightapi/ashx?apikey=<span style="color:#F00">b25a5fd2-965c-4bc8-b425-dbdc5234e6aa</span>&op=<span style="color:#0A0">Assignments</span>&misid=<span style="color:#A0A">9919</span>''' <br> <br>
 
'''<span style="color:#00F"><nowiki>https://insight.school.org</nowiki></span>/insightapi/ashx?apikey=<span style="color:#F00">b25a5fd2-965c-4bc8-b425-dbdc5234e6aa</span>&op=<span style="color:#0A0">Assignments</span>&misid=<span style="color:#A0A">9919</span>''' <br> <br>
  
<!--
+
==Error Messages==
ERROR MESSAGES
 
403.16 invalid api key
 
403.6 IP address rejected
 
403.18 invalid operation
 
403.1 Execute access is denied - role permission preclude call
 
(The above means incorrect API permission config)
 
403.13 Student id expected but none specified
 
  
Worth remembering that Insight makes PARS run a Contact History Report to get Notices.
+
The following error messages can be returned by Insight to an application attempting to use Insight's API: <br> <br>
-->
+
 
 +
'''403.16 invalid api key'''<br>
 +
''The API key used is not found in Insight'' <br> <br>
 +
'''403.6 IP address rejected''' <br>
 +
''The IP address that the request was sent from is not allowed'' <br> <br>
 +
'''403.18 invalid operation''' <br>
 +
''The operation requested by the application does not exist in Insight'' <br> <br>
 +
'''403.1 Execute access is denied - role permission preclude call''' <br>
 +
''The application is requesting to use an operation for which the API key does not have permission'' <br> <br>
 +
'''403.13 Student id expected but none specified''' <br>
 +
''An identifying number for a student is required, but has not been specified by the application'' <br> <br>
  
 
[[Category:Management]]
 
[[Category:Management]]
 
[[Category:Additional modules]]
 
[[Category:Additional modules]]
 
[[Category:Technical]]
 
[[Category:Technical]]

Revision as of 10:49, 31 May 2018

Addmod2.png Additional Module

The Insight API is an additional module in Insight. It allows data to be drawn out of Insight for whatever purpose the school may have.

As the API is an additional module of Insight, a separate charge applies. Please contact sales@tascsoftware.co.uk for further information.

Creating API keys

The API 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.

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

The school's Insight URL
The API key
The information required from the API. The list of available information is shown in the Permission field when creating the API key
The identifying number for the pupil


The final section of the URL is used to identify the pupil whose data is going to be extracted. In the example above, this section of the URL is &adno=002467. If the data being extracted is not specific to a student (such as PARSHousePoints) then this section can be omitted.

The example above uses ADNO to identify the pupil whose data is going to be extracted. MISID and UPN can be used instead. If this is the case, the URL would be written as:
https://insight.school.org/insightapi/ashx?apikey=b25a5fd2-965c-4bc8-b425-dbdc5234e6aa&op=Assignments&upn=N823432113104 or
https://insight.school.org/insightapi/ashx?apikey=b25a5fd2-965c-4bc8-b425-dbdc5234e6aa&op=Assignments&misid=9919

Error Messages

The following error messages can be returned by Insight to an application attempting to use Insight's API:

403.16 invalid api key
The API key used is not found in Insight

403.6 IP address rejected
The IP address that the request was sent from is not allowed

403.18 invalid operation
The operation requested by the application does not exist in Insight

403.1 Execute access is denied - role permission preclude call
The application is requesting to use an operation for which the API key does not have permission

403.13 Student id expected but none specified
An identifying number for a student is required, but has not been specified by the application