The purpose of the API is to integrate UNIWeb with other systems within your organization. The API provides secure read/write access to information stored by UNIWeb, and it provides a mechanism to eliminate the need to duplicate data.
The UNIWeb API provides:
- An interface that allows you to control who has access to your institution's data through our API.
- A means by which to securely read and update your institution's information.
- Rich data in simple, straightforward JSON for maximum readability and reusability.
- The choice to pre-filter the requested data, to obtain just the subset of information in which you are interested.
Learn more: Complete documentation of the UNIWeb API.
An example reference client for the Uniweb API is written in PHP and can be installed via Composer.
It is common to download the client to run local tests and use the client as a reference. Other clients can be developed in different language since all the is required is the ability to send HTTP requests.
To experiment with the API client, one can simply create a project with it by running the command
$ composer create-project proximify/uniweb-api
The advantage of creating a project like that is that the composer.json
in it already defines a CLI query
script for testing.
The API client can also be added as a dependency of another project via
$ composer require proximify/uniweb-api
In your UNIWeb instance, go to the Administration screen and select the API section.
Click on the "Create a client" button, enter a name for your API client, and save it.
Once created, look for the client in the list of clients and click on its "View" button to find out the secret that was created for the client.
Note: the permissions of the client are those of the user that created the client.
To connect to UNIWeb via its API you will need the URL of the instance, the client name, and the client secret.
The constructor of the UniwebClient class expects an array with credentials of the form
$credentials = [
"clientName" => "",
"clientSecret" => "",
"homepage" => ""
]
When running tests, the credentials can be defined in a json file named credentials.json
and place within the settings
folder. For security, settings/credentials.json
should be added to .gitignore
to avoid committing the secret by accident.
The uniweb-api
project includes a queries
folder with code representing different use cases of the UniwebClient class to perform common types of API requests.
If the project was created with composer create-project
, then the root folder will also include a www
folder with a simple script to generate a home webpage for running the sample queries. In addition, the composer.json
file defines a Composer command that can be used to run the queries from a terminal.
To run the sample queries you will need to set the API credentials in settings/credentials.json
{
"clientName": "",
"clientSecret": "",
"homepage": ""
}
The .gitignore
file of the uniweb-api project already includes the command to exclude that file from the repository. But if you use the project as a dependency of another project, make sure that the credentials.json
is ignored in it as well.
A simple way to test the client is to use the PHP built-in web server. To launch the built-in web server, change directory to the www
folder within the uniweb-api project, and start the web server there.
Note: If the project is a dependency within a parent project, you first must to go to the root folder
vendor/proximify/uniweb-api
.
$ cd www && php -S localhost:8000
While the PHP web server is running, the URL http://localhost:8000
should display the website.
Alternatively, it is possible to test the predefined queries from the command line using composer and the query
script.
$ composer query example3