LibrarySMKTI REST API v2

Dokumentasi API yang siap dipakai.

Referensi lengkap untuk menghubungkan website, aplikasi desktop Visual Studio C#, atau client lain ke API katalog buku LibrarySMKTI.

Base URL https://arpa.twelvepplg.my.id/api Version 2.0.0 Format JSON Auth Bearer Token
Semua contoh di halaman ini memakai placeholder token dan kredensial.
01 / Overview

Informasi dasar API

API v2 berjalan sebagai REST API PHP standalone dan dapat diakses langsung oleh aplikasi client melalui endpoint di folder /api.

Base URL
https://arpa.twelvepplg.my.id/api
API Version
2.0.0
Data Format
JSON / multipart/form-data
Status endpoint: GET /api/index.php mengembalikan nama API, versi, fitur, daftar endpoint, klasifikasi auth, dan aturan upload cover.
Request
curl https://arpa.twelvepplg.my.id/api/index.php
Example response
{
  "success": true,
  "message": "API aktif.",
  "data": {
    "name": "LibrarySMKTI REST API",
    "version": "2.0.0",
    "features": [
      "katalog buku + pencarian + filter kategori",
      "detail buku",
      "register + login + token bearer + data akun",
      "dashboard admin + statistik",
      "tambah/edit/hapus buku khusus admin",
      "upload dan penggantian cover JPG/JPEG/PNG maksimal 2 MB",
      "sinopsis buku"
    ],
    "endpoints": [
      "POST /register.php",
      "POST /login.php",
      "GET /me.php",
      "GET /categories.php",
      "GET /books.php",
      "GET /books.php?id={id}",
      "GET /stats.php",
      "POST /add.php",
      "PUT /edit.php?id={id}",
      "PATCH /edit.php?id={id}",
      "POST /edit.php?id={id} (multipart + cover)",
      "DELETE /delete.php?id={id}"
    ],
    "auth": {
      "public": ["register.php", "login.php", "books.php", "categories.php"],
      "bearer_required": ["me.php"],
      "admin_required": ["stats.php", "add.php", "edit.php", "delete.php"]
    },
    "cover": {
      "upload_field": "cover",
      "formats": ["jpg", "jpeg", "png"],
      "max_size_mb": 2,
      "public_base_path": "/perpussmkti/"
    }
  }
}
02 / Quick Start

Alur penggunaan paling umum

Gunakan /register.php bila perlu membuat akun baru, lalu /login.php untuk memperoleh Bearer Token. Katalog dan kategori dapat dibaca tanpa token; data akun membutuhkan token; statistik dan CRUD buku membutuhkan token admin.

STEP 01

Register / Login

Buat akun lewat /register.php atau login lewat /login.php.

STEP 02

Gunakan token

Ambil data.token dan kirim sebagai Authorization: Bearer TOKEN untuk endpoint akun dan admin.

STEP 03

Akses fitur

Katalog/kategori bersifat publik; statistik dan CRUD buku memerlukan akun admin.

03 / Response Format

Format response konsisten

Response sukses memakai success: true dan biasanya berisi message serta data. Response error memakai success: false.

Success

{
  "success": true,
  "message": "...",
  "data": { }
}

Error

{
  "success": false,
  "message": "..."
}
Untuk endpoint yang mengembalikan data buku, object buku memiliki cover_image dan cover_url. Jika cover tidak ada, cover_url diarahkan ke /perpussmkti/default-cover.svg.
04 / Authentication

Bearer Token

Endpoint akun /me.php memerlukan Bearer Token, sedangkan /stats.php, ADD, EDIT, dan DELETE memerlukan token dari user admin. Masa berlaku token saat ini adalah 24 jam.

POST/api/login.php
PUBLIC

Kirim JSON berisi username dan password.

Request
curl -X POST "https://arpa.twelvepplg.my.id/api/login.php" \\
  -H "Content-Type: application/json" \\
  -d '{
    "username": "YOUR_USERNAME",
    "password": "YOUR_PASSWORD"
  }'
Success response
{
  "success": true,
  "message": "Login berhasil.",
  "data": {
    "token": "TOKEN_DARI_SERVER",
    "token_type": "Bearer",
    "expires_in": 86400,
    "user": {
      "id": 1,
      "username": "YOUR_USERNAME",
      "is_admin": 1
    }
  }
}
Gunakan nilai data.token secara langsung pada header Authorization. Token diverifikasi menggunakan tanda tangan server dan waktu kedaluwarsa.
Authorization: Bearer TOKEN_DARI_SERVER
05 / Endpoints

