326 lines
9.6 KiB
Markdown
326 lines
9.6 KiB
Markdown
# API Create Client + User
|
|
|
|
## 🎯 **Overview**
|
|
|
|
API ini memungkinkan pembuatan Client dan Admin User dalam satu panggilan API. **Endpoint ini bersifat PUBLIC** dan tidak memerlukan authentication. Sangat berguna untuk setup awal sistem multi-tenant atau ketika perlu membuat client baru dengan admin user secara bersamaan.
|
|
|
|
## 🚀 **Endpoint**
|
|
|
|
```
|
|
POST /api/clients/with-user
|
|
```
|
|
|
|
## 📋 **Request Structure**
|
|
|
|
### **Headers**
|
|
```
|
|
Content-Type: application/json
|
|
```
|
|
|
|
### **Request Body**
|
|
```json
|
|
{
|
|
"clientName": "string (required)",
|
|
"clientDescription": "string (optional)",
|
|
"clientType": "string (required) - oneof: parent_client, sub_client, standalone",
|
|
"parentClientId": "string (optional) - UUID format",
|
|
"maxUsers": "integer (optional)",
|
|
"maxStorage": "integer (optional) - in bytes",
|
|
"adminUser": {
|
|
"username": "string (required)",
|
|
"email": "string (required) - email format",
|
|
"fullname": "string (required)",
|
|
"password": "string (required) - min 8 characters",
|
|
"address": "string (optional)",
|
|
"phoneNumber": "string (optional)",
|
|
"workType": "string (optional)",
|
|
"genderType": "string (optional)",
|
|
"identityType": "string (optional)",
|
|
"identityGroup": "string (optional)",
|
|
"identityGroupNumber": "string (optional)",
|
|
"identityNumber": "string (optional)",
|
|
"dateOfBirth": "string (optional)",
|
|
"lastEducation": "string (optional)",
|
|
"userRoleId": "integer (required)",
|
|
"userLevelId": "integer (required)"
|
|
}
|
|
}
|
|
```
|
|
|
|
## 📊 **Response Structure**
|
|
|
|
### **Success Response (200)**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"messages": ["Client and admin user created successfully"],
|
|
"data": {
|
|
"client": {
|
|
"id": "uuid",
|
|
"name": "string",
|
|
"description": "string",
|
|
"clientType": "string",
|
|
"parentClientId": "string",
|
|
"maxUsers": "integer",
|
|
"maxStorage": "integer",
|
|
"isActive": "boolean",
|
|
"createdAt": "datetime"
|
|
},
|
|
"adminUser": {
|
|
"id": "integer",
|
|
"username": "string",
|
|
"email": "string",
|
|
"fullname": "string",
|
|
"address": "string",
|
|
"phoneNumber": "string",
|
|
"workType": "string",
|
|
"genderType": "string",
|
|
"identityType": "string",
|
|
"identityGroup": "string",
|
|
"identityGroupNumber": "string",
|
|
"identityNumber": "string",
|
|
"dateOfBirth": "string",
|
|
"lastEducation": "string",
|
|
"userRoleId": "integer",
|
|
"userLevelId": "integer",
|
|
"clientId": "string",
|
|
"statusId": "integer",
|
|
"isActive": "boolean",
|
|
"createdAt": "datetime"
|
|
},
|
|
"message": "Client and admin user created successfully"
|
|
}
|
|
}
|
|
```
|
|
|
|
### **Error Response (400/500)**
|
|
```json
|
|
{
|
|
"success": false,
|
|
"messages": ["Error message"],
|
|
"code": 400
|
|
}
|
|
```
|
|
|
|
## 🔧 **Usage Examples**
|
|
|
|
### **1. Create Standalone Client with Admin User**
|
|
|
|
```bash
|
|
curl -X POST "http://localhost:8080/api/clients/with-user" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"clientName": "Acme Corporation",
|
|
"clientDescription": "A leading technology company",
|
|
"clientType": "standalone",
|
|
"maxUsers": 100,
|
|
"maxStorage": 1073741824,
|
|
"adminUser": {
|
|
"username": "admin_acme",
|
|
"email": "admin@acme.com",
|
|
"fullname": "John Doe",
|
|
"password": "SecurePass123",
|
|
"address": "123 Tech Street, Silicon Valley",
|
|
"phoneNumber": "+1-555-0123",
|
|
"workType": "Full-time",
|
|
"genderType": "Male",
|
|
"identityType": "Passport",
|
|
"identityNumber": "P123456789",
|
|
"dateOfBirth": "1985-06-15",
|
|
"lastEducation": "Master Degree",
|
|
"userRoleId": 1,
|
|
"userLevelId": 1
|
|
}
|
|
}'
|
|
```
|
|
|
|
### **2. Create Sub Client with Admin User**
|
|
|
|
```bash
|
|
curl -X POST "http://localhost:8080/api/clients/with-user" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"clientName": "Acme Branch Office",
|
|
"clientDescription": "Branch office in New York",
|
|
"clientType": "sub_client",
|
|
"parentClientId": "550e8400-e29b-41d4-a716-446655440000",
|
|
"maxUsers": 50,
|
|
"maxStorage": 536870912,
|
|
"adminUser": {
|
|
"username": "admin_branch",
|
|
"email": "admin@branch.acme.com",
|
|
"fullname": "Jane Smith",
|
|
"password": "BranchPass123",
|
|
"address": "456 Business Ave, New York",
|
|
"phoneNumber": "+1-555-0456",
|
|
"workType": "Full-time",
|
|
"genderType": "Female",
|
|
"identityType": "Driver License",
|
|
"identityNumber": "DL987654321",
|
|
"dateOfBirth": "1990-03-22",
|
|
"lastEducation": "Bachelor Degree",
|
|
"userRoleId": 2,
|
|
"userLevelId": 2
|
|
}
|
|
}'
|
|
```
|
|
|
|
### **3. Create Parent Client with Admin User**
|
|
|
|
```bash
|
|
curl -X POST "http://localhost:8080/api/clients/with-user" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"clientName": "Global Enterprise",
|
|
"clientDescription": "Global enterprise with multiple branches",
|
|
"clientType": "parent_client",
|
|
"maxUsers": 1000,
|
|
"maxStorage": 10737418240,
|
|
"adminUser": {
|
|
"username": "super_admin",
|
|
"email": "superadmin@global.com",
|
|
"fullname": "Robert Johnson",
|
|
"password": "SuperSecure123",
|
|
"address": "789 Corporate Blvd, Global City",
|
|
"phoneNumber": "+1-555-0789",
|
|
"workType": "Full-time",
|
|
"genderType": "Male",
|
|
"identityType": "Passport",
|
|
"identityNumber": "P987654321",
|
|
"dateOfBirth": "1980-12-10",
|
|
"lastEducation": "PhD",
|
|
"userRoleId": 1,
|
|
"userLevelId": 1
|
|
}
|
|
}'
|
|
```
|
|
|
|
## 📝 **Field Descriptions**
|
|
|
|
### **Client Fields**
|
|
| Field | Type | Required | Description |
|
|
|-------|------|----------|-------------|
|
|
| `clientName` | string | ✅ | Nama client |
|
|
| `clientDescription` | string | ❌ | Deskripsi client |
|
|
| `clientType` | string | ✅ | Tipe client: `parent_client`, `sub_client`, `standalone` |
|
|
| `parentClientId` | string | ❌ | UUID parent client (untuk sub_client) |
|
|
| `maxUsers` | integer | ❌ | Maksimal jumlah user |
|
|
| `maxStorage` | integer | ❌ | Maksimal storage dalam bytes |
|
|
|
|
### **Admin User Fields**
|
|
| Field | Type | Required | Description |
|
|
|-------|------|----------|-------------|
|
|
| `username` | string | ✅ | Username untuk login |
|
|
| `email` | string | ✅ | Email address (format email) |
|
|
| `fullname` | string | ✅ | Nama lengkap |
|
|
| `password` | string | ✅ | Password (min 8 karakter) |
|
|
| `address` | string | ❌ | Alamat |
|
|
| `phoneNumber` | string | ❌ | Nomor telepon |
|
|
| `workType` | string | ❌ | Tipe pekerjaan |
|
|
| `genderType` | string | ❌ | Jenis kelamin |
|
|
| `identityType` | string | ❌ | Tipe identitas |
|
|
| `identityGroup` | string | ❌ | Grup identitas |
|
|
| `identityGroupNumber` | string | ❌ | Nomor grup identitas |
|
|
| `identityNumber` | string | ❌ | Nomor identitas |
|
|
| `dateOfBirth` | string | ❌ | Tanggal lahir |
|
|
| `lastEducation` | string | ❌ | Pendidikan terakhir |
|
|
| `userRoleId` | integer | ✅ | ID role user |
|
|
| `userLevelId` | integer | ✅ | ID level user |
|
|
|
|
## 🔒 **Authentication & Authorization**
|
|
|
|
- **Required**: None (Public endpoint)
|
|
- **Permission**: No authentication required
|
|
- **Access**: Anyone can create a client and admin user
|
|
|
|
## ⚠️ **Error Handling**
|
|
|
|
### **Common Error Scenarios**
|
|
|
|
1. **Invalid Request Body (400)**
|
|
```json
|
|
{
|
|
"success": false,
|
|
"messages": ["Invalid request body"],
|
|
"code": 400
|
|
}
|
|
```
|
|
|
|
2. **Validation Failed (400)**
|
|
```json
|
|
{
|
|
"success": false,
|
|
"messages": ["Key: 'ClientWithUserCreateRequest.AdminUser.Email' Error:Field validation for 'Email' failed on the 'email' tag"],
|
|
"code": 400
|
|
}
|
|
```
|
|
|
|
3. **User Creation Failed (500)**
|
|
```json
|
|
{
|
|
"success": false,
|
|
"messages": ["failed to create admin user: username already exists"],
|
|
"code": 500
|
|
}
|
|
```
|
|
|
|
4. **Invalid Parent Client ID (500)**
|
|
```json
|
|
{
|
|
"success": false,
|
|
"messages": ["invalid parent client ID: invalid UUID length: 5"],
|
|
"code": 500
|
|
}
|
|
```
|
|
|
|
## 🎯 **Business Logic**
|
|
|
|
### **Process Flow**
|
|
1. **Validate Request** menggunakan struct validation
|
|
2. **Generate Client ID** menggunakan UUID
|
|
3. **Parse Parent Client ID** jika ada
|
|
4. **Create Client Entity** dengan data yang diberikan
|
|
5. **Create Admin User Entity** dengan client ID yang baru
|
|
6. **Save User** menggunakan existing repository
|
|
7. **Update Client** dengan created user ID
|
|
8. **Return Response** dengan data client dan user
|
|
|
|
### **Data Relationships**
|
|
- **Client** → **Admin User**: One-to-One relationship
|
|
- **Parent Client** → **Sub Client**: One-to-Many relationship
|
|
|
|
## 🔧 **Implementation Notes**
|
|
|
|
### **Current Limitations**
|
|
- **TODO**: Client repository belum diimplementasi (simulasi saja)
|
|
- **TODO**: Keycloak integration untuk user creation
|
|
- **TODO**: Transaction rollback jika user creation gagal
|
|
- **Public Endpoint**: Tidak ada authentication, semua orang bisa akses
|
|
|
|
### **Future Enhancements**
|
|
- Implementasi client repository yang sesungguhnya
|
|
- Integration dengan Keycloak untuk user management
|
|
- Transaction management untuk data consistency
|
|
- Email notification untuk admin user
|
|
- Bulk client creation
|
|
- Rate limiting untuk public endpoint
|
|
- CAPTCHA untuk mencegah abuse
|
|
|
|
## 📚 **Related APIs**
|
|
|
|
- `POST /api/users` - Create individual user
|
|
- `POST /api/clients` - Create individual client
|
|
- `GET /api/clients` - List all clients
|
|
- `GET /api/users` - List all users
|
|
|
|
## 🎉 **Summary**
|
|
|
|
API ini memberikan kemudahan untuk:
|
|
- ✅ **Single API Call**: Membuat client dan admin user sekaligus
|
|
- ✅ **Public Access**: Tidak memerlukan authentication
|
|
- ✅ **Data Consistency**: Memastikan relasi client-user terhubung dengan benar
|
|
- ✅ **Flexible Configuration**: Mendukung berbagai tipe client
|
|
- ✅ **Comprehensive Validation**: Validasi lengkap untuk semua field
|
|
- ✅ **Detailed Response**: Response yang informatif dengan data lengkap
|
|
|
|
Perfect untuk setup awal sistem multi-tenant dengan akses public! 🚀 |