refactor: standardize API error handling (#1635)

backend/internal/api/handler.go

@@ -6,6 +6,7 @@ import (
 	"github.com/gin-gonic/gin"
 
 	"github.com/pocket-id/pocket-id/backend/internal/dto"
+	"github.com/pocket-id/pocket-id/backend/internal/httpserver"
 	"github.com/pocket-id/pocket-id/backend/internal/utils"
 )
 
@@ -29,22 +30,20 @@ func newHandler(service *Service) *handler {
 // @Param sort[direction] query string false "Sort direction (asc or desc)" default("asc")
 // @Success 200 {object} dto.Paginated[apiResponseDto]
 // @Router /api/apis [get]
-func (h *handler) list(c *gin.Context) {
+func (h *handler) list(c *gin.Context) error {
 	search := c.Query("search")
 	listRequestOptions := utils.ParseListRequestOptions(c)
 
 	apis, pagination, err := h.service.List(c.Request.Context(), search, listRequestOptions)
 	if err != nil {
-		_ = c.Error(err)
-		return
+		return err
 	}
 
 	items := make([]apiResponseDto, len(apis))
 	for i, api := range apis {
 		var item apiResponseDto
 		if err := dto.MapStruct(api, &item); err != nil {
-			_ = c.Error(err)
-			return
+			return err
 		}
 		item.Resource = api.Audience
 		items[i] = item
@@ -54,6 +53,7 @@ func (h *handler) list(c *gin.Context) {
 		Data:       items,
 		Pagination: pagination,
 	})
+	return nil
 }
 
 // get godoc
@@ -64,14 +64,13 @@ func (h *handler) list(c *gin.Context) {
 // @Param id path string true "API ID"
 // @Success 200 {object} apiResponseDto
 // @Router /api/apis/{id} [get]
-func (h *handler) get(c *gin.Context) {
+func (h *handler) get(c *gin.Context) error {
 	api, err := h.service.Get(c.Request.Context(), nil, c.Param("id"))
 	if err != nil {
-		_ = c.Error(err)
-		return
+		return err
 	}
 
-	h.respond(c, http.StatusOK, api)
+	return h.respond(c, http.StatusOK, api)
 }
 
 // create godoc
@@ -83,20 +82,18 @@ func (h *handler) get(c *gin.Context) {
 // @Param api body apiCreateDto true "API information"
 // @Success 201 {object} apiResponseDto "Created API"
 // @Router /api/apis [post]
-func (h *handler) create(c *gin.Context) {
+func (h *handler) create(c *gin.Context) error {
 	var input apiCreateDto
-	if err := dto.ShouldBindWithNormalizedJSON(c, &input); err != nil {
-		_ = c.Error(err)
-		return
+	if err := httpserver.BindJSON(c, &input); err != nil {
+		return err
 	}
 
 	api, err := h.service.Create(c.Request.Context(), input)
 	if err != nil {
-		_ = c.Error(err)
-		return
+		return err
 	}
 
-	h.respond(c, http.StatusCreated, api)
+	return h.respond(c, http.StatusCreated, api)
 }
 
 // update godoc
@@ -109,20 +106,18 @@ func (h *handler) create(c *gin.Context) {
 // @Param api body apiUpdateDto true "API information"
 // @Success 200 {object} apiResponseDto "Updated API"
 // @Router /api/apis/{id} [put]
-func (h *handler) update(c *gin.Context) {
+func (h *handler) update(c *gin.Context) error {
 	var input apiUpdateDto
-	if err := dto.ShouldBindWithNormalizedJSON(c, &input); err != nil {
-		_ = c.Error(err)
-		return
+	if err := httpserver.BindJSON(c, &input); err != nil {
+		return err
 	}
 
 	api, err := h.service.Update(c.Request.Context(), c.Param("id"), input)
 	if err != nil {
-		_ = c.Error(err)
-		return
+		return err
 	}
 
-	h.respond(c, http.StatusOK, api)
+	return h.respond(c, http.StatusOK, api)
 }
 
 // delete godoc
@@ -132,13 +127,13 @@ func (h *handler) update(c *gin.Context) {
 // @Param id path string true "API ID"
 // @Success 204 "No Content"
 // @Router /api/apis/{id} [delete]
-func (h *handler) delete(c *gin.Context) {
+func (h *handler) delete(c *gin.Context) error {
 	if err := h.service.Delete(c.Request.Context(), c.Param("id")); err != nil {
-		_ = c.Error(err)
-		return
+		return err
 	}
 
 	c.Status(http.StatusNoContent)
+	return nil
 }
 
 // updatePermissions godoc
@@ -151,20 +146,18 @@ func (h *handler) delete(c *gin.Context) {
 // @Param permissions body apiPermissionsUpdateDto true "Permissions to set"
 // @Success 200 {object} apiResponseDto "Updated API"
 // @Router /api/apis/{id}/permissions [put]
-func (h *handler) updatePermissions(c *gin.Context) {
+func (h *handler) updatePermissions(c *gin.Context) error {
 	var input apiPermissionsUpdateDto
-	if err := dto.ShouldBindWithNormalizedJSON(c, &input); err != nil {
-		_ = c.Error(err)
-		return
+	if err := httpserver.BindJSON(c, &input); err != nil {
+		return err
 	}
 
 	api, err := h.service.UpdatePermissions(c.Request.Context(), c.Param("id"), input)
 	if err != nil {
-		_ = c.Error(err)
-		return
+		return err
 	}
 
-	h.respond(c, http.StatusOK, api)
+	return h.respond(c, http.StatusOK, api)
 }
 
 // getClientAccess godoc
@@ -175,14 +168,14 @@ func (h *handler) updatePermissions(c *gin.Context) {
 // @Param clientId path string true "OIDC Client ID"
 // @Success 200 {object} clientApiAccessDto
 // @Router /api/api-access/{clientId} [get]
-func (h *handler) getClientAccess(c *gin.Context) {
+func (h *handler) getClientAccess(c *gin.Context) error {
 	access, err := h.service.GetClientAPIAccess(c.Request.Context(), c.Param("clientId"))
 	if err != nil {
-		_ = c.Error(err)
-		return
+		return err
 	}
 
 	c.JSON(http.StatusOK, newClientApiAccessDto(access))
+	return nil
 }
 
 // updateClientAccess godoc
@@ -195,21 +188,20 @@ func (h *handler) getClientAccess(c *gin.Context) {
 // @Param access body clientApiAccessUpdateDto true "Allowed permission IDs per subject type"
 // @Success 200 {object} clientApiAccessDto
 // @Router /api/api-access/{clientId} [put]
-func (h *handler) updateClientAccess(c *gin.Context) {
+func (h *handler) updateClientAccess(c *gin.Context) error {
 	var input clientApiAccessUpdateDto
-	err := c.ShouldBindJSON(&input)
+	err := httpserver.BindJSON(c, &input)
 	if err != nil {
-		_ = c.Error(err)
-		return
+		return err
 	}
 
 	applied, err := h.service.SetClientAPIAccess(c.Request.Context(), c.Param("clientId"), ClientAPIAccess(input))
 	if err != nil {
-		_ = c.Error(err)
-		return
+		return err
 	}
 
 	c.JSON(http.StatusOK, newClientApiAccessDto(applied))
+	return nil
 }
 
 // newClientApiAccessDto always serializes both permission lists as arrays rather than null
@@ -224,12 +216,12 @@ func newClientApiAccessDto(access ClientAPIAccess) clientApiAccessDto {
 	return dto
 }
 
-func (h *handler) respond(c *gin.Context, status int, api API) {
+func (h *handler) respond(c *gin.Context, status int, api API) error {
 	var responseDto apiResponseDto
 	if err := dto.MapStruct(api, &responseDto); err != nil {
-		_ = c.Error(err)
-		return
+		return err
 	}
 	responseDto.Resource = api.Audience
 	c.JSON(status, responseDto)
+	return nil
 }