Reference endpoint

Berikut seluruh endpoint yang tersedia berdasarkan implementasi API saat ini.

GET/api/books.php
PUBLIC

Mengambil daftar buku dengan optional search, category, pagination, atau mengambil satu buku memakai parameter id.

ParameterTypeDefaultKeterangan
idinteger—Jika diisi, API mengembalikan satu buku berdasarkan ID.
searchstring""Pencarian pada title, author, publisher, atau category.
categorystring""Filter kategori yang harus cocok dengan nilai category.
pageinteger1Nomor halaman, minimum 1.
limitinteger20Jumlah item per halaman, 1–100.
Examples
GET /api/books.php
GET /api/books.php?page=1&limit=20
GET /api/books.php?search=java&category=Pemrograman&page=1&limit=20
GET /api/books.php?id=1
List response
{
  "success": true,
  "message": "Daftar buku berhasil diambil.",
  "data": {
    "items": [
      {
        "id": 1,
        "title": "Belajar PHP",
        "author": "Gede Aditya Arpa",
        "publisher": "SMK TI",
        "year": 2026,
        "category": "Pemrograman",
        "synopsis": "Buku pembelajaran PHP.",
        "cover_image": "abc123.jpg",
        "cover_url": "https://arpa.twelvepplg.my.id/perpussmkti/uploads/abc123.jpg",
        "created_at": "2026-09-30 12:00:00"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "total_pages": 1
    }
  }
}
POST/api/register.php
PUBLIC

Membuat akun user biasa. Akun yang dibuat endpoint ini selalu memiliki is_admin = 0.

JSON body
{
  "username": "user_baru",
  "password": "1234",
  "password_confirm": "1234"
}
FieldAturan
username3–30 karakter, hanya huruf, angka, underscore. Username arpa dicadangkan untuk admin.
passwordMinimal 4 karakter.
password_confirmHarus sama dengan password.
Success response
{
  "success": true,
  "message": "Akun berhasil dibuat. Silakan login.",
  "data": {
    "id": 2,
    "username": "user_baru",
    "is_admin": 0
  }
}
POST/api/login.php
PUBLIC

Validasi akun dan membuat Bearer Token.

JSON body
{
  "username": "YOUR_USERNAME",
  "password": "YOUR_PASSWORD"
}

Response sukses berisi token, token_type, expires_in, dan informasi user.

GET/api/me.php
BEARER TOKEN

Mengambil identitas user yang terkait dengan token aktif.

GET /api/me.php
Authorization: Bearer TOKEN_DARI_SERVER
{
  "success": true,
  "message": "Data akun ditemukan.",
  "data": {
    "id": 1,
    "username": "arpa",
    "is_admin": 1,
    "created_at": "2026-09-30 12:00:00"
  }
}
GET/api/categories.php
PUBLIC

Mengambil semua kategori yang sedang dipakai buku beserta jumlah bukunya. Endpoint ini public dan tidak membutuhkan Bearer Token.

GET /api/categories.php
{
  "success": true,
  "message": "Daftar kategori berhasil diambil.",
  "data": {
    "items": [
      { "name": "Pemrograman", "book_count": 12 },
      { "name": "Novel", "book_count": 7 }
    ],
    "total": 2
  }
}
GET/api/stats.php
ADMIN TOKEN

Mengambil statistik dashboard admin: total buku, total kategori, dan 10 buku terbaru.

GET /api/stats.php
Authorization: Bearer ADMIN_TOKEN
{
  "success": true,
  "message": "Statistik dashboard berhasil diambil.",
  "data": {
    "total_books": 25,
    "total_categories": 4,
    "latest_books": [
      {
        "id": 25,
        "title": "Buku Terbaru",
        "author": "Author",
        "year": 2026,
        "category": "Pemrograman",
        "cover_image": "abc.jpg",
        "cover_url": "https://arpa.twelvepplg.my.id/perpussmkti/uploads/abc.jpg",
        "created_at": "2026-09-30 12:00:00"
      }
    ]
  }
}
POST/api/add.php
ADMIN TOKEN

Menambahkan buku baru. Endpoint menerima JSON atau multipart/form-data. Multipart dipakai bila mengunggah cover.

JSON tanpa cover

POST /api/add.php
Content-Type: application/json
Authorization: Bearer TOKEN

{
  "title": "Belajar PHP",
  "author": "Gede Aditya Arpa",
  "publisher": "SMK TI",
  "year": 2026,
  "category": "Pemrograman",
  "synopsis": "Buku pembelajaran PHP."
}

Multipart + cover

POST /api/add.php
Content-Type: multipart/form-data
Authorization: Bearer TOKEN

Form fields:
title
author
publisher
year
category
synopsis
cover = JPG/JPEG/PNG, max 2 MB
cURL JSON
curl -X POST "https://arpa.twelvepplg.my.id/api/add.php" \\
  -H "Authorization: Bearer TOKEN_DARI_SERVER" \\
  -H "Content-Type: application/json" \\
  -d '{
    "title": "Belajar PHP",
    "author": "Gede Aditya Arpa",
    "publisher": "SMK TI",
    "year": 2026,
    "category": "Pemrograman",
    "synopsis": "Buku pembelajaran PHP."
  }'
