cicnavi/pirac

dev-master 2016-12-15 11:46 UTC

README

Pirac can be used to easily communicate with the ISVU REST API v2.

Installation

Add these lines to your composer.json file:

"require": {
    "cicnavi/pirac": "dev-master"
}

Next, run composer update command.

Configuration

Pirac utilizes the DotEnv PHP library by Vance Lucas. In the root directory of your application, you have to create a .env file. In .env file, Pirac will look for these two variables:

ISVU_USERNAME=exampleusername
ISVU_PASSWORD=examplepassword

Make sure you assign your ISVU REST API username and password to those variables, since those will be used on every request to ISVU REST API. We suggest that you enter production API credentials to those two variables. You can also set credentials for test API. If you want to use the test API, also add these variables:

ISVU_USE_TEST_API=true
ISVU_TEST_USERNAME=someTestUserName
ISVU_TEST_PASSWORD=someTestPassword

Important note: your .env file should not be committed to your application's source control!

Usage

Pirac uses Httpful by nategood to send requests to ISVU REST API. The returned resource will be instance of PHP stdClass. Httpful uses cURL component, so make sure you have it installed and enabled.

In general, you can use Pirac to communicate with single institution ISVU REST API. The first thing we can do now is to fetch available starting resources and their links. We can do that with the following line:

$pirac->getIndex();

This will return available resources thogether with their links. We can use those links in another Pirac method:

$pirac->get('url');

By default, Pirac uses "application/hal+json" as Accept HTTP header. This can be changed by providing an array of headers as the second parameter. By setting the appropriate Accept header, we can actually use ISVU REST API version 1. For example, to use ISVU REST API v1, we can enter the 'application/xml' as Accept header:

$pirac->get('url', ['Accept' => 'application/xml']);

Check ISVU REST API documentation for more information.

Example

        use Pirac\Pirac;

        // Create Pirac instance.
        $pirac = new Pirac();

        // Get index links.
        $indexLinks = $pirac->getIndex();

        // Get specific resource.
        $nastavniplan = $pirac->get($indexLinks->nastavniplan->href);

Multi Institution API

If you have access to multi institution API, you can use getIndex() method to get the list of all available institutions. This will return an array containing all institutions.

$allInstitutions = $pirac->getIndex();

However, if you use a single institution API, getIndex() method will return a stdClass object containing available resources and their links.

License

Pirac is open-sourced software licensed under the MIT license