Documented swagger for new orphan visits endpoint

docs/swagger/definitions/OrphanVisit.json

@@ -0,0 +1,23 @@
+{
+    "type": "object",
+    "required": ["visitedUrl", "type"],
+    "allOf": [{
+        "$ref": "./Visit.json"
+    }],
+    "properties": {
+        "visitedUrl": {
+            "type": "string",
+            "nullable": true,
+            "description": "The originally visited URL that triggered the tracking of this visit"
+        },
+        "type": {
+            "type": "string",
+            "enum": [
+                "invalid_short_url",
+                "base_url",
+                "regular_404"
+            ],
+            "description": "Tells the type of orphan visit"
+        }
+    }
+}

docs/swagger/definitions/Visit.json

@@ -1,5 +1,6 @@
 {
     "type": "object",
+    "required": ["referer", "date", "userAgent", "visitLocation"],
     "properties": {
         "referer": {
             "type": "string",

docs/swagger/paths/v2_visits_orphan.json

@@ -0,0 +1,141 @@
+{
+    "get": {
+        "operationId": "getOrphanVisits",
+        "tags": [
+            "Visits"
+        ],
+        "summary": "List orphan visits",
+        "description": "Get the list of visits to invalid short URLs, the base URL or any other 404.",
+        "parameters": [
+            {
+                "$ref": "../parameters/version.json"
+            },
+            {
+                "name": "startDate",
+                "in": "query",
+                "description": "The date (in ISO-8601 format) from which we want to get visits.",
+                "required": false,
+                "schema": {
+                    "type": "string"
+                }
+            },
+            {
+                "name": "endDate",
+                "in": "query",
+                "description": "The date (in ISO-8601 format) until which we want to get visits.",
+                "required": false,
+                "schema": {
+                    "type": "string"
+                }
+            },
+            {
+                "name": "page",
+                "in": "query",
+                "description": "The page to display. Defaults to 1",
+                "required": false,
+                "schema": {
+                    "type": "number"
+                }
+            },
+            {
+                "name": "itemsPerPage",
+                "in": "query",
+                "description": "The amount of items to return on every page. Defaults to all the items",
+                "required": false,
+                "schema": {
+                    "type": "number"
+                }
+            }
+        ],
+        "security": [
+            {
+                "ApiKey": []
+            }
+        ],
+        "responses": {
+            "200": {
+                "description": "List of visits.",
+                "content": {
+                    "application/json": {
+                        "schema": {
+                            "type": "object",
+                            "properties": {
+                                "visits": {
+                                    "type": "object",
+                                    "properties": {
+                                        "data": {
+                                            "type": "array",
+                                            "items": {
+                                                "$ref": "../definitions/OrphanVisit.json"
+                                            }
+                                        },
+                                        "pagination": {
+                                            "$ref": "../definitions/Pagination.json"
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                },
+                "examples": {
+                    "application/json": {
+                        "visits": {
+                            "data": [
+                                {
+                                    "referer": "https://twitter.com",
+                                    "date": "2015-08-20T05:05:03+04:00",
+                                    "userAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0 Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0",
+                                    "visitLocation": null,
+                                    "visitedUrl": "https://doma.in",
+                                    "type": "base_url"
+                                },
+                                {
+                                    "referer": "https://t.co",
+                                    "date": "2015-08-20T05:05:03+04:00",
+                                    "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
+                                    "visitLocation": {
+                                        "cityName": "Cupertino",
+                                        "countryCode": "US",
+                                        "countryName": "United States",
+                                        "latitude": 37.3042,
+                                        "longitude": -122.0946,
+                                        "regionName": "California",
+                                        "timezone": "America/Los_Angeles"
+                                    },
+                                    "visitedUrl": "https://doma.in/foo",
+                                    "type": "invalid_short_url"
+                                },
+                                {
+                                    "referer": null,
+                                    "date": "2015-08-20T05:05:03+04:00",
+                                    "userAgent": "some_web_crawler/1.4",
+                                    "visitLocation": null,
+                                    "visitedUrl": "https://doma.in/foo/bar/baz",
+                                    "type": "regular_404"
+                                }
+                            ],
+                            "pagination": {
+                                "currentPage": 5,
+                                "pagesCount": 12,
+                                "itemsPerPage": 10,
+                                "itemsInCurrentPage": 10,
+                                "totalItems": 115
+                            }
+                        }
+                    }
+                }
+            },
+            "500": {
+                "description": "Unexpected error.",
+                "content": {
+                    "application/problem+json": {
+                        "schema": {
+                            "$ref": "../definitions/Error.json"
+                        }
+                    }
+                }
+            }
+        }
+    }
+}

docs/swagger/swagger.json

@@ -95,6 +95,9 @@
         "/rest/v{version}/tags/{tag}/visits": {
             "$ref": "paths/v2_tags_{tag}_visits.json"
         },
+        "/rest/v{version}/visits/orphan": {
+            "$ref": "paths/v2_visits_orphan.json"
+        },
 
         "/rest/v{version}/domains": {
             "$ref": "paths/v2_domains.json"