Ekstensi Custom Endpoint

Sejoli API dapat menjadi lapisan autentikasi dan session untuk endpoint tambahan milik snippet, custom module, atau plugin lain. Karena itu, tidak semua endpoint di bawah /wp-json/sejoli/v1/me/* harus berasal dari plugin Sejoli API.

Pembagian Tanggung Jawab

Aktifnya Sejoli API tidak menjamin semua custom route tersedia. Deployment frontend harus memiliki daftar dependency module yang jelas atau menangani response 404 rest_no_route sebagai fitur yang tidak tersedia.

Hook Registrasi Route

Gunakan action berikut agar route didaftarkan setelah namespace utama Sejoli API siap:

add_action(
    'sejoli_api_after_register_routes',
    function ( string $namespace, $api ) {
        register_rest_route(
            $namespace,
            '/me/example-items',
            array(
                'methods'             => WP_REST_Server::READABLE,
                'permission_callback' => 'sejoli_api_require_authenticated',
                'callback'            => function ( WP_REST_Request $request ) {
                    $user = sejoli_api_require_authenticated_user( $request );
                    if ( is_wp_error( $user ) ) {
                        return $user;
                    }

                    return rest_ensure_response(
                        array(
                            'success' => true,
                            'data'    => array(),
                            'meta'    => array(
                                'effective_user_id' => (int) $user->ID,
                            ),
                        )
                    );
                },
            )
        );
    },
    10,
    2
);

Nilai $namespace saat ini adalah:

sejoli/v1

Gunakan nilai yang diberikan hook, bukan menulis namespace secara hardcoded, agar ekstensi mengikuti kontrak registrasi Sejoli API.

Helper Autentikasi

User-session biasa

Gunakan:

'permission_callback' => 'sejoli_api_require_authenticated'

Di dalam callback, ambil user kanonis melalui:

$user = sejoli_api_require_authenticated_user( $request );

Helper tersebut:

1. memverifikasi Bearer JWT;
2. mengambil WordPress user ID dari claim sub;
3. memastikan user masih tersedia;
4. menjalankan wp_set_current_user() untuk user efektif.

Jangan menerima user_id atau affiliate_id dari frontend sebagai identitas utama. Identitas harus berasal dari JWT.

Direct administrator

Untuk operasi sensitif yang hanya boleh dijalankan administrator asli, gunakan:

'permission_callback' => 'sejoli_api_require_direct_admin'

Helper ini menolak:

• user tanpa capability manage_options;
• session hasil user switching;
• session impersonation.

Jika custom module memiliki capability khusus, buat permission callback sendiri yang terlebih dahulu memanggil sejoli_api_require_authenticated_user(), kemudian periksa capability dengan user_can().

Contoh Capability Khusus

function my_module_require_manager( WP_REST_Request $request ) {
    $user = sejoli_api_require_authenticated_user( $request );
    if ( is_wp_error( $user ) ) {
        return $user;
    }

    if ( ! user_can( $user->ID, 'manage_my_module' ) ) {
        return new WP_Error(
            'rest_forbidden',
            'Anda tidak memiliki izin untuk fitur ini.',
            array( 'status' => 403 )
        );
    }

    return true;
}

Kontrak yang Harus Dimiliki Custom Module

Setiap custom module sebaiknya mendokumentasikan:

• plugin/module pemilik route;
• method dan path;
• dependency dan versi minimum;
• role atau capability yang diperlukan;
• parameter, pagination, dan filter;
• format response sukses;
• daftar error;
• side effect dan idempotency untuk operasi tulis.

Disarankan menggunakan pola response yang konsisten:

{
  "success": true,
  "data": [],
  "meta": {
    "effective_user_id": 35,
    "pagination": {
      "page": 1,
      "per_page": 25,
      "total": 0,
      "total_pages": 0
    }
  }
}

Keamanan

• Jangan menerbitkan API key ke browser atau Telegram Mini App.
• Gunakan user-session JWT untuk /me/*.
• Jangan mempercayai role gating pada frontend.
• Periksa ownership resource di server, bukan hanya capability umum.
• Sanitasi parameter melalui args route dan validasi ulang aturan bisnis di callback.
• Untuk endpoint admin, pertimbangkan apakah impersonated session harus ditolak.

Integrasi Frontend

Frontend dapat memanggil custom endpoint dengan token yang sama:

GET /wp-json/sejoli/v1/me/example-items
Authorization: Bearer <user_session_token>
Accept: application/json

Jika module opsional tidak aktif, WordPress biasanya mengembalikan 404 dengan code rest_no_route. Perlakukan kondisi tersebut sebagai fitur/module tidak tersedia, bukan sebagai session yang kedaluwarsa.