📍 Endpoint Registry

KNETEndpointRegistry to centralne repozytorium definicji endpointów API. Type-safe, z walidacją i dokumentacją w kodzie.

📦 Import

import rip.nerd.kitsunenet.util.KNETEndpointRegistry
import rip.nerd.kitsunenet.util.endpoints

🚀 Szybki start

// Definiuj endpointy jako object
object ApiEndpoints : KNETEndpointRegistry("https://api.example.com") {

    // GET endpoints
    val getUsers = GET("/users", description = "Lista użytkowników")
    val getUser = GET("/users/{id}", description = "Szczegóły użytkownika")

    // POST endpoints
    val createUser = POST("/users", description = "Tworzenie użytkownika")

    // PUT/PATCH endpoints
    val updateUser = PUT("/users/{id}")
    val patchUser = PATCH("/users/{id}")

    // DELETE endpoints
    val deleteUser = DELETE("/users/{id}")

    // Z query params
    val searchUsers = GET("/users/search", query = listOf("q", "page", "limit"))
}

// Użycie
val request = ApiEndpoints.getUser.request("id" to "123")
val response = client.request(request)

🔗 Path Parameters

// Definiuj z {param}
val getUser = GET("/users/{id}")
val getOrder = GET("/users/{userId}/orders/{orderId}")

// Użycie z mapą
val request = ApiEndpoints.getUser.request(
    pathParams = mapOf("id" to "123")
)

// Lub z vararg
val request = ApiEndpoints.getUser.request("id" to "123")

// Wiele parametrów
val request = ApiEndpoints.getOrder.request(
    "userId" to "123",
    "orderId" to "456"
)

// URL: https://api.example.com/users/123/orders/456

🔍 Query Parameters

// Definiuj dozwolone query params
val searchUsers = GET("/users/search", query = listOf("q", "page", "limit"))

// Użycie
val request = ApiEndpoints.searchUsers.request(
    query = mapOf(
        "q" to "john",
        "page" to "1",
        "limit" to "20"
    )
)

// URL: https://api.example.com/users/search?q=john&page=1&limit=20

📤 Request z Body

val createUser = POST("/users")

// Z mapą jako body
val request = ApiEndpoints.createUser.request(
    body = mapOf(
        "name" to "John Doe",
        "email" to "john@example.com"
    )
)

// Z obiektem jako body
val request = ApiEndpoints.createUser.request(
    body = CreateUserRequest(name = "John", email = "john@example.com")
)

// Path params + body
val updateUser = PUT("/users/{id}")

val request = ApiEndpoints.updateUser.request(
    pathParams = mapOf("id" to "123"),
    body = mapOf("name" to "Updated Name")
)

🔧 Konfiguracja

Headers dla endpointu

// Wymagane headers dla endpointu
val protectedEndpoint = register(
    method = "GET",
    path = "/admin/users",
    headers = mapOf("X-Admin-Token" to "required"),
    description = "Admin endpoint"
)

Deprecation

val oldEndpoint = register(
    method = "GET",
    path = "/v1/users",
    deprecated = true,
    description = "Use /v2/users instead"
)

Wersjonowanie

val getUserV2 = register(
    method = "GET",
    path = "/v2/users/{id}",
    version = "2.0"
)

🌍 Zmiana Base URL

// Dla różnych środowisk
object ApiEndpoints : KNETEndpointRegistry("https://api.example.com") {
    // ...endpoints
}

// Development
if (BuildConfig.DEBUG) {
    ApiEndpoints.setBaseUrl("https://dev-api.example.com")
}

// Staging
if (BuildConfig.FLAVOR == "staging") {
    ApiEndpoints.setBaseUrl("https://staging-api.example.com")
}

// Pobierz aktualny base URL
val currentBase = ApiEndpoints.getBaseUrl()

🔄 Wykonywanie requestów

// Metoda 1: Buduj request, potem wykonaj
val request = ApiEndpoints.getUser.request("id" to "123")
val response = client.request(request)

// Metoda 2: Wykonaj bezpośrednio
val response = ApiEndpoints.getUser.execute(
    client = client,
    pathParams = mapOf("id" to "123")
)

// Z query i headers
val response = ApiEndpoints.searchUsers.execute(
    client = client,
    query = mapOf("q" to "john"),
    headers = mapOf("Accept-Language" to "pl")
)

📄 Dokumentacja

// Generuj dokumentację wszystkich endpointów
val docs = ApiEndpoints.generateDocs()
println(docs)

// Output:
// # API Endpoints
// Base URL: https://api.example.com
//
// ## GET
// - /users - Lista użytkowników
// - /users/{id} - Szczegóły użytkownika
//   Path params: [id]
// ...

// Lista wszystkich endpointów
val all = ApiEndpoints.getAllEndpoints()

// Znajdź po nazwie
val endpoint = ApiEndpoints.findEndpoint("GET_users_{id}")

// Znajdź po path pattern
val userEndpoints = ApiEndpoints.findByPath(Regex("/users"))

// Lista zdeprecjonowanych
val deprecated = ApiEndpoints.getDeprecatedEndpoints()

💡 Praktyczne przykłady

Pełne API

object MyApi : KNETEndpointRegistry("https://api.myapp.com/v1") {

    // Auth
    val login = POST("/auth/login")
    val logout = POST("/auth/logout")
    val refreshToken = POST("/auth/refresh")

    // Users
    val getUsers = GET("/users", query = listOf("page", "limit", "sort"))
    val getUser = GET("/users/{id}")
    val createUser = POST("/users")
    val updateUser = PUT("/users/{id}")
    val deleteUser = DELETE("/users/{id}")

    // Orders
    val getUserOrders = GET("/users/{userId}/orders")
    val getOrder = GET("/orders/{id}")
    val createOrder = POST("/orders")
    val cancelOrder = POST("/orders/{id}/cancel")

    // Products
    val getProducts = GET("/products", query = listOf("category", "search", "page"))
    val getProduct = GET("/products/{id}")
}

Użycie w Repository

class UserRepository(private val client: KNETClient) {

    suspend fun getUsers(page: Int, limit: Int): List<User> {
        val response = MyApi.getUsers.execute(
            client = client,
            query = mapOf("page" to page.toString(), "limit" to limit.toString())
        )
        return response.jsonList()
    }

    suspend fun getUser(id: String): User {
        val response = MyApi.getUser.execute(
            client = client,
            pathParams = mapOf("id" to id)
        )
        return response.json()
    }

    suspend fun createUser(user: CreateUserRequest): User {
        val response = MyApi.createUser.execute(
            client = client,
            body = user.toMap()
        )
        return response.json()
    }
}

🔗 API Reference

KNETEndpointRegistry

Endpoint

📚 Zobacz też