API Developer Guide – Solvera

Dokumen ini menjelaskan standar lengkap dalam mendesain, membangun, menguji, dan
mendokumentasikan API di lingkungan Solvera. API Developer bertanggung jawab memastikan
bahwa seluruh layanan memiliki kontrak yang konsisten, aman, scalable, dan mudah
diintegrasikan.

1. Mindset API Developer Solvera

API Developer harus memiliki pola pikir:

●​ API-first: API menjadi kontrak utama antara frontend, backend, dan sistem eksternal.​

●​ Stateless: Setiap request harus lengkap, tidak bergantung session.​

●​ Consistent: Format response seragam di seluruh microservices.​

●​ Secure: Terapkan validasi, rate limit, auth, dan sanitasi input.​

●​ Scalable: Siap dipisah, di-cache, di-paralelisasi.​

●​ Observability: API harus mudah dilacak (trace & log).​

2. Arsitektur API Solvera

Dalam project Solvera, API mengikuti struktur:

Frontend ([Link])
|
v
API Gateway (KrakenD / FastAPI Gateway)
|
------------------------------------------------
| | |
Auth API Domain API External API Integration
- Job Service - Odoo
- Contact Service - Payment Gateway
- Company Service - SMS/Email Gateway
- Timeline Service

Lapisan Arsitektur

1.​ API Gateway​

○​ Single entry point​

○​ Routing & versioning​

○​ Security & rate limit​

○​ Aggregation (jika perlu)​

2.​ Microservices API​

○​ FastAPI services berdasarkan domain​

○​ Independent deployment​

3.​ Integration Layer​

○​ API untuk 3rd-party systems​

4.​ Database & Cache Layer​

○​ Neon Postgres​

○​ Redis​

3. API Design Standards

3.1. Base URL Format
Semua API Solvera menggunakan format:

/api/v1/resource

Versioning wajib: v1, v2, v3.

3.2. Naming Convention

Endpoint Naming

Gunakan kata benda, bukan kata kerja.

Benar:

GET /api/v1/jobs
POST /api/v1/jobs
PUT /api/v1/jobs/{id}
DELETE /api/v1/jobs/{id}

Salah:

/getJobs
/createNewJob
/updateJobData

Resource Examples (Standar Solvera)

Domain Resource

Auth /login, /register, /refresh

Job Portal /jobs, /companies,

(SuperJob) /applicants

CRM (SuperContact) /contacts, /activities, /pipeline

Website /articles, /menu

4. Query Params Standard
Gunakan parameter standar untuk:

Pagination
?limit=20&offset=0

Sorting
?sort=created_at:desc

Filtering
?status=active&category=tech

Search
?search=software engineer

5. Request/Response Format Standar

5.1. Standard Request Body
●​ Gunakan snake_case untuk field internal.​

●​ Gunakan camelCase untuk API public jika diperlukan.​

Contoh:

{
"title": "Frontend Developer",
"companyId": 123,
"description": "Job description here..."
}

5.2. Standard Response Format (GLOBAL)

Seluruh API Solvera WAJIB menggunakan format berikut:

Success Response
{
"status": "success",
"message": "Job created successfully.",
"data": {
"id": 12,
"title": "Frontend Developer"
}
}

Error Response
{
"status": "error",
"message": "Email already exists.",
"code": 400
}

Paginated Response
{
"status": "success",
"data": [...],
"pagination": {
"total": 125,
"limit": 20,
"offset": 0
}
}
6. Authentication & Authorization
Solvera menggunakan JWT Auth (access + refresh token):

Token rules

●​ Access token 15–30 menit.​

●​ Refresh token 7–30 hari.​

●​ Simpan refresh token hashed di database.​

Auth Flow
POST /auth/login → return jwt + refresh_token
POST /auth/refresh → return new access token
POST /auth/logout → revoke refresh token

Protected Endpoint

Harus diakses dengan header:

Authorization: Bearer <token>

7. Request Validation (Pydantic)

Setiap request wajib melalui validator:

class JobCreate(BaseModel):
title: str = Field(..., min_length=3)
description: str
company_id: int

Gunakan Pydantic untuk:

●​ type checking​
 ●​ min/max validation​

●​ regex​

●​ optional fields​

8. API Documentation Standard

Gunakan OpenAPI 3.1.

Wajib memiliki:

✔ Summary​
✔ Description​
✔ Tags​
✔ Request body​
✔ Response model​
✔ Error model​
✔ Example values

