Create a Batch API Key

Stage 1: Create a Batch API Key

Setup batch API keys to enable large amounts of data to be requested from iSAMS in a single hit. Batch API keys offer a high level of access control.

To setup Batch API Keys, follow the steps below:

1. In the iSAMS Control Panel Module, select the API Services Manager applet.
2. Select Manage Batch API Keys from the right hand menu.
   The Manage Batch API Keys screen is displayed:
   
3. Click Create Batch API Key.
   A popup window is displayed:
   
4. Select the Key Properties tab. An API Key code is automatically generated. Each API Key code is unique. Right click and select refresh if you want to generate a different code.

5. Complete the fields displayed:

   Field	Explanation
   API Key Name	Enter a clear and concise name for the API key. For example, the name of the third party who is using the API key.
   Description	Add a description to provide more detail on the use of the API key. This is optional.
   API Key State	Select 'Active' for the third party to start using the API key.
   API Key Mode	Select 'Development'. This ensures that any changes made to data are not saved in your iSAMS system. It is not recommended that you select 'Production' until you are ready to go live with the third party application.
   API Key Cache Expiry	Select the period of time that information requested from your iSAMS system is cached. This prevents requested data being constantly updated which could slow iSAMS down. For example, select '24 Hours' and all data requested from iSAMS using this API key is cached for 24 hours.

6. Select the Key Logging tab.

Stage 2: API Key Logging

Use the Key Logging tab to control which types of API requests are logged in iSAMS. By default all types of API request are logged. You may want to limit the options selected to prevent iSAMS being clogged with data.

To control key logging follow the steps below:

1. When creating or editing an API key select the Key Logging tab:
2. Select whether you want to use logging for this API key. Select 'Yes' to display a list of logging options.
3. Select the logging options that you want to record:
   
   • Fatal API Requests. API requests which could not be fulfilled due to a fault with iSAMS. Occasionally, iSAMS may contain bugs which need to be corrected. Contact the Help Desk if you continue to experience this.
   • Error API Requests. API requests which could not be fulfilled due to a fault with the third party's information. For example, dates of birth were not provided in a format recognised by iSAMS.
   • All API Requests. All API requests are logged; this includes successful, fatal and error API requests.
4. Select the Key SSL Settings tab.

Stage 3: API Key SSL Settings

Use the Key SSL Settings tab to encrypt data that is requested from iSAMS. This is advisable due to the personal information recorded within iSAMS.

To setup SSL settings follow the steps below:

1. When creating or editing an API key select the Key SSL Settings tab:
2. Select either:
   
   • Use Global SSL Settings. This is selected by default.
     or
   • Override Global SSL Settings. Additional fields are displayed.

3. Select whether you want to force SSL Connections for this API key.

4. Select the Key Throttling tab.

Stage 4: API Key Throttling

Use the Key Throttling tab to setup the throttling settings to be used for your selected API key. Throttling prevents iSAMS being flooded with requests from third parties.

For example, choose to limit the number of requests per hour using an API key.

To setup throttling settings follow the steps below:

1. When creating or editing an API key select the Key Throttling tab:
2. Select either:
   
   • Use Global Throttling. This is selected by default.
     or
   • Override Global Throttling.

3. Select whether you want to use throttling for this API key. Select 'Yes' to display the Throttling Service Options section.

4. Complete the fields displayed. These are explained in the table below:

   Field	Explanation
   Throttling Unit Type	Select the unit to which the number of requests is applied. For example, select 'Days' to limit the number of requests which can be fulfilled in a set number of days.
   Throttling Unit Value	Enter a unit value to which the number of requests is applied. The number that you enter here is applied to the Throttling Unit Type you have selected.
   Throttling Limit	Enter the number of requests to be applied to the Throttling Unit Type and Throttling Unit Value.

   For example, select 'Days', '1' and '5000'. This limits the number of requests using your API key to 5000 per 1 day.

5. Select the Batch Methods tab.

Stage 5: API Key Batch Methods

Use the Batch Methods tab to select the types of data a third party can access with an API key.

For example, select access to timetables which are in development.

To setup Batch Methods, follow the steps below:

1. When creating or editing an API key select the Batch Methods tab:
2. Scroll through the selections listed. Use the check boxes to select access to different areas of iSAMS.
3. Click Save & Close. The Batch API Key is listed in the Manage Batch API Keys screen.