A. Web Assessment System API Documentation

Bagian ini menjelaskan dokumentasi API pada sistem web assessment (platform ujian online). API ini mendukung operasi CRUD dan service lainnya.

Base URL

Semua permintaan API menggunakan URL berikut sebagai basis:

https://xx.xx.xx.xxx/api/v1

1. Autentikasi

1.1 Mendapatkan Token CSRF

Endpoint: GET /auth/csrf-token

Deskripsi: Mendapatkan token CSRF yang akan digunakan untuk permintaan selanjutnya. Token ini disimpan dalam cookie x-xsrf-token dengan pengaturan secure untuk memastikan cookie hanya dikirim melalui koneksi HTTPS.

Contoh Response (200 OK):

{
  "csrfToken": "value"
}

Cookies:

• x-xsrf-token: Disimpan dengan secure: true, httpOnly: true.

Contoh Request (Curl):

curl -X GET https://xx.xx.xx.xxx/v1/auth/csrf-token

---

1.2 Login Peserta Ujian

Endpoint: POST /auth/login

Deskripsi: Gunakan endpoint ini untuk autentikasi peserta ujian menggunakan Nama Lengkap dan NRP. Setelah login berhasil, token JWT disimpan dalam cookie HTTP-only dengan pengaturan secure, memastikan hanya dikirim melalui HTTPS.

Request:

Headers:

X-XSRF-TOKEN: <token-csrf>

Body:

{
  "name": "johndoe",
  "registeredNumber": "12345678"
}

Contoh Response (200 OK):

{
  "name": "John Doe",
  "eventId": 1,
  "eventTitle": "Ujian Nasional",
  "eventSlug": "ujian-nasional",
  "id": 123,
  "examRegisteredNumber": "12304567892024"
}

Contoh Request (Curl):

curl -X POST https://xx.xx.xx.xxx/v1/auth/login \
-H 'Content-Type: application/json' \
-H 'Cookie: x-xsrf-token=<token-csrf>' \
-H 'X-XSRF-TOKEN: <token-csrf>' \
-d '{"name": "johndoe", "registeredNumber": "password123"}'

Response Cookies:

• sl_token: Token autentikasi JWT disimpan dengan secure: true, httpOnly: true.
  

1.3 Registrasi Pengguna Baru

Endpoint: POST /auth/register

Deskripsi: Gunakan endpoint ini untuk registrasi pengguna baru. CAPTCHA diperlukan untuk validasi. Setelah registrasi, pengguna akan otomatis login dan token JWT disimpan dalam cookie HTTP-only dengan pengaturan secure.

Request:

Headers:

X-XSRF-TOKEN: <token-csrf>

Query Parameters:

• token (optional): Token opsional untuk registrasi otomatis di suatu even ujian.

Body:

{
  "name": "Jane Doe",
  "registeredNumber": "12345678",
  "rankId": 1,
  "positionId": 1,
  "unitId": 1,
  "captcha": "1234"
}

Contoh Response (201 Created):

{
  "id": 1,
  "name": "Jane Doe",
  "registeredNumber": "12345678",
  "rankId": 1,
  "positionId": 1,
  "unitId": 1,
  "accessCode": "unique_access_code"
}

Response Cookies:

• sl_token: Response Token autentikasi disimpan dengan secure: true dan httpOnly: true (jika terdapat token untuk registrasi otomatis ke event ujian).

Contoh Request (Curl):

curl -X POST https://xx.xx.xx.xxx/v1/auth/register?token=event_token \
-H 'Content-Type: application/json' \
-H 'Cookie: x-xsrf-token=<token-csrf>' \
-H 'X-XSRF-TOKEN: <token-csrf>' \
-d '{""name": "Jane Doe","registeredNumber": "12345678","rankId": 1,"positionId": 1,"unitId": 1,"captcha": "1234"}'

1.4 Logout Pengguna

Endpoint: GET /auth/logout

Deskripsi: Gunakan endpoint ini untuk mengeluarkan pengguna dari sistem dengan menghapus cookie autentikasi.

Contoh Response (200 OK):

{
  "message": "Logout successful"
}

Cookies:

• sl_token: Cookie dihapus dengan secure: true.

Contoh Request (Curl):

curl -X GET https://xx.xx.xx.xxx/v1/auth/logout \

