# API Integration

## Paradigm API Documentation

The Paradigm API examples calls may be viewed in the format of a Postman Collection available via this [**link**](https://documenter.getpostman.com/view/541303/TVRpz4qD) (<https://documenter.getpostman.com/view/541303/TVRpz4qD>)

Advanced programmers who are familiar with connecting to APIs are welcome to dive straight in using the Postman documentation for reference.

## Getting Started <a href="#getting-started" id="getting-started"></a>

When reading the documentation you’ll notice contents such as `{{apiUser}}` , these will need to be populated with values that would exist only in your Paradigm system. If you are making use of Postman to test call executions, this is how Postman represents environment variables.

### Common Variables <a href="#common-variables" id="common-variables"></a>

| **Variable Name** | **Description**                                                                                                              | **Example Content**       |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| host              | The hostname of your site                                                                                                    | <https://abc.edu.net.au>  |
| apiUser           | <p>This is the username of the user you wish to use the API with.<br>This username can be any user login in your system.</p> | `YourApplicationName.API` |
| apiPw             | The password for the user                                                                                                    | `*********`               |

## Logging In <a href="#logging-in" id="logging-in"></a>

{% hint style="danger" %}
**BE ADVISED**:

Do not use online tools to generate your base64 encoded logins as these 3rd party sites may store the login credentials resulting in a significant risk to the security of your Paradigm site.
{% endhint %}

To use the API you will need to set the HTTP `Authorization` header as “Basic {{encodedPassString}}”. The encoded pass string is a base64 encoded form of the following information: `username:password`

Use the following examples as a guide on how to correctly generate a base64 encoded text string. Replace the parameters `username` and `password` with the values, you want to use on your Paradigm site.

**Windows Command Prompt:**

```
powershell "[convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(\"username:password\"))
```

**Windows PowerShell:**

```
[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("username:password"))
```

**Linux Bash:**

```
echo  'username:password' | base64
```

&#x20;

## Example Requests <a href="#example-requests" id="example-requests"></a>

In the top menu, you have the option to select the LANGUAGE - as in the programming language or method that you will be using to connect to the API.\
\
By default this is curl:

```
curl --location -g --request GET 'https://host/api/rest/EduNoteData/?partyId={{sampleStudentPartyId}}' \
--header 'Content-Type: application/json'
```

&#x20;

If you use curl and replace the values in <> you should get data returned.

```
curl --location --request GET 'https://host/api/rest/Unit/<edu_unit_id>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <base64 encoded string>'
```

The following should also work in a web browser then prompted to login in.

```
https://host/api/rest/Unit/<edu_unit_id>
```

The following should also work in a web browser no login prompt

```
https://<username>:<password>@host/api/rest/Unit/<edu_unit_id>
```

## URL Encoding

The part after the first question mark is called a Query String.\
The query string needs special characters to be encoded because it’s already using some characters such as:

```
&?=
```

That needs to be treated as different from the full URL.\
\
There’s a handy document on it here\
<https://www.tutorialspoint.com/html/html_url_encoding.htm>\
\
Depending on the software platform that you’re using to transmit the request, there are different methods available to do this for you.\
\
PHP:

```php
urlencode($variable)
```

JavaScript:

```javascript
encodeURIComponent(vraiable)
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.silverband.com.au/home/paradigm-knowledge-base/system-configuration/workflows/api-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.