cURL multipart
curl -X POST "https://arpa.twelvepplg.my.id/api/add.php" \\
  -H "Authorization: Bearer TOKEN_DARI_SERVER" \\
  -F "title=Belajar PHP" \\
  -F "author=Gede Aditya Arpa" \\
  -F "publisher=SMK TI" \\
  -F "year=2026" \\
  -F "category=Pemrograman" \\
  -F "synopsis=Buku pembelajaran PHP." \\
  -F "cover=@C:/gambar/cover.jpg"
PUTPATCH/api/edit.php?id={id}
ADMIN TOKEN

Mengubah sebagian atau beberapa field buku. Untuk PUT/PATCH, body JSON hanya berisi field yang ingin diubah.

PUT /api/edit.php?id=1
Authorization: Bearer TOKEN
Content-Type: application/json

{
  "title": "Belajar PHP Lanjutan",
  "category": "Backend"
}
Field yang tidak dikirim tidak diubah. Namun bila memakai POST /edit.php?id={id}, implementasi API mengharuskan upload cover sekaligus.
POST multipart + cover
POST /api/edit.php?id=1
Authorization: Bearer TOKEN
Content-Type: multipart/form-data

Form fields yang boleh dikirim:
title
author
publisher
year
category
synopsis
cover = JPG/JPEG/PNG, max 2 MB

Saat cover baru berhasil tersimpan, cover lama akan dihapus.

DELETE/api/delete.php?id={id}
ADMIN TOKEN

Menghapus buku berdasarkan ID. Jika buku memiliki cover, file cover tersebut juga dihapus.

curl -X DELETE "https://arpa.twelvepplg.my.id/api/delete.php?id=1" \\
  -H "Authorization: Bearer TOKEN_DARI_SERVER"
Success response
{
  "success": true,
  "message": "Buku berhasil dihapus.",
  "data": { "id": 1 }
}
06 / Book Schema

Field buku & validasi

Validasi berikut berasal dari fungsi validasi pada API. Pada mode edit, semua field bersifat opsional karena update bersifat partial.

FieldTypeWajib saat createBatas / aturan
titlestringYaMaks. 255 karakter.
authorstringYaMaks. 150 karakter.
publisherstring / nullTidakMaks. 150 karakter jika diisi.
yearinteger / nullTidakHarus angka; rentang dimulai 1000 hingga tahun berjalan + 1.
categorystring / nullTidakMaks. 100 karakter.
synopsisstring / nullTidakMaks. 5000 karakter.
coverfileTidakJPG/JPEG/PNG, maksimum 2 MB, harus merupakan gambar valid.
Field selain title, author, publisher, year, category, dan synopsis ditolak dengan HTTP 422.
Cover disimpan di path publik /perpussmkti/uploads/. Jika cover_image kosong, API mengembalikan https://arpa.twelvepplg.my.id/perpussmkti/default-cover.svg sebagai cover_url.
07 / Errors

HTTP status & penanganan error

API mengembalikan JSON error dengan pola success: false dan pesan yang menjelaskan masalah.