---

2.Peserta Ujian

2.1. Data Current Participant

Endpoint: GET /participant

Description: Retrieve the current participant's data based on the provided session token.

Request:

Cookies: sl_token (required): The session token used to identify the participant.

Contoh Response (200):

{
    "title": "Online English Skill Assessment",
    "date": "2024-08-05T17:00:00.000Z",
    "rule": "ibt",
    "startTime": "02:36:00",
    "endTime": "02:39:00",
    "sections": [Object Data]
}

Contoh Response (400):

{
  "statusCode": 400,
  "message": "Invalid token or participant ID",
  "error": "Bad Request"
}

Status Code (404 Not Found):

{
  "statusCode": 404,
  "message": "Participant not found",
  "error": "Not Found"
}

3. Event

Semua permintaan API memerlukan autentikasi menggunakan JWT yang disimpan dalam cookie sl_token.

3.1. Mendapatkan Data Simulation

Endpoint: GET /event/simulation

Deskripsi: Mendapatkan data simulasi dari event. Jika data simulasi tidak tersedia dalam cache, data akan diambil dari layanan event dan disimpan ke dalam cache untuk permintaan selanjutnya.

Contoh Response (200 OK):

{
  "id": 1,
  "name": "Simulation Test Package",
  "sections": [Object Data]
}

Contoh Request (Curl):

    curl -X GET https://xx.xx.xx.xxx/v1/event/simulation

3.2 Get Event for Signed-In Participant

Endpoint: GET /event

Deskripsi: Mendapatkan data event untuk peserta ujian yang sudah login berdasarkan token yang ada di cookie. Jika parameter sectionId disertakan, hanya data dari section tersebut yang akan dikembalikan.

Request:

Query Parameters:

• sectionId (optional): ID section yang ingin diambil datanya.

Contoh Response (200 OK):

{
  "id": 1,
  "eventTitle": "Ujian Nasional",
  "sections": [Object Data]
}

Cookies:

• sl_token: Token autentikasi JWT dari peserta ujian.

Contoh Request (Curl):

curl -X GET https://xx.xx.xx.xxx/v1/event?sectionId=1 \
-b "sl_token=your-jwt-token"

3.3 Get Sections Data on Event Test

Endpoint: GET /event/sections

Deskripsi: Mendapatkan data sections pada sebuah event ujian berdasarkan ID peserta yang sudah login. Informasi ini diambil menggunakan token yang tersimpan dalam cookie.

Request:

Contoh Response (200 OK):

{
  "id": 1,
  "eventTitle": "Ujian Nasional",
  "sections": [
    {
      "id": 1,
      "title": "Section 1",
      "questions": [Object Data]
    }
  ]
}

Cookies:

• sl_token: Token autentikasi JWT dari peserta ujian.

Contoh Request (Curl):

curl -X GET https://xx.xx.xx.xxx/v1/event/sections \
-b "sl_token=your-jwt-token"

4. Test Responses

Semua permintaan API memerlukan autentikasi menggunakan JWT yang disimpan dalam cookie sl_token.

4.1 Submit Test Response

Endpoint: POST /test-responses

Deskripsi: Mengirimkan satu test response dari peserta ujian. Token peserta ujian diambil dari cookie sl_token dan digunakan untuk memvalidasi identitas.

Request Body:

{
  "questionId": 101,
  "answer": "Paris",
}

Cookies:

• sl_token: Token autentikasi JWT dari peserta ujian.

Headers:

X-XSRF-TOKEN: <token-csrf>

Contoh Response (201 Created):

{
  "id": 1,
  "questionId": 101,
  "answer": "Paris",
  "participantId": 5,
  "packageId": 1,
  "eventId": 10,
  "score": 10,
  "createdAt": "2024-09-13T10:00:00Z",
  "updatedAt": "2024-09-13T10:00:00Z"
}

Contoh Request (Curl):

curl -X POST https://xx.xx.xx.xxx/v1/test-responses \
-H 'X-CSRF-TOKEN: <your-csrf-token>' \
-H 'Content-Type: application/json' \
--cookie "sl_token=<your-jwt-token>" \
-d '{
  "questionId": 101,
  "answer": "Paris",
}'

4.2 Submit Bulk Test Responses

