# Quick Start

{% hint style="info" %}
myinfo-connector-python is built with Django to make easy-to-go application. 
{% endhint %}

## Step 1: Clone the repository in your local

{% tabs %}
{% tab title="Bash" %}

```
git clone git@github.com:leeleelee3264/myinfo-connector-python.git
```

{% endtab %}
{% endtabs %}

## Step 2: Install Pre-requisite

#### Install Python 

{% hint style="info" %}
You can exclude python 3 is already installed in your local.
{% endhint %}

{% tabs %}
{% tab title="Bash" %}

```
brew install python@3.8 pipenv
```

{% endtab %}
{% endtabs %}

#### Set Python Path in \~/.zshrc

{% tabs %}
{% tab title="Bash" %}

```
export PATH="/opt/homebrew/opt/python@3.8/bin:$PATH"
```

{% endtab %}
{% endtabs %}

#### Refresh \~/.zshrc 

{% tabs %}
{% tab title="Bash" %}

```
source ~/.zshrc
```

{% endtab %}
{% endtabs %}

## Step 3: Install packages

{% tabs %}
{% tab title="Bash" %}

```
PIPENV_VENV_IN_PROJECT=1 
cd ~/myinfo-connector-python
pipenv install 
```

{% endtab %}
{% endtabs %}

## Step 4: Start server

{% tabs %}
{% tab title="First Tab" %}

```
pipenv run ./connector/manage.py runserver 0:3001
```

{% endtab %}

{% tab title="Second Tab" %}

{% endtab %}
{% endtabs %}

##

## Make your request

To make your first request, call apis in order. 

#### Step 1: Get myinfo redirect login url

## Get login url to redirect to myinfo

<mark style="color:blue;">`GET`</mark> `http://localhost:3001/users/me/external/myinfo-redirect-login`

Get login url to redirect to myinfo. This url contains attributes about person data requested to myinfo.

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "message": "OK",
    "data": {
        "url": "https://test.api.myinfo.gov.sg/com/v3/authorise?client_id=STG2-MYINFO-SELF-TEST&attributes=name,dob,birthcountry,nationality,uinfin,sex,regadd&state=eb03c000-00a3-4708-ab30-926306bfc4a8&redirect_uri=http://localhost:3001/callback&purpose=python-myinfo-connector",
        "state": "eb03c000-00a3-4708-ab30-926306bfc4a8"
    }
}
```

url: url to redirect to myinfo.&#x20;

state: Identifier that represents the user's session/transaction with the client for reconciling query and response. The same value will be sent back via the callback URL. Use a unique system generated number for each user/transaction.

{% endtab %}
{% endtabs %}

####

#### Step 2: Browse myinfo redirect login url&#x20;

{% tabs %}
{% tab title="Curl" %}

```
curl https://test.api.myinfo.gov.sg/com/v3/authorise?client_id=STG2-MYINFO-SELF-TEST&attributes=name,dob,birthcountry,nationality,uinfin,sex,regadd&state=eb03c000-00a3-4708-ab30-926306bfc4a8&redirect_uri=http://localhost:3001/callback&purpose=python-myinfo-connector// Some code
```

{% endtab %}
{% endtabs %}

#### Step 3: Do login and check agree terms

![Myinfo Login Page](https://635115963-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlInvAOhF8qXySERII8EX%2Fuploads%2FE6IjtdApO2Y4Vh0Jmv7F%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202022-07-23%20%E1%84%8B%E1%85%A9%E1%84%8C%E1%85%A5%E1%86%AB%2010.18.51.png?alt=media\&token=a5dea997-eaa6-4e97-a6d2-34d44874c174)

![Myinfo Terms Agreement Page](https://635115963-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlInvAOhF8qXySERII8EX%2Fuploads%2F0Rkc1LoDTjZN6MelW1a6%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202022-07-23%20%E1%84%8B%E1%85%A9%E1%84%8C%E1%85%A5%E1%86%AB%2010.19.35.png?alt=media\&token=8a57d719-9333-40af-8fbc-af566b914471)

#### (Automated) Step 4: Callback API get called by Myinfo&#x20;

After login, Myinfo call our callback api to pass auth code as a response.&#x20;

## Callback called by Myinfo service

<mark style="color:blue;">`GET`</mark> `http://localhost:3001/callback`

After login Myinfo and agree terms, Myinfo service automatically call myinfo-connector-python's callback API to pass auth code.

#### Query Parameters

