@apifreaks/openapi-specs 0.1.0

package/specs/user-agent/bulk-user-agent-parser.json

@@ -0,0 +1,441 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "Bulk User Agent Parser - Multi User Agent Parsing",
+    "version": "1.0.0",
+    "description": "Parse multiple User-Agent strings in a single POST request to obtain detailed browser, device, operating system, and rendering engine information for each string. Supports up to 50,000 User-Agent strings per request. Each entry in the response array mirrors the shape of a single User Agent Parser result --- including browser/app name and version, device hardware (name, type, brand, CPU), layout engine data, and operating system metadata --- in the same order as the request. A malformed/unparsable (but non-empty) string does not fail the batch; it simply comes back with every classification field set to `Hacker`, just like the single-lookup endpoint. An empty string or `null` anywhere in the array does fail the whole request with a `400`, not a per-item error --- there is no partial-failure array shape for this endpoint.",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v1.0",
+      "description": "Bulk User Agent Parser API Server"
+    }
+  ],
+  "paths": {
+    "/user-agent/lookup": {
+      "post": {
+        "tags": ["User Agent APIs"],
+        "summary": "Parse multiple User-Agent strings in a single request to obtain browser, device, and operating system details",
+        "description": "Parse up to 50,000 User-Agent strings simultaneously in a single request. Returns structured details about the browser, device, layout engine, and operating system for each string.",
+        "operationId": "bulkParseUserAgent",
+        "parameters": [
+          {
+            "name": "format",
+            "in": "query",
+            "required": false,
+            "description": "Format of the response. Possible values: json, xml.",
+            "schema": {
+              "type": "string",
+              "enum": ["json", "xml"],
+              "default": "json"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/BulkUserAgentRequest"
+              },
+              "examples": {
+                "typicalRequest": {
+                  "summary": "Example request body",
+                  "value": {
+                    "uaStrings": [
+                      "Mozilla/5.0 (Linux; Android 8.0.0; SM-G960F Build/R16NW) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.84 Mobile Safari/537.36",
+                      "Mozilla/5.0 (X11; U; Linux armv7l like Android; en-us) AppleWebKit/531.2+ (KHTML, like Gecko) Version/5.0 Safari/533.2+ Kindle/3.0+",
+                      "Mozilla/5.0 (Linux; U; en-US) AppleWebKit/528.5+ (KHTML, like Gecko, Safari/528.5+) Version/4.0 Kindle/3.0 (screen 600x800; rotate)"
+                    ]
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful response with parsed user agent data for each input string",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/BulkUserAgentParserResponse"
+                },
+                "examples": {
+                  "typicalSuccess": {
+                    "summary": "Typical successful response",
+                    "value": [
+                      {
+                        "user_agent_string": "Mozilla/5.0 (Linux; Android 8.0.0; SM-G960F Build/R16NW) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.84 Mobile Safari/537.36",
+                        "name": "Chrome",
+                        "type": "Browser",
+                        "version": "62.0.3202.84",
+                        "version_major": "62",
+                        "device": {
+                          "name": "Samsung SM-G960F",
+                          "type": "Phone",
+                          "brand": "Samsung",
+                          "cpu": "Unknown"
+                        },
+                        "engine": {
+                          "name": "Blink",
+                          "type": "Browser",
+                          "version": "62.0",
+                          "version_major": "62"
+                        },
+                        "operating_system": {
+                          "name": "Android",
+                          "type": "Mobile",
+                          "version": "8.0.0",
+                          "version_major": "8",
+                          "build": "R16NW"
+                        }
+                      },
+                      {
+                        "user_agent_string": "Mozilla/5.0 (X11; U; Linux armv7l like Android; en-us) AppleWebKit/531.2+ (KHTML, like Gecko) Version/5.0 Safari/533.2+ Kindle/3.0+",
+                        "name": "Kindle",
+                        "type": "Browser",
+                        "version": "3.0",
+                        "version_major": "3",
+                        "device": {
+                          "name": "Amazon Kindle",
+                          "type": "eReader",
+                          "brand": "Amazon",
+                          "cpu": "ARMv7l"
+                        },
+                        "engine": {
+                          "name": "AppleWebKit",
+                          "type": "Browser",
+                          "version": "531.2",
+                          "version_major": "531"
+                        },
+                        "operating_system": {
+                          "name": "FireOS",
+                          "type": "Mobile",
+                          "version": "??",
+                          "version_major": "??",
+                          "build": "??"
+                        }
+                      },
+                      {
+                        "user_agent_string": "Mozilla/5.0 (Linux; U; en-US) AppleWebKit/528.5+ (KHTML, like Gecko, Safari/528.5+) Version/4.0 Kindle/3.0 (screen 600x800; rotate)",
+                        "name": "Kindle",
+                        "type": "Browser",
+                        "version": "3.0",
+                        "version_major": "3",
+                        "device": {
+                          "name": "Amazon Kindle",
+                          "type": "eReader",
+                          "brand": "Amazon",
+                          "cpu": "Unknown"
+                        },
+                        "engine": {
+                          "name": "AppleWebKit",
+                          "type": "Browser",
+                          "version": "528.5",
+                          "version_major": "528"
+                        },
+                        "operating_system": {
+                          "name": "FireOS",
+                          "type": "Mobile",
+                          "version": "??",
+                          "version_major": "??",
+                          "build": "??"
+                        }
+                      }
+                    ]
+                  },
+                  "mixedWithUnparsable": {
+                    "summary": "Batch with a malformed (non-empty) string \u2014 still 200, that entry comes back as Hacker",
+                    "value": [
+                      {
+                        "user_agent_string": "asdkjaslkdjaslkdj12312",
+                        "name": "Hacker",
+                        "type": "Hacker",
+                        "version": "Hacker",
+                        "version_major": "Hacker",
+                        "device": {
+                          "name": "Hacker",
+                          "type": "Hacker",
+                          "brand": "Hacker",
+                          "cpu": "Unknown"
+                        },
+                        "engine": {
+                          "name": "Hacker",
+                          "type": "Hacker",
+                          "version": "Hacker",
+                          "version_major": "Hacker"
+                        },
+                        "operating_system": {
+                          "name": "Hacker",
+                          "type": "Hacker",
+                          "version": "Hacker",
+                          "version_major": "Hacker",
+                          "build": "??"
+                        }
+                      },
+                      {
+                        "user_agent_string": "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)",
+                        "name": "Googlebot",
+                        "type": "Robot",
+                        "version": "2.1",
+                        "version_major": "2",
+                        "device": {
+                          "name": "Google",
+                          "type": "Robot",
+                          "brand": "Google",
+                          "cpu": "Unknown"
+                        },
+                        "engine": {
+                          "name": "Googlebot",
+                          "type": "Robot",
+                          "version": "??",
+                          "version_major": "??"
+                        },
+                        "operating_system": {
+                          "name": "Google Cloud",
+                          "type": "Cloud",
+                          "version": "??",
+                          "version_major": "??",
+                          "build": "??"
+                        }
+                      }
+                    ]
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request \u2014 Invalid/missing request body, or an empty/null string anywhere in uaStrings (fails the whole batch, not a per-item error)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "missingRequestBody": {
+                    "summary": "Missing, empty, or wrong-type request body",
+                    "value": {
+                      "error": "Invalid request body Exception",
+                      "message": "Please provide data in required format in request body",
+                      "path": "/v1.0/user-agent/lookup",
+                      "status": 400,
+                      "timestamp": "2026-07-24T10:16:11.030Z"
+                    }
+                  },
+                  "emptyUserAgentString": {
+                    "summary": "Empty string or null inside uaStrings array",
+                    "value": {
+                      "message": "'userAgentString' must not be empty or null"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "ApiKeyAuthHeader": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "X-apiKey",
+        "description": "Pass your API key via the X-apiKey request header."
+      },
+      "ApiKeyAuthQuery": {
+        "type": "apiKey",
+        "in": "query",
+        "name": "apiKey",
+        "description": "Pass your API key via the apiKey query parameter."
+      }
+    },
+    "schemas": {
+      "BulkUserAgentRequest": {
+        "type": "object",
+        "description": "Request body containing an array of User-Agent strings to parse.",
+        "required": ["uaStrings"],
+        "properties": {
+          "uaStrings": {
+            "type": "array",
+            "description": "Array of User-Agent strings to parse. Maximum 50,000 strings per request.",
+            "maxItems": 50000,
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "BulkUserAgentParserResponse": {
+        "title": "UserAgentParserResponse",
+        "type": "array",
+        "description": "Array of per-string parsed User-Agent results, one entry per input string, in the same order as the request. Unlike the bulk IP lookup endpoint, there is no per-item error variant here: a malformed (non-empty) string still parses to a full result with every field set to \"Hacker\" (see UserAgentParserResponse). An empty string or null anywhere in the request array fails the entire request with a 400 instead of producing a per-item error entry --- see the 400 response.",
+        "items": {
+          "$ref": "#/components/schemas/UserAgentParserResponse"
+        }
+      },
+      "UserAgentParserResponse": {
+        "type": "object",
+        "description": "Parsed User-Agent result containing browser, device, engine, and operating system information. When the User-Agent string is malformed or cannot be parsed, every field across this object and its nested device/engine/operating_system objects is set to the literal string \"Hacker\" instead of the request failing.",
+        "required": [
+          "user_agent_string",
+          "name",
+          "type",
+          "version",
+          "version_major",
+          "device",
+          "engine",
+          "operating_system"
+        ],
+        "properties": {
+          "user_agent_string": {
+            "type": "string",
+            "description": "The raw User-Agent string that was parsed for browser, device, and operating system details."
+          },
+          "name": {
+            "type": "string",
+            "description": "Name of the browser, crawler, or application identified from the User-Agent string."
+          },
+          "type": {
+            "type": "string",
+            "description": "Category of the agent. Possible values: Browser, Browser Webview, Mobile App, Robot Mobile, Cloud Application, Email Client, Voice, Special, Testclient, Hacker, Unknown."
+          },
+          "version": {
+            "type": "string",
+            "description": "Full version string of the browser or application. \"??\" when the version could not be determined; \"Hacker\" when the User-Agent string itself is malformed/unparsable."
+          },
+          "version_major": {
+            "type": "string",
+            "description": "Major version number extracted from the version string. \"??\" when the version could not be determined; \"Hacker\" when the User-Agent string itself is malformed/unparsable."
+          },
+          "device": {
+            "$ref": "#/components/schemas/Device"
+          },
+          "engine": {
+            "$ref": "#/components/schemas/Engine"
+          },
+          "operating_system": {
+            "$ref": "#/components/schemas/OperatingSystem"
+          }
+        }
+      },
+      "Device": {
+        "type": "object",
+        "description": "Hardware device information extracted from the User-Agent string.",
+        "required": ["name", "type", "brand", "cpu"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Device name or model identifier of the hardware used."
+          },
+          "type": {
+            "type": "string",
+            "description": "Device category. Possible values: Desktop, Mobile, Tablet, Phone, Watch, Virtual Reality, eReader, Set-top box, TV, Game Console, Handheld Game Console, Voice, Robot, Robot Mobile, Robot Imitator, Hacker, Anonymized, Unknown."
+          },
+          "brand": {
+            "type": "string",
+            "description": "Device manufacturer or brand name."
+          },
+          "cpu": {
+            "type": "string",
+            "description": "CPU architecture or model identifier of the device."
+          }
+        }
+      },
+      "Engine": {
+        "type": "object",
+        "description": "Layout or rendering engine information extracted from the User-Agent string.",
+        "required": ["name", "type", "version", "version_major"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Name of the layout or rendering engine (e.g., Blink, Gecko, WebKit)."
+          },
+          "type": {
+            "type": "string",
+            "description": "Engine category. Possible values: Browser, Mobile App, Hacker, Robot, Unknown."
+          },
+          "version": {
+            "type": "string",
+            "description": "Full version string of the layout engine. \"??\" when unknown; \"Hacker\" when the User-Agent string itself is malformed/unparsable."
+          },
+          "version_major": {
+            "type": "string",
+            "description": "Major version number of the layout engine. \"??\" when unknown; \"Hacker\" when the User-Agent string itself is malformed/unparsable."
+          }
+        }
+      },
+      "OperatingSystem": {
+        "type": "object",
+        "description": "Operating system information extracted from the User-Agent string.",
+        "required": ["name", "type", "version", "version_major", "build"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Name of the operating system (e.g., Windows, Android, Ubuntu)."
+          },
+          "type": {
+            "type": "string",
+            "description": "Operating system category. Possible values: Desktop, Mobile, Game Console, Embedded, Cloud, Hacker, Anonymized, Unknown."
+          },
+          "version": {
+            "type": "string",
+            "description": "Full version string of the operating system. \"??\" when unknown; \"Hacker\" when the User-Agent string itself is malformed/unparsable."
+          },
+          "version_major": {
+            "type": "string",
+            "description": "Major version number of the operating system. \"??\" when unknown; \"Hacker\" when the User-Agent string itself is malformed/unparsable."
+          },
+          "build": {
+            "type": "string",
+            "description": "Build number or identifier of the operating system. \"??\" when unknown."
+          }
+        }
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "description": "Standard error envelope returned by the API on failed requests. Request-body-level errors (missing/empty/wrong-type body) include all five fields; per-item validation errors (empty/null string in uaStrings) include only message.",
+        "required": ["message"],
+        "properties": {
+          "error": {
+            "type": "string",
+            "description": "Short error category or exception type."
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable error message describing the failure."
+          },
+          "path": {
+            "type": "string",
+            "description": "API endpoint path that produced the error."
+          },
+          "status": {
+            "type": "integer",
+            "description": "HTTP status code returned with the error."
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Timestamp when the error occurred (ISO 8601)."
+          }
+        }
+      }
+    }
+  },
+  "security": [
+    {
+      "ApiKeyAuthHeader": []
+    },
+    {
+      "ApiKeyAuthQuery": []
+    }
+  ]
+}