Endpoint: POST /test-responses/bulk

Deskripsi: Mengirimkan beberapa test responses sekaligus dari peserta ujian. Token peserta ujian diambil dari cookie sl_token dan digunakan untuk memvalidasi identitas. Data responses dikirimkan dalam bentuk array.

Request Body:

[
  {
    "questionId": 101,
    "answer": "Paris",
  },
  {
    "questionId": 102,
    "answer": "Berlin",
  }
]

Query Parameters:

• status (optional): Status tambahan yang ingin disertakan dalam submit bulk responses, misalnya completed.

Cookies:

• sl_token: Token autentikasi JWT dari peserta ujian.

Headers:

X-XSRF-TOKEN: <token-csrf>

Contoh Request (Curl):

curl -X POST https://xx.xx.xx.xxx/v1/test-responses/bulk?status=completed \
-H 'X-CSRF-TOKEN: <your-csrf-token>' \
-H 'Content-Type: application/json' \
--cookie "sl_token=<your-jwt-token>" \
-d '[
  {
    "questionId": 101,
    "answer": "Paris",
  },
  {
    "questionId": 102,
    "answer": "Berlin",
  }
]'

4.3 Error Handling

Kode status yang umum digunakan dalam API ini meliputi:

Status Code	Deskripsi
200 OK	Permintaan berhasil dijalankan.
400 Bad Request	Data permintaan tidak valid.
401 Unauthorized	Token autentikasi tidak valid.
404 Not Found	Resource yang diminta tidak ditemukan.
500 Internal Server Error	Kesalahan server yang tidak terduga.

---

5. Media

5.1 Upload Video

Endpoint: POST /video

Deskripsi: Gunakan endpoint ini untuk mengunggah file video. Hanya video dengan format webm dan ukuran maksimum 10 MB yang diizinkan. Video ini diunggah dan diproses berdasarkan opsi yang diberikan.

Request: Headers:

X-XSRF-TOKEN: <token-csrf>

Content-Type: multipart/form-data

Query Parameters:

• option (optional): Parameter opsional untuk menentukan opsi penanganan video khusus.

Body (multipart/form-data):

• file: File video yang akan diunggah.

Cookies:

• sl_token: Token autentikasi yang digunakan untuk mengidentifikasi peserta yang mengunggah video.

Contoh Response (201 Created):

{
  "message": "Video uploaded successfully"
}

Contoh Kesalahan (400 Bad Request):

{
  "statusCode": 400,
  "message": "Invalid file type or file size exceeds limit",
  "error": "Bad Request"
}

Cookies:

• sl_token: Digunakan untuk autentikasi peserta.

Contoh Request (Curl):

curl -X POST https://xx.xx.xx.xxx/v1/video \
-H 'Content-Type: multipart/form-data' \
-H 'Cookie: sl_token=<your_token>' \
-H 'Cookie: x-xsrf-token=<csrf>' \
-F 'file=@video.webm' \
--form 'option=compress'

6. Audio

Semua permintaan API memerlukan autentikasi menggunakan JWT yang disimpan dalam cookie sl_token.

6.1 Stream Audio

Endpoint: GET /audio

Deskripsi: Mengalirkan (streaming) file audio berdasarkan parameter query audio. Nama atau path file audio harus diberikan melalui query string.

Query Parameters:

Nama	Tipe	Deskripsi	Wajib
id	String	File Path Audio	Ya

Headers:

X-XSRF-TOKEN: <token-csrf>

Cookies:

• sl_token: Token autentikasi JWT dari pengguna.

Responses:

Contoh Request (Curl):

curl -X GET 'https://xx.xx.xx.xxx/v1/audio?audio=example.mp3' \
--cookie "sl_token=<your-jwt-token>"

7. Units/Satuan

7.1 Mendapatkan Semua Unit/Satuan

Endpoint: GET /units

Deskripsi: Mengambil daftar semua unit yang tersedia dalam sistem.

Contoh Request (Curl):

curl -X GET 'https://xx.xx.xx.xxx/v1/units'

Response Contoh (200):

[
  {
    "id": 10,
    "title": "Komando Operasi Angkatan Udara (Koopsau)",
    "abbr": "Koopsau"
  },
  {
    "id": 11,
    "title": "Komando Pendidikan dan Latihan Angkatan Udara (Kodiklatau)",
    "abbr": "Kodiklatau"
  }
]

