{"id":23268569,"url":"https://github.com/sivaosorg/wrapify","last_synced_at":"2026-01-02T21:11:38.725Z","repository":{"id":266956504,"uuid":"899859295","full_name":"sivaosorg/wrapify","owner":"sivaosorg","description":"wrapify is a Go library designed to simplify and standardize API response wrapping for RESTful services. It leverages the Decorator Pattern to dynamically add error handling, metadata, pagination, and other response features in a clean and human-readable format.","archived":false,"fork":false,"pushed_at":"2024-12-15T15:57:07.000Z","size":99,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-04-06T08:42:10.561Z","etag":null,"topics":["error-handling","errors","go","golang","golang-library","golang-package","response","standardized-api","wrapper","wrapper-api","wrapper-based-selection","wrapper-functions","wrapper-library"],"latest_commit_sha":null,"homepage":"https://github.com/sivaosorg/wrapify","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sivaosorg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-07T07:47:18.000Z","updated_at":"2024-12-15T15:57:10.000Z","dependencies_parsed_at":"2024-12-07T11:49:56.018Z","dependency_job_id":null,"html_url":"https://github.com/sivaosorg/wrapify","commit_stats":null,"previous_names":["sivaosorg/wrapify"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/sivaosorg/wrapify","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sivaosorg%2Fwrapify","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sivaosorg%2Fwrapify/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sivaosorg%2Fwrapify/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sivaosorg%2Fwrapify/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sivaosorg","download_url":"https://codeload.github.com/sivaosorg/wrapify/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sivaosorg%2Fwrapify/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262887186,"owners_count":23379767,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["error-handling","errors","go","golang","golang-library","golang-package","response","standardized-api","wrapper","wrapper-api","wrapper-based-selection","wrapper-functions","wrapper-library"],"created_at":"2024-12-19T17:19:44.707Z","updated_at":"2026-01-02T21:11:38.717Z","avatar_url":"https://github.com/sivaosorg.png","language":"Go","readme":"# wrapify\n\n**wrapify** is a Go library designed to simplify and standardize API response wrapping for RESTful services. It leverages the Decorator Pattern to dynamically add error handling, metadata, pagination, and other response features in a clean and human-readable format. With Wrapify, you can ensure consistent and extensible API responses with minimal boilerplate. Perfect for building robust, maintainable REST APIs in Go!\n\n### Requirements\n\n- Go version 1.23 or higher\n\n### Installation\n\nTo install, you can use the following commands based on your preference:\n\n- For a specific version:\n\n  ```bash\n  go get github.com/sivaosorg/wrapify@v0.0.1\n  ```\n\n- For the latest version:\n  ```bash\n  go get -u github.com/sivaosorg/wrapify@latest\n  ```\n\n### Getting started\n\n#### Getting wrapify\n\nWith [Go's module support](https://go.dev/wiki/Modules#how-to-use-modules), `go [build|run|test]` automatically fetches the necessary dependencies when you add the import in your code:\n\n```go\nimport \"github.com/sivaosorg/wrapify\"\n```\n\n#### Usage\n\n\u003e An example of the wrapper-based standardized API response\n\n```json\n{\n  \"data\": \"response body here\", // The primary data payload of the response.\n  \"debug\": {\n    \"___abc\": \"trace sessions_id: 4919e84fc26881e9fe790f5d07465db4\",\n    \"refer\": 1234\n  }, // Debugging information (useful for development).\n  \"message\": \"How are you? I'm good\", // A message providing additional context about the response.\n  \"meta\": {\n    \"api_version\": \"v0.0.1\", // API version used for the request.\n    \"custom_fields\": {\n      \"fields\": \"userID: 103\"\n    }, // Additional custom metadata fields.\n    \"locale\": \"en_US\", // Locale used for the request, e.g., \"en-US\".\n    \"request_id\": \"80eafc6a1655ec5a06595d155f1e6951\", // Unique identifier for the request, useful for debugging.\n    \"requested_time\": \"2024-12-14T20:24:23.983839+07:00\" // Timestamp when the request was made.\n  }, // Metadata about the API response.\n  \"pagination\": {\n    \"is_last\": true, // Indicates whether this is the last page.\n    \"page\": 1000, // Current page number.\n    \"per_page\": 2, // Number of items per page.\n    \"total_items\": 120, // Total number of items available.\n    \"total_pages\": 34 // Total number of pages.\n  }, // Pagination details, if applicable.\n  \"path\": \"/api/v1/users\", // Request path for which the response is generated.\n  \"status_code\": 200, // HTTP status code for the response.\n  \"total\": 1 // Total number of items (used in non-paginated responses).\n}\n```\n\n\u003e Structure of the wrapper-based standardized API response\n\n```go\n// R represents a wrapper around the main `wrapper` struct.\n// It is used as a high-level abstraction to provide a simplified interface for handling API responses.\n// The `R` type allows for easier manipulation of the wrapped data, metadata,\n// and other response components, while maintaining the flexibility of the underlying `wrapper` structure.\ntype R struct {\n    *wrapper\n}\n// Available checks whether the `wrapper` instance is non-nil.\nfunc (w *wrapper) Available() bool\n// Body retrieves the body data associated with the `wrapper` instance.\nfunc (w *wrapper) Body() interface{}\n// Cause traverses the error chain and returns the underlying cause of the error\n// associated with the `wrapper` instance.\nfunc (w *wrapper) Cause() error\n// Debugging retrieves the debugging information from the `wrapper` instance.\nfunc (w *wrapper) Debugging() map[string]interface{}\n// Error retrieves the error associated with the `wrapper` instance.\nfunc (w *wrapper) Error() string\n// Header retrieves the `header` associated with the `wrapper` instance.\nfunc (w *wrapper) Header() *header\n// IsBodyPresent checks whether the body data is present in the `wrapper` instance.\nfunc (w *wrapper) IsBodyPresent() bool\n// IsClientError checks whether the HTTP status code indicates a client error.\nfunc (w *wrapper) IsClientError() bool\n// IsDebuggingKeyPresent checks whether a specific key exists in the `debug` information.\nfunc (w *wrapper) IsDebuggingKeyPresent(key string) bool\n// IsDebuggingPresent checks whether debugging information is present in the `wrapper` instance.\nfunc (w *wrapper) IsDebuggingPresent() bool\n// IsError checks whether there is an error present in the `wrapper` instance.\n// This function returns `true` if the `wrapper` contains an error, which can be any of the following:\n//   - An error present in the `errors` field.\n//   - A client error (4xx status code) or a server error (5xx status code).\nfunc (w *wrapper) IsError() bool\n// IsErrorPresent checks whether an error is present in the `wrapper` instance.\nfunc (w *wrapper) IsErrorPresent() bool\n// IsHeaderPresent checks whether header information is present in the `wrapper` instance.\nfunc (w *wrapper) IsHeaderPresent() bool\n// IsLastPage checks whether the current page is the last page of results.\nfunc (w *wrapper) IsLastPage() bool\n// IsMetaPresent checks whether metadata information is present in the `wrapper` instance.\nfunc (w *wrapper) IsMetaPresent() bool\n// IsPagingPresent checks whether pagination information is present in the `wrapper` instance.\nfunc (w *wrapper) IsPagingPresent() bool\n// IsRedirection checks whether the HTTP status code indicates a redirection response.\nfunc (w *wrapper) IsRedirection() bool\n// IsServerError checks whether the HTTP status code indicates a server error.\nfunc (w *wrapper) IsServerError() bool\n// IsStatusCodePresent checks whether a valid status code is present in the `wrapper` instance.\nfunc (w *wrapper) IsStatusCodePresent() bool\n// IsSuccess checks whether the HTTP status code indicates a successful response.\nfunc (w *wrapper) IsSuccess() bool\n// IsTotalPresent checks whether the total number of items is present in the `wrapper` instance.\nfunc (w *wrapper) IsTotalPresent() bool\n// Json serializes the `wrapper` instance into a compact JSON string.\nfunc (w *wrapper) Json() string\n// JsonPretty serializes the `wrapper` instance into a prettified JSON string.\nfunc (w *wrapper) JsonPretty() string\n// Message retrieves the message associated with the `wrapper` instance.\nfunc (w *wrapper) Message() string\n// Meta retrieves the `meta` information from the `wrapper` instance.\nfunc (w *wrapper) Meta() *meta\n// OnKeyDebugging retrieves the value of a specific debugging key from the `wrapper` instance.\nfunc (w *wrapper) OnKeyDebugging(key string) interface{}\n// Pagination retrieves the `pagination` instance associated with the `wrapper`.\nfunc (w *wrapper) Pagination() *pagination\n// R represents a wrapper around the main `wrapper` struct. It is used as a high-level\n// abstraction to provide a simplified interface for handling API responses.\n// The `R` type allows for easier manipulation of the wrapped data, metadata, and other\n// response components, while maintaining the flexibility of the underlying `wrapper` structure.\nfunc (w *wrapper) Reply() R\n// Respond generates a map representation of the `wrapper` instance.\nfunc (w *wrapper) Respond() map[string]interface{}\n// StatusCode retrieves the HTTP status code associated with the `wrapper` instance.\nfunc (w *wrapper) StatusCode() int\n// StatusText returns a human-readable string representation of the HTTP status.\nfunc (w *wrapper) StatusText() string\n// Total retrieves the total number of items associated with the `wrapper` instance.\nfunc (w *wrapper) Total() int\n// WithApiVersion sets the API version in the `meta` field of the `wrapper` instance.\nfunc (w *wrapper) WithApiVersion(v string) *wrapper\n// WithApiVersionf sets the API version in the `meta` field of the `wrapper` instance using a formatted string.\nfunc (w *wrapper) WithApiVersionf(format string, args ...interface{}) *wrapper\n// WithBody sets the body data for the `wrapper` instance.\nfunc (w *wrapper) WithBody(v interface{}) *wrapper\n// WithCustomFieldKV sets a specific custom field key-value pair in the `meta` field of the `wrapper` instance.\nfunc (w *wrapper) WithCustomFieldKV(key string, value interface{}) *wrapper\n// WithCustomFieldKVf sets a specific custom field key-value pair in the `meta` field of the `wrapper` instance\n// using a formatted value.\nfunc (w *wrapper) WithCustomFieldKVf(key string, format string, args ...interface{}) *wrapper\n// WithCustomFields sets the custom fields in the `meta` field of the `wrapper` instance.\nfunc (w *wrapper) WithCustomFields(values map[string]interface{}) *wrapper\n// WithDebugging sets the debugging information for the `wrapper` instance.\nfunc (w *wrapper) WithDebugging(v map[string]interface{}) *wrapper\n// WithDebuggingKV adds a key-value pair to the debugging information in the `wrapper` instance.\nfunc (w *wrapper) WithDebuggingKV(key string, value interface{}) *wrapper\n// WithDebuggingKVf adds a formatted key-value pair to the debugging information in the `wrapper` instance.\nfunc (w *wrapper) WithDebuggingKVf(key string, format string, args ...interface{}) *wrapper\n// WithErrMessage adds a plain contextual message to an existing error and sets it for the `wrapper` instance.\nfunc (w *wrapper) WithErrMessage(err error, message string) *wrapper\n// WithErrMessagef adds a formatted contextual message to an existing error and sets it for the `wrapper` instance.\nfunc (w *wrapper) WithErrMessagef(err error, format string, args ...interface{}) *wrapper\n// WithErrSck sets an error with a stack trace for the `wrapper` instance.\nfunc (w *wrapper) WithErrSck(err error) *wrapper\n// WithErrWrap wraps an existing error with an additional message and sets it for the `wrapper` instance.\nfunc (w *wrapper) WithErrWrap(err error, message string) *wrapper\n// WithErrWrapf wraps an existing error with a formatted message and sets it for the `wrapper` instance.\nfunc (w *wrapper) WithErrWrapf(err error, format string, args ...interface{}) *wrapper\n// WithError sets an error for the `wrapper` instance using a plain error message.\nfunc (w *wrapper) WithError(message string) *wrapper\n// WithErrorf sets a formatted error for the `wrapper` instance.\nfunc (w *wrapper) WithErrorf(format string, args ...interface{}) *wrapper\n// WithHeader sets the header for the `wrapper` instance.\nfunc (w *wrapper) WithHeader(v *header) *wrapper\n// WithIsLast sets whether the current page is the last one in the wrapper's pagination.\nfunc (w *wrapper) WithIsLast(v bool) *wrapper\n// WithLocale sets the locale in the `meta` field of the `wrapper` instance.\nfunc (w *wrapper) WithLocale(v string) *wrapper\n// WithMessage sets a message for the `wrapper` instance.\nfunc (w *wrapper) WithMessage(message string) *wrapper\n// WithMessagef sets a formatted message for the `wrapper` instance.\nfunc (w *wrapper) WithMessagef(message string, args ...interface{}) *wrapper\n// WithMeta sets the metadata for the `wrapper` instance.\nfunc (w *wrapper) WithMeta(v *meta) *wrapper\n// WithPage sets the current page number in the wrapper's pagination.\nfunc (w *wrapper) WithPage(v int) *wrapper\n// WithPagination sets the pagination information for the `wrapper` instance.\nfunc (w *wrapper) WithPagination(v *pagination) *wrapper\n// WithPath sets the request path for the `wrapper` instance.\nfunc (w *wrapper) WithPath(v string) *wrapper\n// WithPathf sets a formatted request path for the `wrapper` instance.\nfunc (w *wrapper) WithPathf(v string, args ...interface{}) *wrapper\n// WithPerPage sets the number of items per page in the wrapper's pagination.\nfunc (w *wrapper) WithPerPage(v int) *wrapper\n// WithRequestID sets the request ID in the `meta` field of the `wrapper` instance.\nfunc (w *wrapper) WithRequestID(v string) *wrapper\n// WithRequestIDf sets the request ID in the `meta` field of the `wrapper` instance using a formatted string.\nfunc (w *wrapper) WithRequestIDf(format string, args ...interface{}) *wrapper\n// WithRequestedTime sets the requested time in the `meta` field of the `wrapper` instance.\nfunc (w *wrapper) WithRequestedTime(v time.Time) *wrapper\n// WithStatusCode sets the HTTP status code for the `wrapper` instance.\nfunc (w *wrapper) WithStatusCode(code int) *wrapper\n// WithTotal sets the total number of items for the `wrapper` instance.\nfunc (w *wrapper) WithTotal(total int) *wrapper\n// WithTotalItems sets the total number of items in the wrapper's pagination.\nfunc (w *wrapper) WithTotalItems(v int) *wrapper\n// WithTotalPages sets the total number of pages in the wrapper's pagination.\nfunc (w *wrapper) WithTotalPages(v int) *wrapper\n```\n\n\u003e Parse JSON string to wrapper-based standardized API response\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"log\"\n\t\"time\"\n\n\t\"github.com/sivaosorg/wrapify\"\n)\n\nfunc main() {\n\tjsonStr := `{\n\t\t\"data\": \"response body here\",\n\t\t\"debug\": {\n\t\t  \"___abc\": \"trace sessions_id: 4919e84fc26881e9fe790f5d07465db4\",\n\t\t  \"refer\": 1234\n\t\t},\n\t\t\"message\": \"How do you do? I'm good\",\n\t\t\"meta\": {\n\t\t  \"api_version\": \"v0.0.1\",\n\t\t  \"custom_fields\": {\n\t\t\t\"fields\": \"userID: 103\"\n\t\t  },\n\t\t  \"locale\": \"en_US\",\n\t\t  \"request_id\": \"80eafc6a1655ec5a06595d155f1e6951\",\n\t\t  \"requested_time\": \"2024-12-14T20:24:23.983839+07:00\"\n\t\t},\n\t\t\"pagination\": {\n\t\t  \"is_last\": true,\n\t\t  \"page\": 1000,\n\t\t  \"per_page\": 2,\n\t\t  \"total_items\": 120,\n\t\t  \"total_pages\": 34\n\t\t},\n\t\t\"path\": \"/api/v1/users\",\n\t\t\"status_code\": 200,\n\t\t\"total\": 1\n\t  }`\n\tt := time.Now()\n\tw, err := wrapify.UnwrapJSON(jsonStr)\n\tdiff := time.Since(t)\n\tif err != nil {\n\t\tlog.Fatalf(\"Error parsing JSON: %v\", err)\n\t}\n\tfmt.Printf(\"Exe time: %+v\\n\", diff.String())\n\tfmt.Printf(\"%+v\\n\", w.OnKeyDebugging(\"___abc\"))\n\tfmt.Printf(\"%+v\\n\", w.JsonPretty())\n}\n```\n\n\u003e Example of creating a wrapper-based standardized API response\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\n\t\"github.com/sivaosorg/wrapify\"\n\t\"github.com/sivaosorg/wrapify/randn\"\n)\n\nfunc main() {\n\tp := wrapify.Pages().\n\t\tWithIsLast(true).\n\t\tWithPage(1).\n\t\tWithTotalItems(120).\n\t\tWithPage(1000).\n\t\tWithTotalPages(34).\n\t\tWithPerPage(2)\n\tw := wrapify.New().\n\t\tWithStatusCode(200).\n\t\tWithTotal(1).\n\t\tWithMessagef(\"How are you? %v\", \"I'm good\").\n\t\tWithDebuggingKV(\"refer\", 1234).\n\t\tWithDebuggingKVf(\"___abc\", \"trace sessions_id: %v\", randn.CryptoID()).\n\t\tWithBody(\"response body here\").\n\t\tWithPath(\"/api/v1/users\").\n\t\tWithCustomFieldKVf(\"fields\", \"userID: %v\", 103).\n\t\tWithPagination(p)\n\tif !w.Available() {\n\t\treturn\n\t}\n\tfmt.Println(w.Json())\n\tfmt.Println(w.StatusCode())\n\tfmt.Println(w.StatusText())\n\tfmt.Println(w.Message())\n\tfmt.Println(w.Body())\n\tfmt.Println(w.IsSuccess())\n\tfmt.Println(w.Respond())\n\tfmt.Println(w.Meta().IsCustomFieldPresent())\n\tfmt.Println(w.Meta().IsApiVersionPresent())\n\tfmt.Println(w.Meta().IsRequestIDPresent())\n\tfmt.Println(w.Meta().IsRequestedTimePresent())\n}\n```\n\n#### HTTP Status Codes for APIs\n\n| **Scenario**                       | **HTTP Status Codes**                                     | **Example**                                                                         |\n| ---------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------- |\n| **Successful Resource Retrieval**  | 200 OK, 304 Not Modified                                  | `GET /users/123` - Returns user data or indicates cached content is valid.          |\n| **Resource Creation**              | 201 Created                                               | `POST /users` - Creates a new user, with a location header for the resource URL.    |\n| **Asynchronous Processing**        | 202 Accepted                                              | `POST /large-file` - File upload starts, and the client polls for result.           |\n| **Validation Errors**              | 400 Bad Request                                           | `POST /users` - Missing `name` field or invalid input format.                       |\n| **Authentication Issues**          | 401 Unauthorized, 403 Forbidden                           | Accessing a secured endpoint without valid credentials or insufficient permissions. |\n| **Rate Limiting**                  | 429 Too Many Requests                                     | Exceeded allowed API requests within a time window.                                 |\n| **Missing Resource**               | 404 Not Found                                             | `GET /users/999` - User ID not found.                                               |\n| **Server Failures**                | 500 Internal Server Error, 503 Service Unavailable        | Database failure, unhandled exception, or server in maintenance mode.               |\n| **Version Conflicts**              | 409 Conflict                                              | `PUT /resource/123` with an outdated version, causing a conflict.                   |\n| **Partial Responses**              | 206 Partial Content                                       | Video streaming or fetching paginated results.                                      |\n| **Redirecting Resources**          | 302 Found, 307 Temporary Redirect, 308 Permanent Redirect | URL redirection during resource movement or temporary relocation.                   |\n| **Client Data Too Large**          | 413 Payload Too Large, 414 URI Too Long                   | Request body or URL exceeds server-defined limits.                                  |\n| **Unsupported Content Type**       | 415 Unsupported Media Type                                | Client uploads a file format not accepted by the server.                            |\n| **Preconditions in Requests**      | 428 Precondition Required                                 | Conditional requests missing headers like `If-Match`.                               |\n| **Unavailable Legal Restrictions** | 451 Unavailable For Legal Reasons                         | Server refuses access due to legal constraints (e.g., copyright violations).        |\n| **Teapot Joke (RFC 2324)**         | 418 I'm a Teapot                                          | Easter egg for servers implementing the Hyper Text Coffee Pot Control Protocol.     |\n\n#### Detailed Use of HTTP Status Codes\n\n| **HTTP Status Code**                    | **Category**  | **Description**                                                                   | **Example**                                            |\n| --------------------------------------- | ------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------ |\n| **100 Continue**                        | Informational | Request headers received; client can proceed with the request body.               | Client sends a large payload after server's readiness. |\n| **200 OK**                              | Successful    | General success for GET, POST, PUT, or DELETE requests.                           | Returns requested resource or success confirmation.    |\n| **201 Created**                         | Successful    | Resource successfully created.                                                    | `POST /users` creates a new user.                      |\n| **202 Accepted**                        | Successful    | Request accepted but processing is asynchronous.                                  | Long-running jobs or file uploads.                     |\n| **204 No Content**                      | Successful    | Request successful, but no response body is returned.                             | `DELETE /users/123` successfully deletes a user.       |\n| **301 Moved Permanently**               | Redirection   | Resource has moved permanently to a new location.                                 | Redirect from `http://` to `https://`.                 |\n| **304 Not Modified**                    | Redirection   | Cached content is still valid.                                                    | `GET` returns no new data if resource is unchanged.    |\n| **400 Bad Request**                     | Client Error  | Malformed or invalid request from the client.                                     | Missing required fields or invalid input.              |\n| **401 Unauthorized**                    | Client Error  | Authentication is required but missing or invalid.                                | Accessing protected routes without valid credentials.  |\n| **403 Forbidden**                       | Client Error  | Access is denied due to insufficient permissions.                                 | Non-admin user attempting to access admin resources.   |\n| **404 Not Found**                       | Client Error  | Requested resource could not be found.                                            | `GET /users/999` where the user doesn't exist.         |\n| **409 Conflict**                        | Client Error  | Conflict with the current resource state.                                         | Versioning conflicts during updates.                   |\n| **429 Too Many Requests**               | Client Error  | Too many requests sent by the client in a time window.                            | Exceeding API rate limits for a free-tier user.        |\n| **500 Internal Server Error**           | Server Error  | Generic error due to unexpected server conditions.                                | Unhandled exception or database failure.               |\n| **503 Service Unavailable**             | Server Error  | Server is temporarily unavailable (e.g., maintenance or overload).                | Server in maintenance mode.                            |\n| **504 Gateway Timeout**                 | Server Error  | Upstream server timeout occurred.                                                 | API service failed while calling a dependent service.  |\n| **205 Reset Content**                   | Successful    | Client should reset the view or form after the request.                           | Clearing form data after a successful submission.      |\n| **206 Partial Content**                 | Successful    | Partial data returned, typically for range requests.                              | Video or file streaming.                               |\n| **302 Found**                           | Redirection   | Resource temporarily located at a different URI.                                  | Temporary URL redirection during maintenance.          |\n| **307 Temporary Redirect**              | Redirection   | POST request redirect maintaining HTTP method and body.                           | Redirecting after login to the original page.          |\n| **308 Permanent Redirect**              | Redirection   | Resource has permanently moved; all requests must use the new location.           | Updating bookmarks for a relocated API endpoint.       |\n| **413 Payload Too Large**               | Client Error  | Request entity exceeds the server’s capacity limits.                              | Uploading a file exceeding the server's maximum size.  |\n| **414 URI Too Long**                    | Client Error  | Request URI is too long for the server to process.                                | Query parameters exceed the allowed URL length.        |\n| **415 Unsupported Media Type**          | Client Error  | Media format of the request is not supported by the server.                       | Uploading a `.exe` file when only `.png` is allowed.   |\n| **416 Range Not Satisfiable**           | Client Error  | Client requested an invalid range of data.                                        | Requesting byte range beyond the end of a file.        |\n| **422 Unprocessable Entity**            | Client Error  | Server understands the request but is unable to process the content.              | Semantic validation errors for a JSON payload.         |\n| **451 Unavailable For Legal Reasons**   | Client Error  | Resource cannot be provided due to legal restrictions.                            | Region-based content restrictions.                     |\n| **500 Internal Server Error**           | Server Error  | Catch-all for unexpected server errors.                                           | Database unavailable or unhandled exceptions.          |\n| **501 Not Implemented**                 | Server Error  | Server lacks the functionality to fulfill the request.                            | Unsupported HTTP method (e.g., `TRACE`).               |\n| **502 Bad Gateway**                     | Server Error  | Server acting as a gateway received an invalid response from the upstream server. | Reverse proxy errors.                                  |\n| **504 Gateway Timeout**                 | Server Error  | Timeout occurred while waiting for an upstream server.                            | API dependency fails to respond in time.               |\n| **511 Network Authentication Required** | Server Error  | Network requires authentication to gain access.                                   | Captive portals in public Wi-Fi networks.              |\n\n#### Test Case Scenarios\n\n| **Test Case Scenario**                                                             | **Expected HTTP Status Code(s)**               | **Description**                                                                                                             |\n| ---------------------------------------------------------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| **User successfully logs in**                                                      | 200 OK                                         | API response includes user details and authentication token.                                                                |\n| **User account created successfully**                                              | 201 Created                                    | Resource (user account) is created, and the location of the new resource is returned.                                       |\n| **File uploaded successfully but no additional data**                              | 204 No Content                                 | File upload completed successfully without a response body.                                                                 |\n| **User submits invalid login credentials**                                         | 401 Unauthorized                               | Login fails due to incorrect username or password.                                                                          |\n| **Accessing a protected resource without login**                                   | 403 Forbidden                                  | User is not authorized to view the resource, even with authentication.                                                      |\n| **User attempts to access a non-existent endpoint**                                | 404 Not Found                                  | Requested API endpoint or resource does not exist.                                                                          |\n| **Validation error on a user registration form**                                   | 422 Unprocessable Entity                       | Form data does not pass validation rules (e.g., password too short).                                                        |\n| **Request body too large (e.g., large file upload)**                               | 413 Payload Too Large                          | File upload or JSON body exceeds server limits.                                                                             |\n| **Incorrect file format uploaded (e.g., .exe file)**                               | 415 Unsupported Media Type                     | Server does not support the uploaded file type.                                                                             |\n| **Pagination requested beyond total pages**                                        | 416 Range Not Satisfiable                      | Client requests data outside the valid range of pages or records.                                                           |\n| **Server fails to connect to the database**                                        | 500 Internal Server Error                      | Unhandled error when the database connection cannot be established.                                                         |\n| **Feature not yet implemented in the API**                                         | 501 Not Implemented                            | HTTP method or endpoint is recognized but not implemented.                                                                  |\n| **API request timeout due to heavy backend processing**                            | 504 Gateway Timeout                            | Upstream server takes too long to process the request.                                                                      |\n| **Resource moved to a new location**                                               | 301 Moved Permanently, 308 Permanent Redirect  | URL of the resource has changed permanently; clients should update their links.                                             |\n| **Resource temporarily relocated during maintenance**                              | 302 Found, 307 Temporary Redirect              | Temporary redirect to another URL while the primary resource is unavailable.                                                |\n| **Rate-limiting: Too many API requests**                                           | 429 Too Many Requests                          | Client exceeds the allowed number of API requests in a given time window.                                                   |\n| **Precondition headers fail validation**                                           | 412 Precondition Failed                        | Conditional request fails because resource has been modified.                                                               |\n| **JSON body missing required fields**                                              | 400 Bad Request                                | Client sends a malformed or incomplete request body.                                                                        |\n| **Legal restriction prevents content access**                                      | 451 Unavailable For Legal Reasons              | Server is legally restricted from providing access to the resource.                                                         |\n| **Client loses connection before the request completes**                           | 499 Client Closed Request                      | Client aborts the connection before receiving a response (commonly logged, not directly sent).                              |\n| **Authentication required by proxy server**                                        | 407 Proxy Authentication Required              | Proxy server requires authentication to forward the request.                                                                |\n| **File partially downloaded for video streaming**                                  | 206 Partial Content                            | Only a specific byte range of the resource is delivered for streaming or download resumption.                               |\n| **Form submission resets after success**                                           | 205 Reset Content                              | Server advises client to clear the form view post submission.                                                               |\n| **HTTP protocol not supported by server**                                          | 505 HTTP Version Not Supported                 | Server rejects the request because it uses an unsupported HTTP protocol version.                                            |\n| **Conflict during resource creation (e.g., duplicate)**                            | 409 Conflict                                   | Duplicate data (e.g., username already taken) prevents successful resource creation.                                        |\n| **Request missing mandatory headers**                                              | 428 Precondition Required                      | Server expects precondition headers but they are not provided in the request.                                               |\n| **Server unavailable for scheduled maintenance**                                   | 503 Service Unavailable                        | API temporarily down due to maintenance.                                                                                    |\n| **Captive portal blocking request**                                                | 511 Network Authentication Required            | Network requires user to authenticate via a captive portal (e.g., public Wi-Fi).                                            |\n| **User attempts to delete a resource they don’t own**                              | 403 Forbidden                                  | User lacks the necessary permissions to delete the resource.                                                                |\n| **Successful logout action**                                                       | 204 No Content                                 | Logout succeeds, and no further information is needed in the response body.                                                 |\n| **Failed payment during checkout**                                                 | 402 Payment Required                           | Payment processing fails due to insufficient funds or invalid card details.                                                 |\n| **Retryable error while interacting with an API**                                  | 503 Service Unavailable, 429 Too Many Requests | Server advises client to retry the request later due to high load or maintenance.                                           |\n| **Resource has been permanently removed**                                          | 410 Gone                                       | The requested resource is no longer available and has been intentionally removed.                                           |\n| **Attempting to use deprecated API functionality**                                 | 426 Upgrade Required                           | Server indicates the client must switch to a newer API version or feature.                                                  |\n| **Server encounters infinite loop in processing**                                  | 508 Loop Detected                              | Recursive dependency or circular reference causes server to fail.                                                           |\n| **Client request rejected for failing security policy**                            | 403 Forbidden                                  | Request rejected due to IP block, WAF policy, or lack of role-based access.                                                 |\n| **Data synchronization between microservices fails**                               | 424 Failed Dependency                          | Dependent service failure causes the current request to fail.                                                               |\n| **Cache expired and client retries fetching resource**                             | 304 Not Modified                               | Client reuses cached data because the resource hasn’t been modified.                                                        |\n| **Conditional GET succeeds with ETag header validation**                           | 200 OK                                         | ETag or Last-Modified headers validate that the resource is still current.                                                  |\n| **Debugging API errors via enhanced logs**                                         | 500 Internal Server Error                      | Logs include additional debugging information in non-production environments.                                               |\n| **Database deadlock during bulk update**                                           | 503 Service Unavailable                        | Server temporarily pauses due to contention in backend services (e.g., database).                                           |\n| **Sending an OPTIONS request for CORS preflight**                                  | 204 No Content                                 | Preflight request checks permissions and provides headers without returning a body.                                         |\n| **User provides outdated resource version for update**                             | 409 Conflict                                   | Request fails because the resource version has changed (optimistic locking conflict).                                       |\n| **Authorization header missing for private API**                                   | 401 Unauthorized                               | Server denies access to private endpoints due to missing or invalid authorization credentials.                              |\n| **Request triggers alert for potential bot activity**                              | 429 Too Many Requests                          | Server throttles requests due to rate limits exceeded by suspected bot.                                                     |\n| **Returning localized error messages**                                             | 422 Unprocessable Entity                       | Localized error message (e.g., user-facing validation errors) is included in the response.                                  |\n| **API downtime monitored by a health check service**                               | 503 Service Unavailable                        | Health check detects outage, and server signals unavailability for monitoring tools.                                        |\n| **Proxy service fails to resolve the target server**                               | 502 Bad Gateway                                | Reverse proxy server cannot reach the upstream server.                                                                      |\n| **User requests unsupported language or locale**                                   | 406 Not Acceptable                             | Server cannot fulfill request due to missing translation or unsupported Accept-Language header.                             |\n| **Request contains missing parameters**                                            | 400 Bad Request                                | Request body or query parameters are incomplete or improperly formatted.                                                    |\n| **Rate-limited error with Retry-After header**                                     | 429 Too Many Requests                          | Response includes a Retry-After header to indicate when the client can send another request.                                |\n| **Simultaneous update results in inconsistent state**                              | 409 Conflict                                   | Two users updating the same resource simultaneously cause a conflict.                                                       |\n| **Long-running process accepted but not completed yet**                            | 202 Accepted                                   | Request acknowledged and being processed asynchronously; no result yet.                                                     |\n| **Streaming file in chunks for large downloads**                                   | 206 Partial Content                            | Response delivers file in chunks using Content-Range headers.                                                               |\n| **Server limits resource creation per account**                                    | 429 Too Many Requests                          | Too many POST requests for creating new resources are detected from the same account.                                       |\n| **Request contains invalid authentication token**                                  | 401 Unauthorized                               | JWT token expired, malformed, or signed with an invalid key.                                                                |\n| **Custom error page for 404 not found**                                            | 404 Not Found                                  | Server renders a user-friendly 404 error page for missing resources.                                                        |\n| **JSON parsing error during request processing**                                   | 400 Bad Request                                | Malformed JSON request body results in a bad request error.                                                                 |\n| **File uploaded to a temporary storage location**                                  | 201 Created                                    | Temporary resource is created, and location is returned in response headers.                                                |\n| **Upstream server returns a malformed response**                                   | 502 Bad Gateway                                | Reverse proxy reports an invalid or unexpected response from the upstream server.                                           |\n| **Deprecation warning in response headers**                                        | 200 OK                                         | Warning header advises clients that the endpoint or feature will be deprecated in future.                                   |\n| **Custom quota limits for premium users**                                          | 429 Too Many Requests                          | Rate-limiting based on user’s subscription tier is enforced.                                                                |\n| **User provides invalid credentials**                                              | 401 Unauthorized                               | Authentication fails due to incorrect or missing credentials in the request.                                                |\n| **User requests a resource that no longer exists**                                 | 410 Gone                                       | Requested resource was previously available but has been permanently deleted.                                               |\n| **File upload is too large**                                                       | 413 Payload Too Large                          | User attempts to upload a file that exceeds the allowed size.                                                               |\n| **Access is denied due to insufficient permissions**                               | 403 Forbidden                                  | User lacks permissions to access the requested resource, even though they are authenticated.                                |\n| **User tries to access a resource they are not authorized for**                    | 403 Forbidden                                  | The user is authenticated, but their role does not permit access to the resource.                                           |\n| **API version mismatch**                                                           | 426 Upgrade Required                           | The client needs to upgrade to a supported API version.                                                                     |\n| **API successfully processes a request**                                           | 200 OK                                         | Request is processed successfully, and the server returns the result.                                                       |\n| **Resource creation is successful**                                                | 201 Created                                    | A new resource is created (e.g., new user, new item) and the response includes a location header.                           |\n| **User tries to update a resource with invalid data**                              | 400 Bad Request                                | The user has sent invalid data or missing required parameters in the request body.                                          |\n| **Invalid input format or type in request body**                                   | 400 Bad Request                                | Malformed JSON, XML, or any unsupported data format received in the body.                                                   |\n| **Client exceeds rate limit for API calls**                                        | 429 Too Many Requests                          | Too many requests sent in a given time frame, exceeding the rate limit.                                                     |\n| **Resource is temporarily unavailable due to maintenance**                         | 503 Service Unavailable                        | Service is down due to scheduled or unscheduled maintenance.                                                                |\n| **Requested resource does not exist**                                              | 404 Not Found                                  | The server cannot find the resource requested by the client.                                                                |\n| **User is logged out or session expired**                                          | 401 Unauthorized                               | Session has expired, requiring the user to authenticate again.                                                              |\n| **API request is valid but cannot be processed immediately**                       | 202 Accepted                                   | Request is accepted, but processing is deferred (asynchronous).                                                             |\n| **Invalid request headers**                                                        | 400 Bad Request                                | Client sends improper headers, such as missing required headers or unsupported content types.                               |\n| **File type not supported during upload**                                          | 415 Unsupported Media Type                     | The server refuses to process the file because its type is not supported.                                                   |\n| **Client attempts to access a restricted IP address**                              | 403 Forbidden                                  | Server blocks access from a specific IP address for security reasons.                                                       |\n| **Required query parameters are missing**                                          | 400 Bad Request                                | A required query parameter is missing from the request, making it invalid.                                                  |\n| **Client sends an invalid or expired authentication token**                        | 401 Unauthorized                               | Authentication fails due to the expiration or invalidity of the provided authentication token.                              |\n| **The request is processed but some resources fail**                               | 206 Partial Content                            | The request was partially fulfilled; some resources were returned, but others failed.                                       |\n| **Client requested a resource that has been moved**                                | 301 Moved Permanently                          | The requested resource has been permanently moved to a new URL.                                                             |\n| **Client requests an old resource version**                                        | 409 Conflict                                   | A conflict occurs, typically when trying to update a resource that has been modified by others.                             |\n| **Resource modification fails due to business rules**                              | 422 Unprocessable Entity                       | The resource update fails due to invalid data (e.g., violating constraints or business rules).                              |\n| **Server error during processing due to unexpected issue**                         | 500 Internal Server Error                      | Generic error indicating that the server encountered an unexpected condition.                                               |\n| **Proxy server encounters an error while communicating with the backend**          | 502 Bad Gateway                                | The reverse proxy server is unable to forward the request to the backend service.                                           |\n| **Request body exceeds maximum allowed size**                                      | 413 Payload Too Large                          | The client sends a request with a body larger than what the server is willing or able to process.                           |\n| **User attempts to upload a file without authorization**                           | 403 Forbidden                                  | User is authenticated, but lacks permission to upload files to the server.                                                  |\n| **API request violates business logic (e.g., attempting to submit an empty form)** | 400 Bad Request                                | Request violates API business logic or validation rules (e.g., submitting empty or invalid fields).                         |\n| **Server does not support the requested HTTP method**                              | 405 Method Not Allowed                         | The client attempts to use an unsupported HTTP method (e.g., using PUT on a read-only endpoint).                            |\n| **Client attempts to submit a request with too many parameters**                   | 400 Bad Request                                | Request contains too many parameters or exceeds the API’s parameter limits.                                                 |\n| **Service is temporarily unavailable**                                             | 503 Service Unavailable                        | The service is temporarily unavailable due to reasons like server overload, maintenance, etc.                               |\n| **Invalid request format (e.g., XML instead of JSON)**                             | 415 Unsupported Media Type                     | Server responds with an error when an unsupported content type (like XML) is sent in the request.                           |\n| **File not found in requested location**                                           | 404 Not Found                                  | Client requests a file that does not exist on the server.                                                                   |\n| **Server experiences a timeout when processing request**                           | 504 Gateway Timeout                            | The server was unable to get a timely response from an upstream server.                                                     |\n| **Incorrect authentication method provided**                                       | 400 Bad Request                                | Authentication method provided by the client is not supported by the server (e.g., Basic Auth instead of OAuth).            |\n| **Request sent in unsupported language**                                           | 406 Not Acceptable                             | The server cannot provide a response in the requested language.                                                             |\n| **Client sends invalid API version**                                               | 426 Upgrade Required                           | API version used in the request is outdated and no longer supported by the server.                                          |\n| **The API is receiving an unexpected large number of requests**                    | 429 Too Many Requests                          | The client exceeded the rate limit defined for the API endpoint.                                                            |\n| **Client requests a resource that is locked**                                      | 423 Locked                                     | The requested resource is locked and cannot be modified.                                                                    |\n| **Request failed due to a custom business rule violation**                         | 422 Unprocessable Entity                       | The request contains valid input, but a business rule prevents it from being processed.                                     |\n| **Client tries to access a deprecated endpoint**                                   | 410 Gone                                       | The endpoint has been deprecated and is no longer available.                                                                |\n| **The server is unable to process the request due to a backend error**             | 502 Bad Gateway                                | Backend or upstream server issues prevent the processing of the request.                                                    |\n| **The client’s request is incomplete (missing necessary fields)**                  | 400 Bad Request                                | Request cannot be processed because it lacks necessary fields or contains invalid values.                                   |\n| **User reaches the maximum limit of API calls per day**                            | 429 Too Many Requests                          | The user has exceeded their daily API quota limit and must wait until the next period.                                      |\n| **Client tries to access a resource that requires a higher subscription tier**     | 403 Forbidden                                  | Client is attempting to access a resource that is restricted based on their subscription tier.                              |\n| **Client sends a request with a malformed header**                                 | 400 Bad Request                                | A malformed or missing required header causes the request to be rejected.                                                   |\n| **Server successfully processes a POST request to create a new entity**            | 201 Created                                    | The POST request creates a new entity (such as a user or item), and the server returns the URI of the newly created entity. |\n| **Client submits a valid request for batch processing**                            | 207 Multi-Status                               | A batch request is processed with mixed success, returning the status of each request in the batch.                         |\n| **Request for an unsupported API version**                                         | 426 Upgrade Required                           | The requested API version is unsupported, and the client must upgrade.                                                      |\n\n### Contributing\n\nTo contribute to project, follow these steps:\n\n1. Clone the repository:\n\n   ```bash\n   git clone --depth 1 https://github.com/sivaosorg/wrapify.git\n   ```\n\n2. Navigate to the project directory:\n\n   ```bash\n   cd wrapify\n   ```\n\n3. Prepare the project environment:\n   ```bash\n   go mod tidy\n   ```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsivaosorg%2Fwrapify","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsivaosorg%2Fwrapify","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsivaosorg%2Fwrapify/lists"}