Difference between revisions of "API keys"

From InsightWiki
Jump to navigation Jump to search
Line 1: Line 1:
{{Additional_module}}
+
The Insight API is an additional module in Insight. It allows data to be drawn out of Insight to be used by other applications. There is also a free, limited version of the API which is automatically available if Insight is linked to PARS. <br> <br>
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. <br> <br>
 
  
As the API is an additional module of Insight, a separate charge applies. Please contact <span class="plainlinks">[mailto:sales@tascsoftware.co.uk sales@tascsoftware.co.uk]</span> for further information. <br> <br>
+
As the full version of the API is an additional module of Insight, a separate charge applies. Please contact <span class="plainlinks">[mailto:sales@tascsoftware.co.uk sales@tascsoftware.co.uk]</span> for further information. <br> <br>
  
==Creating API keys==
+
=Creating an API Key=
  
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. <br> <br>
+
The API page is accessed via: <br>
 +
'''Manage > API Keys''' <br> <br>
 +
 
 +
The following Role Options are required to configure Insight APIs: <br>
 +
''Manage > API Keys'' (On) <br> <br>
  
 
New API keys are created using the Add button at the top of the page. An API key has the following options:
 
New API keys are created using the Add button at the top of the page. An API key has the following options:
Line 12: Line 15:
 
!Field!!Purpose
 
!Field!!Purpose
 
|-
 
|-
|Key||This is a randomly generated string that cannot be changed
+
|Key||This is a randomly generated string that cannot be changed.
 
|-
 
|-
|Description||The title given to the key. This is only for internal Insight use, to help users organise the API keys
+
|Description||The title given to the key. This is only for internal Insight use, to help users organise the API keys.
 
|-
 
|-
|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.
+
|Role||The API key will use the chosen [[Roles|role]] when extracting data. This may affect the data that is extracted, for example by limiting 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
+
|IP address range||A start and end address can be set to create an IP address range. Insight will only return data to an application if the request is made from an IP address within this range. The default values allow data requests from any IP address (note that API requests always require a 32 character key, regardless of the IP settings).
 
|-
 
|-
|Permissions||The information that the key is allowed to extract
+
|Permissions||The information that the key is allowed to extract from Insight.
 
|} <br>
 
|} <br>
  
==Using API keys==
+
==Settings for PARS API==
  
A URL is needed to extract data from Insight using the API module. The URL is constructed as follows: <br> <br>
+
An API key is required for some functionality between Insight and PARS. These functions are: <br>
 +
* Allowing students to upload attachments in Insight for homework assignments created in PARS
 +
* Triggering a push notification in the Insight app when a message is sent from the External Contact page in PARS <br> <br>
 +
 
 +
Only one API Key can be used by PARS. The '''Description''' given and the '''Role''' used for the API Key have no effect.
 +
 
 +
If you want to limit the IP addresses that the Insight API will reply to then you must create an internal URL for Insight, which will be used by PARS. In this case the API requests will either be sent from 127.0.0.1 (if the PARS and Insight websites share an IIS server) or otherwise the IP address of the IIS server hosting PARS. <br> <br>
 +
 
 +
The '''Permissions''' that can be used are: <br>
 +
'''Push''' - this allows PARS to trigger push notifications in the Insight app <br>
 +
'''Evidence''' - this allows PARS to receive assignment uploads from Insight <br> <br>
 +
 
 +
The following preferences must be used to enable these features: <br>
 +
''Manage > Preferences > PARS > Collect Assignments from PARS'' - this must be On for Insight to display assignments from PARS <br>
 +
''Manage > Preferences > PARS > Include PARS communications in notices'' - this must be On for Insight users to see messages sent from PARS and to receive push notifications when such messages are sent <br> <br>
 +
 
 +
PARS must also be given the URL and API Key for Insight. These details are entered into PARS via: <br>
 +
'''Main menu > System management > Preferences > Personal''' <br> <br>
 +
 
 +
=Using an API Key with other applications=
 +
 
 +
Once you have created the appropriate API Key in Insight, you need to create a URL for your other application to use to request data from Insight. The URL is constructed as follows: <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>&adno=<span style="color:#A0A">002467</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>&adno=<span style="color:#A0A">002467</span>''' <br> <br>
Line 51: Line 75:
  
 
'''403.16 invalid api key'''<br>
 
'''403.16 invalid api key'''<br>
''The API key used is not found in Insight'' <br> <br>
+
''The <span style="color:#F00">API key</span> is incorrect'' <br> <br>
 
'''403.6 IP address rejected''' <br>
 
'''403.6 IP address rejected''' <br>
''The IP address that the request was sent from is not allowed'' <br> <br>
+
''The IP address that the request was sent from is forbidden'' <br> <br>
 
'''403.18 invalid operation''' <br>
 
'''403.18 invalid operation''' <br>
''The operation requested by the application does not exist in Insight'' <br> <br>
+
''The <span style="color:#0A0>operation</span> requested by the application is incorrect'' <br> <br>
 
'''403.1 Execute access is denied - role permission preclude call''' <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>
+
''The application is requesting to use an <span style="color:#0A0>operation</span> for which the API key does not have <span style="color:#0A0>permission</span>'' <br> <br>
 
'''403.13 Student id expected but none specified''' <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>
+
''An <span style="color:#A0A>identifying number</span> for a student is required, but has not been specified by the application'' <br> <br>
 
 
[[Category:Management]]
 
[[Category:Additional modules]]
 
[[Category:Technical]]
 

Revision as of 16:02, 20 September 2018

The Insight API is an additional module in Insight. It allows data to be drawn out of Insight to be used by other applications. There is also a free, limited version of the API which is automatically available if Insight is linked to PARS.

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

Creating an API Key

The API page is accessed via:
Manage > API Keys

The following Role Options are required to configure Insight APIs:
Manage > API Keys (On)

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. This is only for internal Insight use, to help users organise the API keys.
Role The API key will use the chosen role when extracting data. This may affect the data that is extracted, for example by limiting 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. Insight will only return data to an application if the request is made from an IP address within this range. The default values allow data requests from any IP address (note that API requests always require a 32 character key, regardless of the IP settings).
Permissions The information that the key is allowed to extract from Insight.


Settings for PARS API

An API key is required for some functionality between Insight and PARS. These functions are:

  • Allowing students to upload attachments in Insight for homework assignments created in PARS
  • Triggering a push notification in the Insight app when a message is sent from the External Contact page in PARS

Only one API Key can be used by PARS. The Description given and the Role used for the API Key have no effect.

If you want to limit the IP addresses that the Insight API will reply to then you must create an internal URL for Insight, which will be used by PARS. In this case the API requests will either be sent from 127.0.0.1 (if the PARS and Insight websites share an IIS server) or otherwise the IP address of the IIS server hosting PARS.

The Permissions that can be used are:
Push - this allows PARS to trigger push notifications in the Insight app
Evidence - this allows PARS to receive assignment uploads from Insight

The following preferences must be used to enable these features:
Manage > Preferences > PARS > Collect Assignments from PARS - this must be On for Insight to display assignments from PARS
Manage > Preferences > PARS > Include PARS communications in notices - this must be On for Insight users to see messages sent from PARS and to receive push notifications when such messages are sent

PARS must also be given the URL and API Key for Insight. These details are entered into PARS via:
Main menu > System management > Preferences > Personal

Using an API Key with other applications

Once you have created the appropriate API Key in Insight, you need to create a URL for your other application to use to request data from Insight. 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 is incorrect

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

403.18 invalid operation
The operation requested by the application is incorrect

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