Fibermedia API Freeze Specification v2.1

Fibermedia API Docs v2.1 Frozen

Documentation API Freeze Specification Raw JSON

# Fibermedia Provisioning System - API Freeze Declaration

**Status**: 🔒 **FROZEN (v2.1)**  
**Effective Date**: 4 Agustus 2026  
**Target Clients**: Web Admin CMS, Mobile App Sales, Mobile App Teknisi

---

## 1. Pernyataan API Freeze (API Freeze Policy)

Dokumen ini secara resmi menyatakan bahwa seluruh antarmuka pemrograman aplikasi (**REST API v2.1**) untuk **Fibermedia Provisioning System** berada dalam status **API Freeze**.

### Ketentuan API Freeze:
1. **Kontrak API Terkunci (Contract Immutability)**:
   Seluruh struktur URL Endpoint, Metode HTTP, Header, Format JSON Request Body, Query Parameter, dan Struktur Response JSON (termasuk tipe data dan kunci nama atribut) **TIDAK BOLEH** diubah tanpa versi mayor baru (`/api/v3/`).
2. **Tidak Ada Breaking Changes**:
   Klien Frontend (Web Admin, Mobile Sales, Mobile Teknisi) dapat membangun dan menggunakan seluruh endpoint sesuai spesifikasi resmi tanpa khawatir adanya perubahan nama field, perubahan tipe data, atau pergeseran status code HTTP.
3. **Penambahan Fitur (Non-breaking Additions)**:
   Penambahan field opsional di masa mendatang pada response JSON yang bersifat *backward compatible* diperbolehkan dengan persetujuan dokumentasi terlebih dahulu.

---

## 2. Ringkasan Modul & Cakupan Endpoint Terkunci

---

## 3. Standar Status Code HTTP Terkunci

- `200 OK`: Request sukses (Mengembalikan data tunggal atau paginasi).
- `201 Created`: Resource baru berhasil dibuat.
- `400 Bad Request`: Parameter request tidak valid atau alur bisnis menyalahi syarat (*workflow transition error*).
- `401 Unauthorized`: Token Bearer tidak valid, kadaluarsa, atau status akun non-aktif.
- `403 Forbidden`: Pengguna tidak memiliki Role/Permission yang sesuai.
- `404 Not Found`: Resource tidak ditemukan di database.
- `409 Conflict`: Konflik data unik (misal: duplikasi username BFASS atau duplikasi pendaftaran).
- `422 Unprocessable Content`: Validasi input gagal (Format rincian error `errors: { field: ["reason"] }`).
- `429 Too Many Requests`: Melebihi batas Rate Limiting (Throttle limit).
- `500 Internal Server Error`: Kesalahan tidak terduga pada server.

---

## 4. Standar Amplop Response (Response Envelopes)

### Single Resource Response
```json
{
  "success": true,
  "message": "Resource action message",
  "data": {
    "id": 1,
    "field": "value"
  }
}
```

### Paginated Collection Response (Standard Laravel Pagination)
```json
{
  "data": [
    { "id": 1, "field": "value" }
  ],
  "links": {
    "first": "http://localhost:8000/api/endpoint?page=1",
    "last": "http://localhost:8000/api/endpoint?page=5",
    "prev": null,
    "next": "http://localhost:8000/api/endpoint?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "per_page": 15,
    "to": 15,
    "total": 75
  }
}
```

### Error Response
```json
{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "email": [
      "The email field is required."
    ]
  }
}
```

---
*Penutupan Spesifikasi API Freeze v2.1 - PT Fibermedia Indonesia.*