Merge pull request #270 from shamanec/feature/refactor-api-responses

Refactor API responses to use a specific structure

Author: shamanec

.gitignore

@@ -12,4 +12,5 @@ server.key
 jsconfig.json
 .vscode/launch.json
 Provider1/
-go-ios*
+go-ios*
+memory/*

common/api/api.go

@@ -16,29 +16,57 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
-func GenericResponse(c *gin.Context, statusCode int, message string, result interface{}) {
-	c.JSON(statusCode, models.APIResponse{
-		Message: message,
-		Result:  result,
-	})
+// OK sends a 200 response with result payload.
+func OK[T any](c *gin.Context, message string, result T) {
+	c.JSON(http.StatusOK, models.APIResponse[T]{Success: true, Message: message, Result: result})
 }
 
-func InternalServerErrorResponse(c *gin.Context, message string, result interface{}) {
-	GenericResponse(c, http.StatusInternalServerError, message, result)
+// OKMessage sends a 200 response with a message only (no result payload).
+func OKMessage(c *gin.Context, message string) {
+	c.JSON(http.StatusOK, models.APIResponse[any]{Success: true, Message: message})
 }
 
-func OKResponse(c *gin.Context, message string, result interface{}) {
-	GenericResponse(c, http.StatusOK, message, result)
+// Created sends a 201 response with result payload.
+func Created[T any](c *gin.Context, message string, result T) {
+	c.JSON(http.StatusCreated, models.APIResponse[T]{Success: true, Message: message, Result: result})
 }
 
-func NotFoundResponse(c *gin.Context, message string, result interface{}) {
-	GenericResponse(c, http.StatusNotFound, message, result)
+// ErrorResponse sends an error response with the given status code.
+func ErrorResponse(c *gin.Context, status int, message string) {
+	c.JSON(status, models.APIResponse[any]{Success: false, Message: message})
 }
 
-func BadRequestResponse(c *gin.Context, message string, result interface{}) {
-	GenericResponse(c, http.StatusBadRequest, message, result)
+// BadRequest sends a 400 error response.
+func BadRequest(c *gin.Context, message string) {
+	ErrorResponse(c, http.StatusBadRequest, message)
 }
 
-func ForbiddenResponse(c *gin.Context, message string, result interface{}) {
-	GenericResponse(c, http.StatusForbidden, message, result)
+// Unauthorized sends a 401 error response.
+func Unauthorized(c *gin.Context, message string) {
+	ErrorResponse(c, http.StatusUnauthorized, message)
+}
+
+// Forbidden sends a 403 error response.
+func Forbidden(c *gin.Context, message string) {
+	ErrorResponse(c, http.StatusForbidden, message)
+}
+
+// NotFound sends a 404 error response.
+func NotFound(c *gin.Context, message string) {
+	ErrorResponse(c, http.StatusNotFound, message)
+}
+
+// Conflict sends a 409 error response.
+func Conflict(c *gin.Context, message string) {
+	ErrorResponse(c, http.StatusConflict, message)
+}
+
+// InternalError sends a 500 error response.
+func InternalError(c *gin.Context, message string) {
+	ErrorResponse(c, http.StatusInternalServerError, message)
+}
+
+// AbortUnauthorized aborts the request chain and sends a 401 response.
+func AbortUnauthorized(c *gin.Context, message string) {
+	c.AbortWithStatusJSON(http.StatusUnauthorized, models.APIResponse[any]{Success: false, Message: message})
 }

common/models/hub_api.go

@@ -9,19 +9,65 @@
 
 package models
 
-// SuccessResponse represents a successful API response
-type SuccessResponse struct {
-	Message string `json:"message" example:"Operation completed successfully"`
+// APIResponse is the standard response envelope for all GADS API endpoints.
+// Use the concrete type aliases below for Swagger annotations.
+type APIResponse[T any] struct {
+	Success bool   `json:"success" example:"true"`
+	Message string `json:"message,omitempty" example:"Operation completed successfully"`
+	Result  T      `json:"result,omitempty"`
+}
+
+// Page is a generic paginated result wrapper.
+type Page[T any] struct {
+	Items      []T   `json:"items"`
+	Total      int64 `json:"total"`
+	Page       int   `json:"page,omitempty"`
+	TotalPages int   `json:"total_pages,omitempty"`
+}
+
+// Concrete page types for Swagger annotations.
+type WorkspacesPage = Page[WorkspaceWithDeviceCount]
+type AuditLogsPage = Page[SecretKeyAuditLogResponse]
+
+// Concrete types for Swagger annotations (swag does not support Go generics directly).
+type DeviceResponse = APIResponse[Device]
+type DeviceListResponse = APIResponse[[]Device]
+type UserResponse = APIResponse[User]
+type UserListResponse = APIResponse[[]User]
+type WorkspaceResponse = APIResponse[Workspace]
+type WorkspacePageResponse = APIResponse[WorkspacesPage]
+type ProviderResponse = APIResponse[Provider]
+type ProviderListResponse = APIResponse[[]Provider]
+type AuthTokenResponse = APIResponse[AuthResponse]
+type SecretKeyListResponse = APIResponse[[]SecretKeyResponse]
+type CredentialCreateResponse = APIResponse[CreateCredentialResponse]
+type CredentialListResponse = APIResponse[ClientCredentialsListResponse]
+type CredentialGetResponse = APIResponse[CredentialResponse]
+type FileListResponse = APIResponse[[]DBFile]
+type StringDataResponse = APIResponse[string]
+type CustomActionResponse = APIResponse[CustomAction]
+type CustomActionListResponse = APIResponse[[]CustomAction]
+type InstalledAppsResponse = APIResponse[[]string]
+type StreamSettingsResponse = APIResponse[StreamSettings]
+type MinioConfigResponse = APIResponse[MinioConfig]
+type TURNConfigResponse = APIResponse[TURNConfig]
+type SysStatusResponse = APIResponse[SystemStatusResponse]
+type LogsResponse = APIResponse[[]LogEntry]
+
+// ErrorResponse is the Swagger schema for error API responses (no result payload).
+type ErrorResponse struct {
+	Success bool   `json:"success" example:"false"`
+	Message string `json:"message" example:"An error occurred"`
 }
 
-// ErrorResponse represents an error API response
-type ErrorResponse struct {
-	Error string `json:"error" example:"Something went wrong"`
+// SuccessResponse is the Swagger schema for success API responses without a result payload.
+type SuccessResponse struct {
+	Success bool   `json:"success" example:"true"`
+	Message string `json:"message" example:"Operation completed successfully"`
 }
 
-// HealthResponse represents the health check response
-type HealthResponse struct {
-	Message string `json:"message" example:"ok"`
+type OAuthErrorResponse struct {
+	Error string `json:"error"`
 }
 
 // SecretKeyResponse represents a secret key response (without exposing the actual key)
@@ -157,3 +203,14 @@ type ClientCredentialsListResponse struct {
 	Credentials []CredentialResponse `json:"credentials"`
 	Total       int64                `json:"total" example:"5"`
 }
+
+// System status response structures
+type SystemStatusMessage struct {
+	Type    string `json:"type"`
+	Message string `json:"message"`
+	Action  string `json:"action"`
+}
+
+type SystemStatusResponse struct {
+	Messages []SystemStatusMessage `json:"messages"`
+}