Like widgets, an API (or Application Programming Interface) allows you to post data to a custom, shared, reference (individual transactions), or gate count dataset. The big difference is that an API allows you to create your own custom app or script that posts data from another source.
For example, if your security gate has an API for retrieving gate count readings, you could develop your own script that takes the data from your gate and post it to your gate count dataset in LibInsight.
As you can tell, APIs are intended for users who have some programming know-how. If you are looking for a simple way to manually record data from outside of LibInsight, consider creating widgets instead.
Creating an API
- Log into LibInsight and go to Admin > Widgets and APIs.
- Click on the Create API button.
- In the New API window, choose a supported dataset from the Select Dataset dropdown. You can create APIs for the following dataset types:
- Reference (individual transactions)
- Gate count
- Enter a Name for your API. This will help you identify it later.
- If you selected a gate count dataset, use the Select Library dropdown to choose the library to which you'll be posting data. Select All Libraries if you'd like to be able to post to all libraries using your API.
- Save your new API.
Viewing an API's code
- On the Widgets and APIs page, locate your API in the list and click on its code () button in the Actions column.
- In the API Code window, you'll find an overview of the API's data, parameters, and response data.
- Form Data: this provides you with the API's unique POST URL for receiving data.
- Form Data parameters: this lists each available field name in the dataset, along with it's required/optional status and field type. The field type will indicate the correct format for the data you're posting to the field (so you don't post text to a date field, for example).
- Return: this provides a list of the possible responses that the API will return. This will indicate whether or not your POST request was successful.
- Sending multiple data at once: if you want to post multiple records in one request, you can send up to 500 records using the unique POST URL listed here. When using this option, you will need to post an array of JSON objects, with one object per record.
- When finished, click the Close button.
Using the API
The API can be called using an HTTP POST request. For your request to be successful, please note the following:
- Only System Field and Custom Field keys can be passed
- System Field keys are optional (they can be omitted from the POST request body)
- Custom Field keys are required to be passed, but their values are optional (unless a specific field has been set as required in your dataset's settings, in which case you would have to pass a value for that field)
- You cannot pass a Custom Field key that is not listed in the API code (see above section)