Swagger otomatis di FastAPI:

●​ /docs​

●​ /redoc​

●​ /[Link]​

9. Performance Optimization
API Developer harus memahami:

Cache Strategy
 ●​ Redis for list endpoints​

●​ TTL based on domain (job list 30–60 sec)​

●​ Cache invalidation strategy​

Database Optimization

●​ Indexing field yang sering dicari​

●​ Batasi join​

●​ Use pagination​

N+1 Prevention

Gunakan eager loading jika perlu.

10. Rate Limiting

Untuk API publik, gunakan:

100 requests/minute per IP

Tools:

●​ API Gateway limit​

●​ Redis counter​

●​ FastAPI-limiter​

11. Error Handling Rules

Gunakan format standar:

raise HTTPException(
status_code=400,
detail="Invalid input"
)

Error harus ditangani:

●​ validation error​

●​ auth error​

●​ DB error​

●​ 3rd party error​

●​ gateway timeout​

12. Logging & Monitoring

Gunakan Loguru:

[Link]("Create job: id={id}")

[Link]("Slow query detected...")
[Link]("Failed to sync with Odoo")

Monitoring:

●​ Vercel logs (frontend)​

●​ CloudWatch / Grafana (backend)​

●​ Sentry (error tracking)​

13. API Versioning Strategy
Gunakan semver untuk API.

v1 → stable

v2 → new changes requiring breaking compatibility

Rules:

●​ Tidak boleh menghapus field tanpa version bump.​

●​ Tidak boleh mengganti struktur response tanpa version bump.​

14. API Testing Guide

Gunakan:

●​ pytest​

●​ httpx​

●​ pytest-asyncio​

Test wajib untuk:

●​ auth flow​

●​ CRUD resource​

●​ permission test​

●​ data validation​

Coverage minimal: 70%.

15. GitLab Repository Rules untuk API
Developer
Branching
main → production
develop → staging
feature/* → new API
bugfix/* → fix error
hotfix/* → urgent patch

Merge Request Checklist

●​ Endpoint & schema sesuai PRD​

●​ Swagger update​

●​ Unit test passed​

●​ Response format standar​

●​ Tidak ada hardcoded secret​

●​ Tidak push file .env​

16. API Gateway Guidelines (KrakenD /

FastAPI Gateway)
API Gateway harus menyediakan:

●​ Routing ke microservices​

●​ Aggregation endpoint (opsional)​

 ●​ CORS handling​

●​ Rate limit​

●​ Header validation​

●​ Unified error handling​

Contoh agregasi:

GET /api/v1/summary
→ fetch /users + /jobs + /contacts
→ return merged response

17. Integration API (Odoo / 3rd Party)

Aturan khusus:

●​ Gunakan adapter pattern​

●​ Retry mechanism (exponential backoff)​

●​ Logging lengkap​

●​ Timeout max 5–10 detik​

●​ Mapping field jelas​

Contoh payload:

{
"external_id": "odoo_123",
"name": "John Doe",
"email": "john@[Link]"
}
18. Security Best Practices
●​ Sanitasi input sebelum insert DB​

●​ Validasi semua request​

●​ Jangan pernah kirim password​

●​ Enkripsi data sensitif​

●​ Gunakan HTTPS​

●​ Implement header security:​

○​ X-Frame-Options​

○​ X-XSS-Protection​

○​ HSTS​

19. Checklist Kompetensi API Developer

Solvera
API Developer dinyatakan siap produksi jika sudah mampu:

✔ Mendesain API sesuai PRD + BDD​

✔ Membuat schema request/response​
✔ Menulis CRUD FastAPI modular​
✔ Menggunakan SQLAlchemy + Alembic​
✔ Mengimplementasikan JWT auth​
✔ Menghubungkan Redis cache​
✔ Membuat unit test API​
✔ Menggunakan GitLab MR workflow​
✔ Deploy API ke staging/production​
✔ Membuat dokumentasi OpenAPI lengkap
20. Bonus: Template Endpoint
Documentation (Siap Pakai)
# POST /api/v1/jobs

## Summary
Create new job posting.

## Description
Membuat data job baru untuk SuperJob.

## Request
{
"title": "Backend Developer",
"description": "Full-time remote",
"companyId": 7
}

## Response
{
"status": "success",
"data": {
"id": 21,
"title": "Backend Developer"
}
}

## Error
400 - invalid input
401 - unauthorized
500 - internal server error