API Design: Resources, Pagination, Errors

Copy code# WRONG — verbs in URL
GET  /getUsers
POST /createUser
POST /deleteUser/42

# CORRECT — nouns, HTTP methods carry the action
GET    /users          → list users
POST   /users          → create a user
GET    /users/42       → get user 42
PUT    /users/42       → replace user 42
PATCH  /users/42       → partial update user 42
DELETE /users/42       → delete user 42

Copy codeGET  /users/42/orders          → orders belonging to user 42
GET  /users/42/orders/7        → order 7 of user 42
POST /users/42/orders          → create an order for user 42

Copy code// Common status codes and their meanings

// 2xx — success
200 OK              // GET, PUT, PATCH success
201 Created         // POST success with new resource
204 No Content      // DELETE success, no body to return

// 3xx — redirect
301 Moved Permanently    // resource URL has changed
304 Not Modified         // cache hit; use cached response

// 4xx — client error (caller's fault)
400 Bad Request          // malformed request body/params
401 Unauthorized         // missing or invalid authentication
403 Forbidden            // authenticated but not authorized
404 Not Found            // resource does not exist
409 Conflict             // state conflict (e.g., duplicate email)
422 Unprocessable Entity // valid JSON, but semantically invalid (validation failed)
429 Too Many Requests    // rate limit exceeded

// 5xx — server error (server's fault)
500 Internal Server Error  // unexpected server failure
502 Bad Gateway            // upstream service error
503 Service Unavailable    // server overloaded or down for maintenance
504 Gateway Timeout        // upstream timeout

Copy codeGET /products?page=2&per_page=20
GET /products?offset=40&limit=20

Copy code{
  "data": [...],
  "pagination": {
    "total": 1500,
    "page": 2,
    "per_page": 20,
    "total_pages": 75
  }
}

Copy codeGET /posts?limit=20
GET /posts?limit=20&cursor=eyJpZCI6MTAwfQ==

Copy code{
  "data": [...],
  "next_cursor": "eyJpZCI6ODB9",
  "prev_cursor": "eyJpZCI6MTAxfQ==",
  "has_next": true,
  "has_prev": false
}

Copy code// Retrofit interface for cursor-based pagination
interface PostApi {
    @GET("posts")
    suspend fun getPosts(
        @Query("limit") limit: Int,
        @Query("cursor") cursor: String? = null
    ): PagedResponse<Post>
}

data class PagedResponse<T>(
    val data: List<T>,
    val nextCursor: String?,
    val hasPrev: Boolean
)

// PagingSource implementation
class PostPagingSource(
    private val api: PostApi
) : PagingSource<String, Post>() {

    override suspend fun load(params: LoadParams<String>): LoadResult<String, Post> {
        return try {
            val response = api.getPosts(
                limit = params.loadSize,
                cursor = params.key    // null for first page
            )
            LoadResult.Page(
                data = response.data,
                prevKey = null,        // cursor-based: no backward paging
                nextKey = response.nextCursor
            )
        } catch (e: IOException) {
            LoadResult.Error(e)
        } catch (e: HttpException) {
            LoadResult.Error(e)
        }
    }

    override fun getRefreshKey(state: PagingState<String, Post>): String? = null
}

Copy code{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The request contains invalid fields",
    "details": [
      {
        "field": "email",
        "code": "ALREADY_TAKEN",
        "message": "This email address is already registered"
      },
      {
        "field": "username",
        "code": "TOO_SHORT",
        "message": "Username must be at least 3 characters"
      }
    ],
    "request_id": "req_abc123"
  }
}

Copy codesealed class NetworkResult<out T> {
    data class Success<T>(val data: T) : NetworkResult<T>()
    data class Error(
        val code: Int,
        val errorBody: ApiError?,
        val throwable: Throwable? = null
    ) : NetworkResult<Nothing>()
    object Loading : NetworkResult<Nothing>()
}

data class ApiError(
    val code: String,
    val message: String,
    val details: List<FieldError>? = null,
    val requestId: String? = null
)

data class FieldError(
    val field: String,
    val code: String,
    val message: String
)

Copy code// Retrofit setup
interface UserApi {
    @POST("users")
    suspend fun createUser(@Body request: CreateUserRequest): UserResponse
}

data class CreateUserRequest(val name: String, val email: String)
data class UserResponse(val id: String, val name: String, val email: String)

// Generic safe API call wrapper
suspend inline fun <reified T> safeApiCall(
    crossinline call: suspend () -> T
): NetworkResult<T> {
    return try {
        NetworkResult.Success(call())
    } catch (e: HttpException) {
        val errorBody = parseErrorBody(e)
        NetworkResult.Error(code = e.code(), errorBody = errorBody, throwable = e)
    } catch (e: IOException) {
        NetworkResult.Error(code = -1, errorBody = null, throwable = e)
    } catch (e: Exception) {
        NetworkResult.Error(code = -1, errorBody = null, throwable = e)
    }
}

fun parseErrorBody(e: HttpException): ApiError? {
    return try {
        val errorJson = e.response()?.errorBody()?.string() ?: return null
        val moshi = Moshi.Builder().build()
        val adapter = moshi.adapter(ApiErrorWrapper::class.java)
        adapter.fromJson(errorJson)?.error
    } catch (parseException: Exception) {
        null
    }
}

data class ApiErrorWrapper(val error: ApiError)

// Usage in Repository
class UserRepository @Inject constructor(private val api: UserApi) {

    suspend fun createUser(name: String, email: String): NetworkResult<UserResponse> {
        return safeApiCall { api.createUser(CreateUserRequest(name, email)) }
    }
}

// Usage in ViewModel
fun createUser(name: String, email: String) {
    viewModelScope.launch {
        _uiState.update { it.copy(isLoading = true) }

        when (val result = userRepository.createUser(name, email)) {
            is NetworkResult.Success -> {
                _uiState.update { it.copy(isLoading = false, user = result.data) }
            }
            is NetworkResult.Error -> {
                val errorMsg = when {
                    result.code == 422 -> {
                        // Show field-specific validation errors
                        result.errorBody?.details
                            ?.joinToString("\n") { "${it.field}: ${it.message}" }
                            ?: "Validation failed"
                    }
                    result.code == 409 -> "Email already taken"
                    result.throwable is IOException -> "No internet connection"
                    else -> "Something went wrong (${result.code})"
                }
                _uiState.update { it.copy(isLoading = false, errorMessage = errorMsg) }
            }
            is NetworkResult.Loading -> Unit
        }
    }
}

Copy codeinterface ProductApi {
    @GET("products")
    suspend fun getProducts(
        @Query("category") category: String? = null,
        @Query("min_price") minPrice: Double? = null,
        @Query("max_price") maxPrice: Double? = null,
        @Query("sort") sort: String = "newest",
        @Query("page") page: Int = 1,
        @Query("per_page") perPage: Int = 20
    ): PagedResponse<Product>

    // List parameters — Retrofit encodes as ?tags=a&tags=b
    @GET("products/search")
    suspend fun search(
        @Query("q") query: String,
        @Query("tags") tags: List<String>
    ): SearchResponse<Product>
}