7.2 Mendapatkan Unit Berdasarkan ID

Endpoint: GET /units/{id}

Deskripsi: Mengambil informasi unit berdasarkan id yang diberikan.

Path Parameters:

Nama	Tipe	Deskripsi
id	String	ID dari unit yang ingin diambil.

Contoh Request (Curl):

curl -X GET 'https://xx.xx.xx.xxx/v1/units/1' \

Response Contoh (200):

{
  "id": 11,
  "title": "Komando Pendidikan dan Latihan Angkatan Udara (Kodiklatau)",
  "abbr": "Kodiklatau"
}

Response Contoh (404):

{
  "statusCode": 404,
  "message": "Unit with ID 1 not found",
  "error": "Not Found"
}

7.3 Error Handling

Kode status yang umum digunakan dalam API ini meliputi:

Status Code	Deskripsi
200 OK	Permintaan berhasil dijalankan.
400 Bad Request	Data permintaan tidak valid.
401 Unauthorized	Token autentikasi tidak valid.
404 Not Found	Resource yang diminta tidak ditemukan.
500 Internal Server Error	Kesalahan server yang tidak terduga.

---

8. Position/Jabatan

8.1 Mendapatkan Semua Unit/Satuan

Endpoint: GET /positions

Deskripsi: Mengambil daftar semua jabatan yang tersedia dalam sistem.

Contoh Request (Curl):

curl -X GET 'https://xx.xx.xx.xxx/v1/positions'

Response Contoh (200):

[
  {
    "id": 1,
    "title": "Komandan Satuan Pemeliharaan (KSP)",
    "abbr": "KSP"
  },
  {
    "id": 2,
    "title": "Komandan Satuan Radar (KSR)",
    "abbr": "KSR"
  },
  {
    "id": 3,
    "title": "Komandan Satuan Pendidikan (KSPd)",
    "abbr": "KSPd"
  }
]

8.2 Mendapatkan Position/Jabatan Berdasarkan ID

Endpoint: GET /posistions/{id}

Deskripsi: Mengambil informasi jabatan berdasarkan id yang diberikan.

Path Parameters:

Nama	Tipe	Deskripsi
id	String	ID dari position yang ingin diambil.

Contoh Request (Curl):

curl -X GET 'https://xx.xx.xx.xxx/v1/positions/1' \

Response Contoh (200):

  {
    "id": 2,
    "title": "Komandan Satuan Radar (KSR)",
    "abbr": "KSR"
  }

Response Contoh (404):

{
  "statusCode": 404,
  "message": "Position with ID 1 not found",
  "error": "Not Found"
}

9. Pangkat

9.1 Mendapatkan Semua Pangkat

Endpoint: GET /ranks

Deskripsi: Mengambil daftar semua pangkat yang tersedia dalam sistem.

Contoh Request (Curl):

curl -X GET 'https://xx.xx.xx.xxx/v1/ranks'

Response Contoh (200):

[
  {
    "id": 1,
    "title": "Prajurit Dua"
  },
  {
    "id": 2,
    "title": "Prajurit Satu"
  }
]

8.2 Mendapatkan Pangkat Berdasarkan ID

Endpoint: GET /ranks/{id}

Deskripsi: Mengambil informasi pangkat berdasarkan id yang diberikan.

Path Parameters:

Nama	Tipe	Deskripsi
id	String	ID dari pangkat yang ingin diambil.

Contoh Request (Curl):

curl -X GET 'https://xx.xx.xx.xxx/v1/ranks/1' \

Response Contoh (200):

{
    "id": 2,
    "title": "Prajurit Satu"
  }

Response Contoh (404):

{
  "statusCode": 404,
  "message": "Rank with ID 1 not found",
  "error": "Not Found"
}

9. Kode Status

Kode status yang umum digunakan dalam API ini meliputi:

Status Code	Deskripsi
200 OK	Permintaan berhasil dijalankan.
400 Bad Request	Data permintaan tidak valid.
401 Unauthorized	Token autentikasi tidak valid.
404 Not Found	Resource yang diminta tidak ditemukan.
500 Internal Server Error	Kesalahan server yang tidak terduga.

---