# Edcess Tutor Registration API

API for receiving request from tutors through the wordpress website. Form submission will comprise of two main steps:
1. Form data is submitted to an endpoint to create an application. If successful, the endpoint will return an `applicationId`
2. Upload the file for the given `applicationId`

## Base URL

To be added

## Authentication

> To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "<base_url>/api"
  -H "Authorization: api-key"

> Make sure to replace `api-key` with your API key.

We use an `api-key` to authenticate users. Please contact [e-mail] for a key.

`Authorization: meowmeowmeow`

<aside class="notice">
You must replace <code>api-key</code> with your personal API key.
</aside>

## Tutor Registration

### Send Tutor Details Data (Private Tutor)

This endpoint should be called from the web page that collects tutor registration details.

Endpoint:

POST    /web/v1/tutors/private

curl --location --request POST 'http://localhost:5001/edcess-9cc0f/asia-east2/web/tutors' \
--header 'Authorization: Bearer some_api_key' \
--header 'Content-Type: application/json' \
--data-raw '{
    "firstName" : "John",
	"lastName" : "Doeee",
    "gender" : "m",
    "prefix" : "mr",
    "citizenship" : "singaporean",
    "dateOfBirth" : "2020-09-01",
    "contactNumber" : "88888888",
    "postalCode" : "123456",
    "locationPreferences" : ["south", "north"],
    "availability" : ["mon_12-15"],
    "subjects" : ["english"],
    "teachingPreferences" : "online",
    "race" : "chinese",
    "minRate" : 30,
    "commitmentPeriodMonths" : 3,
    "commencementDate" : "2020-09-15",
    // cont..
}'

> The above command takes in a JSON request, structured like this:

{
	"firstName" : "John",
	"lastName" : "Doeee",
    "gender" : "m",
    "prefix" : "mr",
    "citizenship" : "singaporean",
    "dateOfBirth" : "2020-09-01",
    "contactNumber" : "88888888",
    "postalCode" : "123456",
    "locationPreferences" : ["south", "north"],
    "availability" : ["mon_12-15"],
    "race" : "chinese",
    "teachingPreferences" : [
        {
            "studentLevel" : "sec_3",
            "studentStream" : "express",
            "subject": "mathematics",
            "minRatePerHr" : 30,
            "commencementDate" : "2020-09-15",
            "commitmentPeriod" : 3
        },
        {
            "studentLevel" : "sec_4",
            "studentStream" : "express",
            "subject": "mathematics",
            "minRatePerHr" : 30,
            "commencementDate" : "2020-09-15",
            "commitmentPeriod" : 3
        }
    ]
    //cont....
}

> The above command returns JSON structured like this:

{
  "applicationId" : "6asd81ec71nc"
}

`applicationId` is the identifier of the application. This will be required in the next step.

### Query Parameters