204OPTIONS / preflight berhasil; tanpa body.
400Request atau parameter wajib tidak valid.
401Bearer token hilang/tidak valid/kedaluwarsa atau login gagal.
403Token valid tetapi akun bukan admin.
404Resource, misalnya buku berdasarkan ID, tidak ditemukan.
405HTTP method tidak sesuai dengan endpoint.
409Konflik data, misalnya username registrasi sudah digunakan.
422Field atau isi data gagal validasi.
500Kesalahan database, upload, atau server internal.
Example
{
  "success": false,
  "message": "Authorization Bearer token diperlukan."
}
08 / CORS & OPTIONS

Akses lintas origin

API saat ini mengizinkan CORS dari semua origin dan mendeklarasikan header serta method yang digunakan.

Allowed origin

Access-Control-Allow-Origin: *

Allowed headers

Content-Type, Authorization, X-API-Key

Allowed methods

GET, POST, PUT, PATCH, DELETE, OPTIONS

Request OPTIONS dijawab dengan HTTP 204. Ini mendukung preflight request browser sebelum request API tertentu.
09 / C# Integration

Contoh pemakaian Visual Studio C#

Paket API v2 menyertakan LibraryApiClient.cs untuk .NET. Client mencakup register, login, identitas akun, kategori, statistik admin, katalog/detail buku, tambah, edit, dan hapus. Base URL client adalah https://arpa.twelvepplg.my.id/api.

Initialize client
using LibrarySMKTI;

using var api = new LibraryApiClient(
    "https://arpa.twelvepplg.my.id/api");
Login + get books
var login = await api.LoginAsync(
    "YOUR_USERNAME",
    "YOUR_PASSWORD");

Console.WriteLine(login.Message);

var books = await api.GetBooksAsync(
    search: "php",
    category: "Pemrograman",
    page: 1,
    limit: 20);

foreach (var book in books.Data?.Items ?? [])
{
    Console.WriteLine(
        $"{book.Id} - {book.Title} - {book.Author}");
}
Register / account / categories / stats
var registered = await api.RegisterAsync(
    "user_baru",
    "1234",
    "1234");

var loginAfterRegister = await api.LoginAsync(
    "user_baru",
    "1234");

var me = await api.GetCurrentUserAsync();
var categories = await api.GetCategoriesAsync();

if (me.Data?.IsAdmin == 1)
{
    var stats = await api.GetDashboardStatsAsync();
    Console.WriteLine($"Total buku: {stats.Data?.TotalBooks}");
}
Create / update / delete
var created = await api.CreateBookAsync(new BookCreate
{
    Title = "Buku Baru dari C#",
    Author = "Admin C#",
    Publisher = "SMKTI",
    Year = 2026,
    Category = "Pemrograman",
    Synopsis = "Data dibuat dari aplikasi Visual Studio C#."
});

if (created.Data is not null)
{
    var updated = await api.UpdateBookAsync(
        created.Data.Id,
        new BookUpdate
        {
            Title = "Buku Baru dari C# - Updated"
        });

    var deleted = await api.DeleteBookAsync(
        created.Data.Id);
}
Client C# menyimpan token hasil login secara internal pada property Token, lalu menambahkan header Bearer untuk request yang membutuhkan autentikasi.
10 / Security Notes

Catatan untuk deployment

Halaman ini mendokumentasikan kontrak API, bukan tempat menyimpan secret server.

Jangan publikasikan credential database atau API signing secret. Nilai rahasia yang berada di file konfigurasi server tidak ditampilkan di dokumentasi publik ini.

Token

  • Berlaku 24 jam pada konfigurasi API saat ini.
  • Gunakan header Authorization: Bearer ....
  • Jangan commit token aktif ke repository atau frontend publik.

Account

  • Operasi tulis memerlukan user dengan flag admin.
  • Login gagal menghasilkan HTTP 401.
  • Token valid non-admin menghasilkan HTTP 403.
Contoh username/password di source client diperlakukan sebagai contoh saja. Gunakan akun yang memang tersedia di database deployment Anda dan jangan memasukkan password nyata ke source publik.
Catatan implementasi v2: file login.php dan register.php pada paket saat ini membandingkan/menyimpan password secara langsung. Untuk deployment production, pertimbangkan migrasi ke hashing password seperti password_hash() dan password_verify().