====== Installing and Configuring Koha's REST Plugin ======

// Thanks to Mariyapillai Jayakananthan and Mohan Pradhan for developing this documentation. //

** Prerequisite **

These instructions assume that you have already installed Koha version 22.05 in a Debian-based Linux environment. Later versions of Koha may look different from the provided screen shots, and different operating systems may have minor differences in some commands.

The example assumes that the Koha ILS is installed on one server and VuFind will be installed on another server. However, this process should also work with both systems installed on one server.

===== Configuration at the Koha side =====

The RestApi plugin is used for accessing real-time data from Koha.

The following steps will be followed to configure the plugin at the Koha side.

==== Configure koha-conf.xml ====

1. Edit the koha-conf.xml file. It is located in the path ''/etc/koha/sites/<instance name>''.

In our case, the instance name is pasantha. In your case, it may be different.

<code bash>
root@debian:/etc/koha/sites/pasantha# nano /etc/koha/sites/pasantha/koha-conf.xml
</code>

After opening the koha-conf.xml file, change the line:

<code bash>
<enable_plugins>0</enable_plugins>
</code>

to

<code bash>
<enable_plugins>1</enable_plugins>
</code>

Save the file after making this change and run the command: 

<code bash>
sudo service apache2 restart
</code>

2. Download the most up-to-date .kpz plugin file from https://github.com/NatLibFi/koha-plugin-rest-di/releases.

3. In the Koha staff interface, go to: **Home -> Koha administration -> Global system preferences -> Web services** and find the REST API section. By default, it is set to 'Disable.' 

Set each dropdown (RESTBasicAuth, RESTOauth2ClientCredentials, RESTPublicAnonymousRequests and RESTPublicAPI) to 'Enable' and then click the **Save all Web service preferences** button, as shown below: 

{{ :configuration:ils:examples:screenshot3.png |}}

==== Upload the Plugin ====

Go to **Home -> Administration**  and click **Manage Plugins**. The output will be as follows:

{{ :configuration:ils:examples:screenshot4.png |}}

Click the **Upload plugin** button as shown above. 

You will then be prompted to select a file:

{{ :configuration:ils:examples:screenshot5.png |}}

Choose the file you downloaded earlier (the filename will be something similar to ''koha-plugin-rest-di-22.05.06.kpz''), and click the **Upload** button.

When you view the Plugins list, you will see that the REST API plugin is set as DISABLED. Go to **Actions** at the far right and select **Enable**, as shown below.

{{ :configuration:ils:examples:screenshot6.png |}}

The plugin will now be ENABLED, as shown here:

{{ :configuration:ils:examples:screenshot7.png |}}

If you don’t have the latest version of Koha installed, then the warning message message below will appear on your screen:

{{ :configuration:ils:examples:screenshot8.png |}}

If you have the most recent version, you will not see that message.

==== Configure Plack  ====

Plack can increase the performance of Koha. Plack is included with Koha by default, but in some cases it may need to be enabled. Check your **About Koha** page to see if it’s running or not.  

To enable Plack, enter the following commands, replacing "libraryname" with the appropriate name for your own Koha instance:

<code bash>
sudo a2enmod headers proxy_http
sudo koha-plack --enable libraryname
sudo koha-plack --start libraryname
sudo systemctl restart apache2
</code>

Then check your **About Koha** page. You should see ''PSGI: Plack (deployment)'' under **Server Information** if Plack is running and configured correctly.

==== Configure the EnvAuthorisation setting ====

Add the following line as shown below in ''/etc/apache2/sites-available/<instance.conf>'' (where "instance.conf" is the Apache configuration filename for your Koha site): 

<code bash>
SetEnvIf Authorization .+ HTTP_AUTHORIZATION=$0
</code>

{{ :configuration:ils:examples:screenshot9.png |}}

Save your change and run the command 

<code bash>
sudo service apache2 restart
</code>

==== Create a Client ID and Secret Key from the Patrons area ====

Go to: **Home -> Patrons** and select a patron. We will use patron Manu Pasantha as an example. 

Go to **More -> Set Permission** and grant **Access to all library functions** to this user. 

{{ :configuration:ils:examples:screenshot10.png |}}

Go to **More -> Manage API keys**. 

{{ :configuration:ils:examples:screenshot11.png |}}

{{ :configuration:ils:examples:screenshot12.png |}}

Click the link to **Generate a new client id/secret pair**. Under Description, enter "vufind" as illustrated below.

{{ :configuration:ils:examples:screenshot13.png |}}

Once a value such as vufind is entered and saved, the system will display a Client ID and Secret key for the patron, as shown below: 

{{ :configuration:ils:examples:screenshot14.png |}}

Note the Client ID and Secret key; you will need these later when [[configuration:ils:examples:koharest_driver|configuring the KohaRest ILS driver]].

==== Verify whether the API is working ====

Go to 

<code bash>
http://[staff-or-opac-ip-or-hostname]/api/v1/.html 
</code>

If successful, you will see the following heading among the others:

{{ :configuration:ils:examples:screenshot15.png |}}

If this heading is not displayed, go to **Home -> Koha administration-> Global system preferences-> Web services**. 

Set the **RESTOAuth2ClientCredentials** option to "Enabled." 

If it is already enabled, disable and save it. Then enable it again and save it. 

Now recheck again by again trying to access the URL:

<code bash>
http://[staff-or-opac-ip-or-hostname]/api/v1/.html 
</code>