Parameter | Type | Description
--------- | ------- | -----------
`prefix` | `string` | Prefix for the tutor. Can be either `mr`, `ms`, `mrs` or `dr`
`firstName` | `string` | First name of the user
`lastName` | `string` | Last name of the user
`email` | `string` | Email address
`contactNumber` | `string` | 8-digit contact number
`postalCode` | `string` | 6-digit postal code
`gender` | `string` | Gender (either `m` or `f` )
`citizenship` | `string` | Either `singaporean` (Singapore Citizen), `pr` (Permanent Resident) or `foreigner` (Foreigner)
`race` | `string` | One of the following values: `chinese`, `malay`, `indian`, `eurasian`, `others`
`dateOfBirth` | `string` | DOB in the following format DD-MMM-YYYY (e.g. 25-DEC-1990)
`fromTuitionCentre` | `boolean` | True if from tuition centre, false if otherwise
`tuitionCentreName` | `string` | Name of tuition centre (Applicable if `fromTuitionCentre` is true). Otherwise, add NA.
`isStudying` | `boolean` | true if applicant is still studying.
`highestEducationObtained` | `string` | Highest education obtained (e.g. Bachelors)
`institutionName` | `string` | Name of institution |
`yearGraduated` | `string` | Year graduated in YYYY format
`currentPursuedEducationLevel` | `string` | Current pursued qualification
`currentInstitutionName` | `string` | Current institution name (Only applicable for current student)
`currentExpectedCompletion` | `string` | Current expected completion
`currentQualificationDetails` | `string` | Current qualification details
`tutorExperience` | `string` | Tutor's experience
`teachingInstitutionName` | `string` | Name of institution taught at
`teachingPeriod` | `string` | Teaching period (e.g. 2001-2005)
`profileDescription` | `string` | Profile description
`student_levels` | `List(String)` | List of levels (see [spreadsheet](https://docs.google.com/spreadsheets/d/1CcqBwpIbgXWdd6pq2-VdBM7vTPsPb5te62I_hLMnyd4/edit?usp=sharing) for allowed values and mapping)
`preferredSteams` | `List(String)` | List of supported streams
`subjects` | `List(String)` | List of subjects (see [spreadsheet](https://docs.google.com/spreadsheets/d/1CcqBwpIbgXWdd6pq2-VdBM7vTPsPb5te62I_hLMnyd4/edit?usp=sharing) for allowed values and mapping)
`commencementDate` | `string` | Date in `YYYY-MM-DD` format.
`commitmentPeriodMonths` | `number` | Commimtment period in months
`minRate` | `number` | Minimum hourly rate for tuition in SGD
`availability` | `List(String)` | Available timeslots in a day. Values allowed corresponds to the following pattern - `dayofweek<underscore>startTime<hyphen>endHour` (e.g. Monday 12 - 3 pm = `mon_12-15`)
`locationPreferences` | `List(String)` | List of locations `north`, `north_west`, `west`, `central`, `north_east`, `east`, `south` or `no_preference`
`additional_information` | `string` | Information about additional information that the tutor may have
| `preferredPaymentMethod` | `string` | Either `paynow` or `bankAccount` |
| `paynowDetails` | `string` | Details if user enters paynow as an option. This could be phone number or UEN (Only applicable if `preferredPaymentMethod` is PayNow)
| `bankAccount` | `string` | Bank account number (Only applicable if `preferredPaymentMethod` is Bank Transfer)
| `nameOfBank` | `string` | Name of bank (Only applicable if `preferredPaymentMethod` is Bank Transfer)

If there is an error, server will respond with a 400 HTTP Status Code, with details on what error is found:

{
    "message": "Validation Error",
    "details": [
        {
            "message": "\"postalCode\" is required"
        }
    ]
}

### Send Tutor Details Data (Tuition Centre)

This endpoint should be called from the web page that collects tutor registration details.

Endpoint:

POST    /web/v1/tutors/tuitionCentre

curl --location --request POST 'http://localhost:5001/edcess-9cc0f/asia-east2/web/tutors' \
--header 'Authorization: Bearer some_api_key' \
--header 'Content-Type: application/json' \
--data-raw '{ 
    // similar to above
}'

> The above command returns JSON structured like this:

{
  "applicationId" : "6asd81ec71nc"
}

`applicationId` is the identifier of the application. This will be required in the next step.

### Query Parameters

Parameter | Type | Description
--------- | ------- | -----------
`name` | `string` | Name of tuition centre
| `moeRegistered` | `boolean` | True if MOE-registed, false otherwise
`contactNumber` | `string` | 8-digit contact number
`email` | `string` | Email address of tuition centre
`address` | `string` | Address of tuition centre
`block` | `string` | Block number
`unitNo` | `string` | Unit number
`postalCode` | `string` | 6-digit postal code
`description` | `string` | Description of tuition centre (limited to 300 words)
| `preferredPaymentMethod` | `string` | Either `paynow` or `bankAccount` |
| `paynowDetails` | `string` | Details if user enters paynow as an option. This could be phone number or UEN (Only applicable if `preferredPaymentMethod` is PayNow)
| `bankAccount` | `string` | Bank account number (Only applicable if `preferredPaymentMethod` is Bank Transfer)
| `nameOfBank` | `string` | Name of bank (Only applicable if `preferredPaymentMethod` is Bank Transfer)

### File Upload

After submitting the application, you should now have the `applicationId`. This endpoint allows you to upload the files to our server.

POST       /fileUpload?:applicationId

The applicationId is required as a request query parameter. The endpoint will validate if the application has been created. If it has not been created, it will throw a 404 NOT FOUND error.

Files will be received through a multipart form-data request on a field called `files`. File submission is limited to 10MB.

Example request

curl --location --request POST 'http://api.edcess.io/asia-east2/fileUpload?applicationId=SOME_APPLICATION_ID' \
--header 'Authorization: Bearer some_secret_key' \
--form 'files=path_to_pic1.png' \
--form 'files=path_to_pic2.png' \
--form 'files=path_to_pic3.png'

### Response

If successful, it will return a 200 success code.