| Name                                    | Type   | Description                                                                                                                                                                                                                          |
| --------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| code<mark style="color:red;">\*</mark>  | String | The authcode given by [myinfo's authorise API](https://public.cloud.myinfo.gov.sg/myinfo/api/myinfo-kyc-v3.2.2.html#operation/getauthorise)                                                                                          |
| state<mark style="color:red;">\*</mark> | String | Identifier that represents the user's session/transaction with the client for reconciling query and response. The same value will be sent back via the callback URL. Use a unique system generated number for each user/transaction. |

{% tabs %}
{% tab title="200: OK successfully called by Myinfo" %}

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
</head>
<body>
    <span>Callback from Myinfo. Wait for calling person data API</span>
    <span id="code-container">{{ code }}</span>
</body>

<script>
    window.addEventListener('load',
        function (event) {
            let code_element = document.getElementById('code-container')
            let code_text = code_element.innerHTML

            let url = `http://localhost:3001/users/me/external/myinfo?code=${code_text}`
            window.location.href = url
        }
    );
</script>
</html>

```

{% endtab %}
{% endtabs %}

callback url example

```
http://localhost:3001/callback?code=8932a98da8720a10e356bc76475d76c4c628aa7f&state=e2ad339a-337f-45ec-98fa-1672160cf463
```

Our callback api return simple HTML page to&#x20;

* get callback from Myinfo&#x20;
* call api for person data automatically right after the callback api called.&#x20;

![Response Page for callback api](https://635115963-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlInvAOhF8qXySERII8EX%2Fuploads%2FAR3Gcn5qGLw3XJOdDkUI%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202022-07-23%20%E1%84%8B%E1%85%A9%E1%84%8C%E1%85%A5%E1%86%AB%2010.32.34.png?alt=media\&token=88db50e3-c937-481d-93e1-0e69b4c7c16b)

#### (Automated) Final Step: Get Person data from Myinfo

After callback, callback page automatically calls our api for person data

## Get person data from myinfo

<mark style="color:blue;">`GET`</mark> `http://localhost:3001/users/me/external/myinfo`

Get person data from myinfo. The API is final step of myinfo-connector-python

#### Query Parameters

| Name | Type   | Description                                                                                                                                 |
| ---- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| code | String | The authcode given by [myinfo's authorise API](https://public.cloud.myinfo.gov.sg/myinfo/api/myinfo-kyc-v3.2.2.html#operation/getauthorise) |

{% tabs %}
{% tab title="200: OK Succeed to get person data from myinfo" %}

```json
{
    "message": "OK",
    "sodata": {
        "regadd": {
            "country": {
                "code": "SG",
                "desc": "SINGAPORE"
            },
            "unit": {
                "value": "10"
            },
            "street": {
                "value": "ANCHORVALE DRIVE"
            },
            "lastupdated": "2022-07-14",
            "block": {
                "value": "319"
            },
            "source": "1",
            "postal": {
                "value": "542319"
            },
            "classification": "C",
            "floor": {
                "value": "38"
            },
            "type": "SG",
            "building": {
                "value": ""
            }
        },
        "dob": "1988-10-06",
        "sex": "M",
        "name": "ANDY LAU",
        "birthcountry": "SG",
        "nationality": "SG",
        "uinfin": "S6005048A"
    }
}
```

regadd: Registered Address of Person (including FIN holders)

dob: Date of Birth of Person.

sex: Sex of Person.

name: Full Name of the Person.

birthcountry: Country of Birth of Person. Refer to `country` in code table provided [HERE](https://public.cloud.myinfo.gov.sg/myinfobiz/myinfo-business-api-code-tables.xlsx) for description of each code.

nationality: Nationality of Person. Refer to the [Code reference tables](https://public.cloud.myinfo.gov.sg/myinfo/api/myinfo-kyc-v3.2.2.html#section/Support) in the Support section for list of possible values.

unifin: Singapore issued identification number of the Person.
{% endtab %}

{% tab title="500: Internal Server Error Failed to get person data from myinfo" %}
{% tabs %}
{% tab title="AccessToken failure" %}

```
{
    "message": "Internal server error.",
    "code": "INTERNAL_SERVER_ERROR",
    "error": {
        "title": "오류가 발생했습니다.",
        "description": "Fail to get Myinfo Access Token. Authcode Might be re-used or expired.",
        "code": "INTERNAL_SERVER_ERROR",
        "data": null
    }
}
```

{% endtab %}

{% tab title="Person failure" %}

```
{
    "message": "Internal server error.",
    "code": "INTERNAL_SERVER_ERROR",
    "error": {
        "title": "오류가 발생했습니다.",
        "description": "Fail to parse Myinfo Person Data.",
        "code": "INTERNAL_SERVER_ERROR",
        "data": null
    }
}
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}