From 8e0009ae4889ebf460bb87b83ab50a72d1926ac3 Mon Sep 17 00:00:00 2001 From: Sun Howwrongbum Date: Tue, 6 Dec 2016 02:15:35 +0530 Subject: [swagger] Move consumes/produces to higher level --- swagger.json | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/swagger.json b/swagger.json index 25b76963c..705d887ac 100644 --- a/swagger.json +++ b/swagger.json @@ -9,6 +9,12 @@ "schemes": [ "http" ], + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], "paths": { "/commands": { "post": { -- cgit v1.2.3 From 0e47bd14846de72381179734daf402267abb694f Mon Sep 17 00:00:00 2001 From: Sun Howwrongbum Date: Tue, 6 Dec 2016 02:17:12 +0530 Subject: [swagger] Describe /commands - remove unnecessary entries --- swagger.json | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/swagger.json b/swagger.json index 705d887ac..0d887d97c 100644 --- a/swagger.json +++ b/swagger.json @@ -17,13 +17,8 @@ ], "paths": { "/commands": { + "summary": "Dispatch commands to device", "post": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], "parameters": [ { "name": "body", @@ -37,10 +32,12 @@ "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "$ref": "#/definitions/Command" } + }, + "400": { + "description": "Could happen when dispatching to the device is offline, the user doesn't have permission or an incorrect command _type_." } } } -- cgit v1.2.3 From 3776bd31240936f47e8790fbb8e1794d74feb19d Mon Sep 17 00:00:00 2001 From: Sun Howwrongbum Date: Tue, 6 Dec 2016 02:46:32 +0530 Subject: [swagger] Fix typos and incorrect entries --- swagger.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/swagger.json b/swagger.json index 0d887d97c..2d9e0ef3d 100644 --- a/swagger.json +++ b/swagger.json @@ -17,8 +17,8 @@ ], "paths": { "/commands": { - "summary": "Dispatch commands to device", "post": { + "summary": "Dispatch commands to device", "parameters": [ { "name": "body", @@ -37,7 +37,7 @@ } }, "400": { - "description": "Could happen when dispatching to the device is offline, the user doesn't have permission or an incorrect command _type_." + "description": "Could happen when dispatching to a device that is offline, the user doesn't have permission or an incorrect command _type_ for the device" } } } -- cgit v1.2.3 From a6989526efdd3d6a1af87270647ace0dc9a4c798 Mon Sep 17 00:00:00 2001 From: Sun Howwrongbum Date: Tue, 6 Dec 2016 02:47:28 +0530 Subject: [swagger] Describe /devices --- swagger.json | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/swagger.json b/swagger.json index 2d9e0ef3d..354544084 100644 --- a/swagger.json +++ b/swagger.json @@ -44,36 +44,34 @@ }, "/devices": { "get": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Fetch a list of Devices", + "description": "Without any params, returns a list of the user's devices", "parameters": [ { "name": "all", "in": "query", - "required": true, + "description": "Can only be used by admin users to fetch all entities", "type": "boolean" }, { "name": "userId", "in": "query", - "required": true, + "description": "Standard users can use this with their only with their own _userId_", "type": "integer" } ], "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "type": "array", "items": { "$ref": "#/definitions/Device" } } + }, + "400": { + "description": "No permission" } } }, -- cgit v1.2.3 From b7083d62bae0675e2f3e4009e6794460554352d6 Mon Sep 17 00:00:00 2001 From: Sun Howwrongbum Date: Tue, 6 Dec 2016 03:14:27 +0530 Subject: [swagger] Update the rest of /devices --- swagger.json | 77 ++++++++++++++++-------------------------------------------- 1 file changed, 20 insertions(+), 57 deletions(-) diff --git a/swagger.json b/swagger.json index 354544084..61ebf62e7 100644 --- a/swagger.json +++ b/swagger.json @@ -76,12 +76,7 @@ } }, "post": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Create a Device", "parameters": [ { "name": "body", @@ -95,7 +90,6 @@ "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "$ref": "#/definitions/Device" } @@ -105,18 +99,10 @@ }, "/devices/{id}": { "put": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Update a Device", "parameters": [ { - "name": "id", - "in": "path", - "required": true, - "type": "integer" + "$ref": "#/parameters/entityId" }, { "name": "body", @@ -130,7 +116,6 @@ "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "$ref": "#/definitions/Device" } @@ -138,42 +123,25 @@ } }, "delete": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Update a Device", "parameters": [ { - "name": "id", - "in": "path", - "required": true, - "type": "integer" + "$ref": "#/parameters/entityId" } ], "responses": { "204": { - "description": "No Content", - "headers": {} + "description": "No Content" } } } }, "/devices/{id}/distance": { "put": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Update the distance counter of the Device", "parameters": [ { - "name": "id", - "in": "path", - "required": true, - "type": "integer" + "$ref": "#/parameters/entityId" }, { "name": "body", @@ -186,20 +154,14 @@ ], "responses": { "204": { - "description": "No Content", - "headers": {} + "description": "No Content" } } } }, "/devices/geofences": { "post": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Link a Geofence to a Device", "parameters": [ { "name": "body", @@ -213,7 +175,6 @@ "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "$ref": "#/definitions/DeviceGeofence" } @@ -221,12 +182,7 @@ } }, "delete": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Remove a Geofence from a Device", "parameters": [ { "name": "body", @@ -239,8 +195,7 @@ ], "responses": { "204": { - "description": "No Content", - "headers": {} + "description": "No Content" } } } @@ -1946,5 +1901,13 @@ } } } + }, + "parameters": { + "entityId": { + "name": "id", + "in": "path", + "required": true, + "type": "integer" + } } } -- cgit v1.2.3 From a0375c8e3067f74ed14c370b2674ea00e9851a9c Mon Sep 17 00:00:00 2001 From: Sun Howwrongbum Date: Tue, 6 Dec 2016 03:31:58 +0530 Subject: [swagger] Describe /groups and refactor params ... as references --- swagger.json | 98 +++++++++++++++++++----------------------------------------- 1 file changed, 30 insertions(+), 68 deletions(-) diff --git a/swagger.json b/swagger.json index 61ebf62e7..abdbbf0dc 100644 --- a/swagger.json +++ b/swagger.json @@ -48,16 +48,10 @@ "description": "Without any params, returns a list of the user's devices", "parameters": [ { - "name": "all", - "in": "query", - "description": "Can only be used by admin users to fetch all entities", - "type": "boolean" + "$ref": "#/parameters/all" }, { - "name": "userId", - "in": "query", - "description": "Standard users can use this with their only with their own _userId_", - "type": "integer" + "$ref": "#/parameters/userId" } ], "responses": { @@ -202,30 +196,19 @@ }, "/groups": { "get": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Fetch a list of Groups", + "description": "Without any params, returns a list of the Groups the user belongs to", "parameters": [ { - "name": "all", - "in": "query", - "required": true, - "type": "boolean" + "$ref": "#/parameters/all" }, { - "name": "userId", - "in": "query", - "required": true, - "type": "integer" + "$ref": "#/parameters/userId" } ], "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "type": "array", "items": { @@ -236,12 +219,7 @@ } }, "post": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Create a Group", "parameters": [ { "name": "body", @@ -255,28 +233,22 @@ "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "$ref": "#/definitions/Group" } + }, + "400": { + "description": "No permission" } } } }, "/groups/{id}": { "put": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Update a Group", "parameters": [ { - "name": "id", - "in": "path", - "required": true, - "type": "integer" + "$ref": "#/parameters/entityId" }, { "name": "body", @@ -290,7 +262,6 @@ "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "$ref": "#/definitions/Group" } @@ -298,36 +269,22 @@ } }, "delete": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Delete a Group", "parameters": [ { - "name": "id", - "in": "path", - "required": true, - "type": "integer" + "$ref": "#/parameters/entityId" } ], "responses": { "204": { - "description": "No Content", - "headers": {} + "description": "No Content" } } } }, "/groups/geofences": { "post": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Link a Geofence to a Group", "parameters": [ { "name": "body", @@ -341,7 +298,6 @@ "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "$ref": "#/definitions/GroupGeofence" } @@ -349,12 +305,7 @@ } }, "delete": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Remove a Geofence from a Group", "parameters": [ { "name": "body", @@ -367,8 +318,7 @@ ], "responses": { "204": { - "description": "No Content", - "headers": {} + "description": "No Content" } } } @@ -1908,6 +1858,18 @@ "in": "path", "required": true, "type": "integer" + }, + "all": { + "name": "all", + "in": "query", + "description": "Can only be used by admin users to fetch all entities", + "type": "boolean" + }, + "userId": { + "name": "userId", + "in": "query", + "description": "Standard users can use this with their only with their own _userId_", + "type": "integer" } } } -- cgit v1.2.3 From e37f4e08d751b083c97ce44aae47f08b5fd04f46 Mon Sep 17 00:00:00 2001 From: Sun Howwrongbum Date: Tue, 6 Dec 2016 03:47:29 +0530 Subject: [swagger] Describe /permissions --- swagger.json | 57 ++++++++++++--------------------------------------------- 1 file changed, 12 insertions(+), 45 deletions(-) diff --git a/swagger.json b/swagger.json index abdbbf0dc..ae273ce5e 100644 --- a/swagger.json +++ b/swagger.json @@ -325,12 +325,7 @@ }, "/permissions/devices": { "post": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Link a Device to a User", "parameters": [ { "name": "body", @@ -344,20 +339,17 @@ "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "$ref": "#/definitions/DevicePermission" } + }, + "400": { + "description": "No permission" } } }, "delete": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Remove a Device from a User", "parameters": [ { "name": "body", @@ -370,20 +362,14 @@ ], "responses": { "204": { - "description": "No Content", - "headers": {} + "description": "No Content" } } } }, "/permissions/groups": { "post": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Link a Group to a User", "parameters": [ { "name": "body", @@ -397,7 +383,6 @@ "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "$ref": "#/definitions/GroupPermission" } @@ -405,12 +390,7 @@ } }, "delete": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Remove a Group from a User", "parameters": [ { "name": "body", @@ -423,20 +403,14 @@ ], "responses": { "204": { - "description": "No Content", - "headers": {} + "description": "No Content" } } } }, "/permissions/geofences": { "post": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Link a Geofence to a User", "parameters": [ { "name": "body", @@ -450,7 +424,6 @@ "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "$ref": "#/definitions/GeofencePermission" } @@ -458,12 +431,7 @@ } }, "delete": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Remove a Geofence from a User", "parameters": [ { "name": "body", @@ -476,8 +444,7 @@ ], "responses": { "204": { - "description": "No Content", - "headers": {} + "description": "No Content" } } } -- cgit v1.2.3 From ec535ff33ee8b2c2b3635a8d373ae37d358af18e Mon Sep 17 00:00:00 2001 From: Sun Howwrongbum Date: Tue, 6 Dec 2016 04:02:07 +0530 Subject: [swagger] Describe /positions, /server, ... ... /session --- swagger.json | 81 ++++++++++++++++++++++-------------------------------------- 1 file changed, 29 insertions(+), 52 deletions(-) diff --git a/swagger.json b/swagger.json index ae273ce5e..a4ff0d0f6 100644 --- a/swagger.json +++ b/swagger.json @@ -452,13 +452,7 @@ "/positions": { "get": { "summary" : "Fetches a list of Positions", - "description" : "Without any params, it returns a list of last known positions for all the user's devices", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "description" : "Without any params, it returns a list of last known positions for all the user's Devices. _from_ and _to_ fields are not required with _id_", "parameters": [ { "name": "deviceId", @@ -468,19 +462,12 @@ "type": "integer" }, { - "name": "from", - "in": "query", - "description": "Not required with _id_", - "required": false, - "type": "string" + "$ref": "#/parameters/fromTime" + }, + { + "$ref": "#/parameters/toTime" }, { - "name": "to", - "in": "query", - "description": "Not required with _id_", - "required": false, - "type": "string" - }, { "name" : "id", "in" : "query", "description" : "To fetch one or more positions. Multiple params can be passed like `id=31&id=42`", @@ -504,17 +491,10 @@ }, "/server": { "get": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], + "summary": "Fetch Server information", "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "$ref": "#/definitions/Server" } @@ -522,12 +502,7 @@ } }, "put": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Update Server information", "parameters": [ { "name": "body", @@ -541,7 +516,6 @@ "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "$ref": "#/definitions/Server" } @@ -551,34 +525,27 @@ }, "/session": { "get": { + "summary": "Fetch Session information", "consumes": [ "application/x-www-form-urlencoded" ], - "produces": [ - "application/json" - ], - "parameters": [], "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "$ref": "#/definitions/User" } }, "404": { - "description": "Not Found", - "headers": {} + "description": "Not Found" } } }, "post": { + "summary": "Create a new Session", "consumes": [ "application/x-www-form-urlencoded" ], - "produces": [ - "application/json" - ], "parameters": [ { "name": "email", @@ -590,35 +557,31 @@ "name": "password", "in": "formData", "required": true, - "type": "string" + "type": "string", + "format": "password" } ], "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "$ref": "#/definitions/User" } }, "401": { - "description": "Unauthorized", - "headers": {} + "description": "Unauthorized" } } }, "delete": { + "summary": "Close the Session", "consumes": [ "application/x-www-form-urlencoded" ], - "produces": [ - "application/json" - ], "parameters": [], "responses": { "204": { - "description": "No Content", - "headers": {} + "description": "No Content" } } } @@ -1837,6 +1800,20 @@ "in": "query", "description": "Standard users can use this with their only with their own _userId_", "type": "integer" + }, + "fromTime": { + "name": "from", + "in": "query", + "required": false, + "type": "string", + "format": "date-time" + }, + "toTime": { + "name": "to", + "in": "query", + "required": false, + "type": "string", + "format": "date-time" } } } -- cgit v1.2.3 From 4508d17884da22557527ac29826952822ffe365a Mon Sep 17 00:00:00 2001 From: Sun Howwrongbum Date: Tue, 6 Dec 2016 04:24:23 +0530 Subject: [swagger] Describe /users and /commandtypes --- swagger.json | 82 ++++++++++++++---------------------------------------------- 1 file changed, 19 insertions(+), 63 deletions(-) diff --git a/swagger.json b/swagger.json index a4ff0d0f6..27efbcc23 100644 --- a/swagger.json +++ b/swagger.json @@ -588,33 +588,24 @@ }, "/users": { "get": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], + "summary": "Fetch a list of Users", "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "type": "array", "items": { "$ref": "#/definitions/User" } } + }, + "400": { + "description": "No Permission" } } }, "post": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Create a User", "parameters": [ { "name": "body", @@ -628,7 +619,6 @@ "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "$ref": "#/definitions/User" } @@ -638,18 +628,10 @@ }, "/users/{id}": { "put": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Update a User", "parameters": [ { - "name": "id", - "in": "path", - "required": true, - "type": "integer" + "$ref": "#/parameters/entityId" }, { "name": "body", @@ -663,7 +645,6 @@ "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "$ref": "#/definitions/User" } @@ -671,54 +652,38 @@ } }, "delete": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Delete a User", "parameters": [ { - "name": "id", - "in": "path", - "required": true, - "type": "integer" + "$ref": "#/parameters/entityId" } ], "responses": { "204": { - "description": "No Content", - "headers": {} + "description": "No Content" } } } }, "/users/notifications": { "get": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Fetch a list of Notification types", + "description": "Without params, it returns a list of the user's enabled Notifications", "parameters": [ { "name": "all", "in": "query", + "description": "To fetch a list of all available Notifications", "required": true, "type": "boolean" }, { - "name": "userId", - "in": "query", - "required": true, - "type": "integer" + "$ref": "#/parameters/userId" } ], "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "type": "array", "items": { @@ -729,12 +694,7 @@ } }, "post": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Set or unset a Notification", "parameters": [ { "name": "body", @@ -748,7 +708,6 @@ "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "$ref": "#/definitions/Notification" } @@ -758,12 +717,7 @@ }, "/commandtypes": { "get": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Fetch a list of available Commands for the Device", "parameters": [ { "name": "deviceId", @@ -775,13 +729,15 @@ "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "type": "array", "items": { "$ref": "#/definitions/CommandType" } } + }, + "400": { + "description": "Could happen when trying to fetch from an pffline device or the user does not have permission" } } } -- cgit v1.2.3 From 0179fd16451d738302ff8a5e7384da7f2771ee92 Mon Sep 17 00:00:00 2001 From: Sun Howwrongbum Date: Tue, 6 Dec 2016 04:53:27 +0530 Subject: [swagger] Update /geofences and /events --- swagger.json | 65 ++++++++++-------------------------------------------------- 1 file changed, 10 insertions(+), 55 deletions(-) diff --git a/swagger.json b/swagger.json index 27efbcc23..2a3690e11 100644 --- a/swagger.json +++ b/swagger.json @@ -744,35 +744,25 @@ }, "/geofences": { "get": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Fetch a list of Geofences", + "description": "Without params, it returns a list of Geofences the user has access to", "parameters": [ { - "name": "all", - "in": "query", - "required": true, - "type": "boolean" + "$ref": "#/parameters/all" }, { "name": "userId", "in": "query", - "required": true, "type": "integer" }, { "name": "groupId", "in": "query", - "required": true, "type": "integer" }, { "name": "deviceId", "in": "query", - "required": true, "type": "integer" }, { @@ -785,7 +775,6 @@ "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "type": "array", "items": { @@ -796,12 +785,7 @@ } }, "post": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Create a Geofence", "parameters": [ { "name": "body", @@ -815,7 +799,6 @@ "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "$ref": "#/definitions/Geofence" } @@ -825,18 +808,10 @@ }, "/geofences/{id}": { "put": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Update a Geofence", "parameters": [ { - "name": "id", - "in": "path", - "required": true, - "type": "integer" + "$ref": "#/parameters/entityId" }, { "name": "body", @@ -850,7 +825,6 @@ "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "$ref": "#/definitions/Geofence" } @@ -858,48 +832,29 @@ } }, "delete": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Delete a Geofence", "parameters": [ { - "name": "id", - "in": "path", - "required": true, - "type": "integer" + "$ref": "#/parameters/entityId" } ], "responses": { "204": { - "description": "No Content", - "headers": {} + "description": "No Content" } } } }, "/events/{id}": { "get": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], "parameters": [ { - "name": "id", - "in": "path", - "required": true, - "type": "integer" + "$ref": "#/parameters/entityId" } ], "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "$ref": "#/definitions/Event" } -- cgit v1.2.3 From 733bddeced3834f01bedf7c66760e4dd75b0c35d Mon Sep 17 00:00:00 2001 From: Sun Howwrongbum Date: Tue, 6 Dec 2016 05:12:26 +0530 Subject: [swagger] Update /reports and /statistics - refactor params, unreference previous params because their use case was once only --- swagger.json | 203 +++++++++++++++++------------------------------------------ 1 file changed, 58 insertions(+), 145 deletions(-) diff --git a/swagger.json b/swagger.json index 2a3690e11..2f7833da6 100644 --- a/swagger.json +++ b/swagger.json @@ -462,10 +462,18 @@ "type": "integer" }, { - "$ref": "#/parameters/fromTime" + "name": "from", + "in": "query", + "required": false, + "type": "string", + "format": "date-time" }, { - "$ref": "#/parameters/toTime" + "name": "to", + "in": "query", + "required": false, + "type": "string", + "format": "date-time" }, { "name" : "id", @@ -864,50 +872,25 @@ }, "/reports/route": { "get": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Fetch a list of Positions within the time period for the Devices or Groups", + "description": "At least one _deviceId_ or one _groupId_ must be passed", "parameters": [ { - "name": "deviceId", - "in": "query", - "description": "at least one deviceId or one groupId must be passed", - "required": true, - "type": "array", - "items": { - "type": "integer" - } + "$ref": "#/parameters/deviceIdArray" }, { - "name": "groupId", - "in": "query", - "description": "at least one deviceId or one groupId must be passed", - "required": true, - "type": "array", - "items": { - "type": "integer" - } + "$ref": "#/parameters/groupIdArray" }, { - "name": "from", - "in": "query", - "required": true, - "type": "string" + "$ref": "#/parameters/fromTime" }, { - "name": "to", - "in": "query", - "required": true, - "type": "string" + "$ref": "#/parameters/toTime" } ], "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "type": "array", "items": { @@ -920,60 +903,34 @@ }, "/reports/events": { "get": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Fetch a list of Events within the time period for the Devices or Groups", + "description": "At least one _deviceId_ or one _groupId_ must be passed", "parameters": [ { - "name": "deviceId", - "in": "query", - "description": "at least one deviceId or one groupId must be passed", - "required": true, - "type": "array", - "items": { - "type": "integer" - } + "$ref": "#/parameters/deviceIdArray" }, { - "name": "groupId", - "in": "query", - "description": "at least one deviceId or one groupId must be passed", - "required": true, - "type": "array", - "items": { - "type": "integer" - } + "$ref": "#/parameters/groupIdArray" }, { "name": "type", "in": "query", "description": "% can be used to return events of all types", - "required": true, "type": "array", "items": { "type": "string" } }, { - "name": "from", - "in": "query", - "required": true, - "type": "string" + "$ref": "#/parameters/fromTime" }, { - "name": "to", - "in": "query", - "required": true, - "type": "string" + "$ref": "#/parameters/toTime" } ], "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "type": "array", "items": { @@ -986,50 +943,25 @@ }, "/reports/summary": { "get": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Fetch a list of ReportSummary within the time period for the Devices or Groups", + "description": "At least one _deviceId_ or one _groupId_ must be passed", "parameters": [ { - "name": "deviceId", - "in": "query", - "description": "at least one deviceId or one groupId must be passed", - "required": true, - "type": "array", - "items": { - "type": "integer" - } + "$ref": "#/parameters/deviceIdArray" }, { - "name": "groupId", - "in": "query", - "description": "at least one deviceId or one groupId must be passed", - "required": true, - "type": "array", - "items": { - "type": "integer" - } + "$ref": "#/parameters/groupIdArray" }, { - "name": "from", - "in": "query", - "required": true, - "type": "string" + "$ref": "#/parameters/fromTime" }, { - "name": "to", - "in": "query", - "required": true, - "type": "string" + "$ref": "#/parameters/toTime" } ], "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "type": "array", "items": { @@ -1042,50 +974,25 @@ }, "/reports/trips": { "get": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Fetch a list of ReportTrips within the time period for the Devices or Groups", + "description": "At least one _deviceId_ or one _groupId_ must be passed", "parameters": [ { - "name": "deviceId", - "in": "query", - "description": "at least one deviceId or one groupId must be passed", - "required": true, - "type": "array", - "items": { - "type": "integer" - } + "$ref": "#/parameters/deviceIdArray" }, { - "name": "groupId", - "in": "query", - "description": "at least one deviceId or one groupId must be passed", - "required": true, - "type": "array", - "items": { - "type": "integer" - } + "$ref": "#/parameters/groupIdArray" }, { - "name": "from", - "in": "query", - "required": true, - "type": "string" + "$ref": "#/parameters/fromTime" }, { - "name": "to", - "in": "query", - "required": true, - "type": "string" + "$ref": "#/parameters/toTime" } ], "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "type": "array", "items": { @@ -1098,30 +1005,18 @@ }, "/statistics": { "get": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Fetch server Statistics", "parameters": [ { - "name": "from", - "in": "query", - "required": true, - "type": "string" + "$ref": "#/parameters/fromTime" }, { - "name": "to", - "in": "query", - "required": true, - "type": "string" + "$ref": "#/parameters/toTime" } ], "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "type": "array", "items": { @@ -1709,20 +1604,38 @@ "userId": { "name": "userId", "in": "query", - "description": "Standard users can use this with their only with their own _userId_", + "description": "Standard users can use this only with their own _userId_", "type": "integer" }, + "deviceIdArray": { + "name": "deviceId", + "in": "query", + "type": "array", + "items": { + "type": "integer" + }, + "collectionFormat": "multi" + }, + "groupIdArray": { + "name": "groupId", + "in": "query", + "type": "array", + "items": { + "type": "integer" + }, + "collectionFormat": "multi" + }, "fromTime": { "name": "from", "in": "query", - "required": false, + "required": true, "type": "string", "format": "date-time" }, "toTime": { "name": "to", "in": "query", - "required": false, + "required": true, "type": "string", "format": "date-time" } -- cgit v1.2.3 From af1cf1dfb92c61f203f3c9196d023ee2343ae9e6 Mon Sep 17 00:00:00 2001 From: Sun Howwrongbum Date: Tue, 6 Dec 2016 05:39:36 +0530 Subject: [swagger] Update /attributes and Models --- swagger.json | 104 ++++++++++++++++++++++++++++------------------------------- 1 file changed, 50 insertions(+), 54 deletions(-) diff --git a/swagger.json b/swagger.json index 2f7833da6..2e89498b2 100644 --- a/swagger.json +++ b/swagger.json @@ -1029,12 +1029,8 @@ }, "/attributes/aliases": { "get": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Fetch a list of AttributeAlias", + "description": "Without params, it returns a list of AttributeAlias from all the user's Devices", "parameters": [ { "name": "deviceId", @@ -1046,7 +1042,6 @@ "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "type": "array", "items": { @@ -1057,12 +1052,7 @@ } }, "post": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Set an AttributeAlias", "parameters": [ { "name": "body", @@ -1076,7 +1066,6 @@ "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "$ref": "#/definitions/AttributeAlias" } @@ -1086,18 +1075,10 @@ }, "/attributes/aliases/{id}": { "put": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Update an AttributeAlias", "parameters": [ { - "name": "id", - "in": "path", - "required": true, - "type": "integer" + "$ref": "#/parameters/entityId" }, { "name": "body", @@ -1111,7 +1092,6 @@ "responses": { "200": { "description": "OK", - "headers": {}, "schema": { "$ref": "#/definitions/AttributeAlias" } @@ -1119,24 +1099,15 @@ } }, "delete": { - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "summary": "Delete an AttributeAlias", "parameters": [ { - "name": "id", - "in": "path", - "required": true, - "type": "integer" + "$ref": "#/parameters/entityId" } ], "responses": { "204": { - "description": "No Content", - "headers": {} + "description": "No Content" } } } @@ -1155,10 +1126,16 @@ "type": "string" }, "deviceTime": { - "type": "string" + "type": "string", + "format": "date-time" }, "fixTime": { - "type": "string" + "type": "string", + "format": "date-time" + }, + "serverTime": { + "type": "string", + "format": "date-time" }, "outdated": { "type": "boolean" @@ -1176,7 +1153,8 @@ "type": "number" }, "speed": { - "type": "number" + "type": "number", + "description": "In knots" }, "course": { "type": "number" @@ -1235,7 +1213,8 @@ "type": "boolean" }, "expirationTime": { - "type": "string" + "type": "string", + "format": "date-time" }, "deviceLimit": { "type": "integer" @@ -1322,7 +1301,8 @@ "type": "string" }, "lastUpdate": { - "type": "string" + "type": "string", + "format": "date-time" }, "positionId": { "type": "integer" @@ -1342,7 +1322,12 @@ "category": { "type": "string" }, - "geofenceIds": {}, + "geofenceIds": { + "type": "array", + "items": { + "type": "integer" + } + }, "attributes": {} } }, @@ -1457,7 +1442,8 @@ "type": "string" }, "serverTime": { - "type": "string" + "type": "string", + "format": "date-time" }, "deviceId": { "type": "integer" @@ -1480,13 +1466,16 @@ "type": "string" }, "maxSpeed": { - "type": "number" + "type": "number", + "description": "in knots" }, "averageSpeed": { - "type": "number" + "type": "number", + "description": "in knots" }, "distance": { - "type": "number" + "type": "number", + "description": "in meters" }, "engineHours": { "type": "integer" @@ -1502,19 +1491,23 @@ "type": "string" }, "maxSpeed": { - "type": "number" + "type": "number", + "description": "in knots" }, "averageSpeed": { - "type": "number" + "type": "number", + "description": "in knots" }, "distance": { - "type": "number" + "type": "number", + "description": "in meters" }, "duration": { "type": "integer" }, "startTime": { - "type": "string" + "type": "string", + "format": "date-time" }, "startAddress": { "type": "string" @@ -1526,7 +1519,8 @@ "type": "number" }, "endTime": { - "type": "string" + "type": "string", + "format": "date-time" }, "endAddress": { "type": "string" @@ -1542,7 +1536,8 @@ "Statistics": { "properties": { "captureTime": { - "type": "string" + "type": "string", + "format": "date-time" }, "activeUsers": { "type": "integer" @@ -1583,7 +1578,8 @@ "type": "integer" }, "totalDistance": { - "type": "number" + "type": "number", + "description": "in meters" } } } -- cgit v1.2.3 From 10692907db3ed2b9550184c9272f58e78497b3bf Mon Sep 17 00:00:00 2001 From: Sun Howwrongbum Date: Tue, 6 Dec 2016 06:16:48 +0530 Subject: [swagger] Make reference most params --- swagger.json | 240 +++++++++++++++++++++++++++-------------------------------- 1 file changed, 109 insertions(+), 131 deletions(-) diff --git a/swagger.json b/swagger.json index 2e89498b2..64171cb79 100644 --- a/swagger.json +++ b/swagger.json @@ -73,12 +73,7 @@ "summary": "Create a Device", "parameters": [ { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/Device" - } + "$ref": "#/parameters/DeviceInBody" } ], "responses": { @@ -99,12 +94,7 @@ "$ref": "#/parameters/entityId" }, { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/Device" - } + "$ref": "#/parameters/DeviceInBody" } ], "responses": { @@ -158,12 +148,7 @@ "summary": "Link a Geofence to a Device", "parameters": [ { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/DeviceGeofence" - } + "$ref": "#/parameters/DeviceGeofenceInBody" } ], "responses": { @@ -179,12 +164,7 @@ "summary": "Remove a Geofence from a Device", "parameters": [ { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/DeviceGeofence" - } + "$ref": "#/parameters/DeviceGeofenceInBody" } ], "responses": { @@ -222,12 +202,7 @@ "summary": "Create a Group", "parameters": [ { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/Group" - } + "$ref": "#/parameters/GroupInBody" } ], "responses": { @@ -251,12 +226,7 @@ "$ref": "#/parameters/entityId" }, { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/Group" - } + "$ref": "#/parameters/GroupInBody" } ], "responses": { @@ -287,12 +257,7 @@ "summary": "Link a Geofence to a Group", "parameters": [ { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/GroupGeofence" - } + "$ref": "#/parameters/GroupGeofenceInBody" } ], "responses": { @@ -308,12 +273,7 @@ "summary": "Remove a Geofence from a Group", "parameters": [ { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/GroupGeofence" - } + "$ref": "#/parameters/GroupGeofenceInBody" } ], "responses": { @@ -328,12 +288,7 @@ "summary": "Link a Device to a User", "parameters": [ { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/DevicePermission" - } + "$ref": "#/parameters/DevicePermissionInBody" } ], "responses": { @@ -352,12 +307,7 @@ "summary": "Remove a Device from a User", "parameters": [ { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/DevicePermission" - } + "$ref": "#/parameters/DevicePermissionInBody" } ], "responses": { @@ -372,12 +322,7 @@ "summary": "Link a Group to a User", "parameters": [ { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/GroupPermission" - } + "$ref": "#/parameters/GroupPermissionInBody" } ], "responses": { @@ -393,12 +338,7 @@ "summary": "Remove a Group from a User", "parameters": [ { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/GroupPermission" - } + "$ref": "#/parameters/GroupPermissionInBody" } ], "responses": { @@ -413,12 +353,7 @@ "summary": "Link a Geofence to a User", "parameters": [ { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/GeofencePermission" - } + "$ref": "#/parameters/GeofencePermissionInBody" } ], "responses": { @@ -434,12 +369,7 @@ "summary": "Remove a Geofence from a User", "parameters": [ { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/GeofencePermission" - } + "$ref": "#/parameters/GeofencePermissionInBody" } ], "responses": { @@ -616,12 +546,7 @@ "summary": "Create a User", "parameters": [ { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/User" - } + "$ref": "#/parameters/UserInBody" } ], "responses": { @@ -642,12 +567,7 @@ "$ref": "#/parameters/entityId" }, { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/User" - } + "$ref": "#/parameters/UserInBody" } ], "responses": { @@ -682,7 +602,6 @@ "name": "all", "in": "query", "description": "To fetch a list of all available Notifications", - "required": true, "type": "boolean" }, { @@ -759,9 +678,7 @@ "$ref": "#/parameters/all" }, { - "name": "userId", - "in": "query", - "type": "integer" + "$ref": "#/parameters/userId" }, { "name": "groupId", @@ -769,9 +686,7 @@ "type": "integer" }, { - "name": "deviceId", - "in": "query", - "type": "integer" + "$ref": "#/parameters/deviceId" }, { "name": "refresh", @@ -796,12 +711,7 @@ "summary": "Create a Geofence", "parameters": [ { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/Geofence" - } + "$ref": "#/parameters/GeofenceInBody" } ], "responses": { @@ -822,12 +732,7 @@ "$ref": "#/parameters/entityId" }, { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/Geofence" - } + "$ref": "#/parameters/GeofenceInBody" } ], "responses": { @@ -1033,10 +938,7 @@ "description": "Without params, it returns a list of AttributeAlias from all the user's Devices", "parameters": [ { - "name": "deviceId", - "in": "query", - "required": false, - "type": "integer" + "$ref": "#/parameters/deviceId" } ], "responses": { @@ -1055,12 +957,7 @@ "summary": "Set an AttributeAlias", "parameters": [ { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/AttributeAlias" - } + "$ref": "#/parameters/AttributeAliasInBody" } ], "responses": { @@ -1081,12 +978,7 @@ "$ref": "#/parameters/entityId" }, { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/AttributeAlias" - } + "$ref": "#/parameters/AttributeAliasInBody" } ], "responses": { @@ -1603,6 +1495,92 @@ "description": "Standard users can use this only with their own _userId_", "type": "integer" }, + "deviceId": { + "name": "deviceId", + "in": "query", + "description": "Standard users can use this only with _userId_s, they have access to", + "type": "integer" + }, + "DeviceInBody": { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/Device" + } + }, + "DeviceGeofenceInBody": { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/DeviceGeofence" + } + }, + "GroupInBody": { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/Group" + } + }, + "GroupGeofenceInBody": { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/GroupGeofence" + } + }, + "DevicePermissionInBody": { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/DevicePermission" + } + }, + "GroupPermissionInBody": { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/GroupPermission" + } + }, + "GeofencePermissionInBody": { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/GeofencePermission" + } + }, + "UserInBody": { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/User" + } + }, + "GeofenceInBody": { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/Geofence" + } + }, + "AttributeAliasInBody": { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/AttributeAlias" + } + }, "deviceIdArray": { "name": "deviceId", "in": "query", -- cgit v1.2.3 From 8d4d1a78ef0c58a74a6fa349488dfaa29daa7020 Mon Sep 17 00:00:00 2001 From: Sun Howwrongbum Date: Tue, 13 Dec 2016 08:01:52 +0530 Subject: Update version in swagger.json --- swagger.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/swagger.json b/swagger.json index 64171cb79..8577a106f 100644 --- a/swagger.json +++ b/swagger.json @@ -1,7 +1,7 @@ { "swagger": "2.0", "info": { - "version": "3.8", + "version": "3.9", "title": "traccar" }, "host": "traccar.org", -- cgit v1.2.3 From 8458c73893db3e64a865589f7a01455ad28f7dd6 Mon Sep 17 00:00:00 2001 From: Sun Howwrongbum Date: Tue, 13 Dec 2016 08:14:29 +0530 Subject: Add API docs --- docs/api.md | 822 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 822 insertions(+) create mode 100644 docs/api.md diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 000000000..0ceb9467b --- /dev/null +++ b/docs/api.md @@ -0,0 +1,822 @@ +# traccar +__Version__: 3.9 +__Base URL__: http://traccar.org/api + +### Contents +[Paths](#paths) +- [attributes](#paths_attributes) + - [PUT /attributes/aliases/{id}](#paths_attributesaliasesid_PUT) + - [DELETE /attributes/aliases/{id}](#paths_attributesaliasesid_DELETE) + - [POST /attributes/aliases](#paths_attributesaliases_POST) + - [GET /attributes/aliases](#paths_attributesaliases_GET) +- [commands](#paths_commands) + - [POST /commands](#paths_commands_POST) +- [commandtypes](#paths_commandtypes) + - [GET /commandtypes](#paths_commandtypes_GET) +- [devices](#paths_devices) + - [POST /devices](#paths_devices_POST) + - [GET /devices](#paths_devices_GET) + - [POST /devices/geofences](#paths_devicesgeofences_POST) + - [DELETE /devices/geofences](#paths_devicesgeofences_DELETE) + - [PUT /devices/{id}](#paths_devicesid_PUT) + - [DELETE /devices/{id}](#paths_devicesid_DELETE) + - [PUT /devices/{id}/distance](#paths_devicesiddistance_PUT) +- [events](#paths_events) + - [GET /events/{id}](#paths_eventsid_GET) +- [geofences](#paths_geofences) + - [PUT /geofences/{id}](#paths_geofencesid_PUT) + - [DELETE /geofences/{id}](#paths_geofencesid_DELETE) + - [POST /geofences](#paths_geofences_POST) + - [GET /geofences](#paths_geofences_GET) +- [groups](#paths_groups) + - [POST /groups/geofences](#paths_groupsgeofences_POST) + - [DELETE /groups/geofences](#paths_groupsgeofences_DELETE) + - [POST /groups](#paths_groups_POST) + - [GET /groups](#paths_groups_GET) + - [PUT /groups/{id}](#paths_groupsid_PUT) + - [DELETE /groups/{id}](#paths_groupsid_DELETE) +- [permissions](#paths_permissions) + - [POST /permissions/devices](#paths_permissionsdevices_POST) + - [DELETE /permissions/devices](#paths_permissionsdevices_DELETE) + - [POST /permissions/geofences](#paths_permissionsgeofences_POST) + - [DELETE /permissions/geofences](#paths_permissionsgeofences_DELETE) + - [POST /permissions/groups](#paths_permissionsgroups_POST) + - [DELETE /permissions/groups](#paths_permissionsgroups_DELETE) +- [positions](#paths_positions) + - [GET /positions](#paths_positions_GET) +- [reports](#paths_reports) + - [GET /reports/summary](#paths_reportssummary_GET) + - [GET /reports/events](#paths_reportsevents_GET) + - [GET /reports/route](#paths_reportsroute_GET) + - [GET /reports/trips](#paths_reportstrips_GET) +- [server](#paths_server) + - [PUT /server](#paths_server_PUT) + - [GET /server](#paths_server_GET) +- [session](#paths_session) + - [POST /session](#paths_session_POST) + - [DELETE /session](#paths_session_DELETE) + - [GET /session](#paths_session_GET) +- [statistics](#paths_statistics) + - [GET /statistics](#paths_statistics_GET) +- [users](#paths_users) + - [POST /users/notifications](#paths_usersnotifications_POST) + - [GET /users/notifications](#paths_usersnotifications_GET) + - [PUT /users/{id}](#paths_usersid_PUT) + - [DELETE /users/{id}](#paths_usersid_DELETE) + - [POST /users](#paths_users_POST) + - [GET /users](#paths_users_GET) + +[Models](#definitions) +- [AttributeAlias](#definitions_AttributeAlias) +- [Command](#definitions_Command) +- [CommandType](#definitions_CommandType) +- [Device](#definitions_Device) +- [DeviceGeofence](#definitions_DeviceGeofence) +- [DevicePermission](#definitions_DevicePermission) +- [DeviceTotalDistance](#definitions_DeviceTotalDistance) +- [Event](#definitions_Event) +- [Geofence](#definitions_Geofence) +- [GeofencePermission](#definitions_GeofencePermission) +- [Group](#definitions_Group) +- [GroupGeofence](#definitions_GroupGeofence) +- [GroupPermission](#definitions_GroupPermission) +- [Notification](#definitions_Notification) +- [Position](#definitions_Position) +- [ReportSummary](#definitions_ReportSummary) +- [ReportTrips](#definitions_ReportTrips) +- [Server](#definitions_Server) +- [Statistics](#definitions_Statistics) +- [User](#definitions_User) + +## Paths +### attributes +#### `PUT /attributes/aliases/{id}` +__Summary__: Update an AttributeAlias +##### Parameters +Name | ParamType | Required | DataType | Schema +--- | --- | --- | --- | --- +_id_ | path | __True__ | _integer_ | +_body_ | body | __True__ | | [AttributeAlias](#definitions_AttributeAlias) +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [AttributeAlias](#definitions_AttributeAlias) +#### `DELETE /attributes/aliases/{id}` +__Summary__: Delete an AttributeAlias +##### Parameters +Name | ParamType | Required | DataType +--- | --- | --- | --- +_id_ | path | __True__ | _integer_ +##### Responses +Status Code | Description +--- | --- +_204_ | No Content +#### `POST /attributes/aliases` +__Summary__: Set an AttributeAlias +##### Parameters +Name | ParamType | Required | Schema +--- | --- | --- | --- +_body_ | body | __True__ | [AttributeAlias](#definitions_AttributeAlias) +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [AttributeAlias](#definitions_AttributeAlias) +#### `GET /attributes/aliases` +__Summary__: Fetch a list of AttributeAlias +__Description__: Without params, it returns a list of AttributeAlias from all the user's Devices +##### Parameters +Name | ParamType | Description | DataType +--- | --- | --- | --- +_deviceId_ | query | Standard users can use this only with _userId_s, they have access to | _integer_ +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [ [AttributeAlias](#definitions_AttributeAlias) ] + +### commands +#### `POST /commands` +__Summary__: Dispatch commands to device +##### Parameters +Name | ParamType | Required | Schema +--- | --- | --- | --- +_body_ | body | __True__ | [Command](#definitions_Command) +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [Command](#definitions_Command) +_400_ | Could happen when dispatching to a device that is offline, the user doesn't have permission or an incorrect command _type_ for the device | + +### commandtypes +#### `GET /commandtypes` +__Summary__: Fetch a list of available Commands for the Device +##### Parameters +Name | ParamType | Required | DataType +--- | --- | --- | --- +_deviceId_ | query | __True__ | _integer_ +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [ [CommandType](#definitions_CommandType) ] +_400_ | Could happen when trying to fetch from an pffline device or the user does not have permission | + +### devices +#### `POST /devices` +__Summary__: Create a Device +##### Parameters +Name | ParamType | Required | Schema +--- | --- | --- | --- +_body_ | body | __True__ | [Device](#definitions_Device) +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [Device](#definitions_Device) +#### `GET /devices` +__Summary__: Fetch a list of Devices +__Description__: Without any params, returns a list of the user's devices +##### Parameters +Name | ParamType | Description | DataType +--- | --- | --- | --- +_all_ | query | Can only be used by admin users to fetch all entities | _boolean_ +_userId_ | query | Standard users can use this only with their own _userId_ | _integer_ +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [ [Device](#definitions_Device) ] +_400_ | No permission | +#### `POST /devices/geofences` +__Summary__: Link a Geofence to a Device +##### Parameters +Name | ParamType | Required | Schema +--- | --- | --- | --- +_body_ | body | __True__ | [DeviceGeofence](#definitions_DeviceGeofence) +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [DeviceGeofence](#definitions_DeviceGeofence) +#### `DELETE /devices/geofences` +__Summary__: Remove a Geofence from a Device +##### Parameters +Name | ParamType | Required | Schema +--- | --- | --- | --- +_body_ | body | __True__ | [DeviceGeofence](#definitions_DeviceGeofence) +##### Responses +Status Code | Description +--- | --- +_204_ | No Content +#### `PUT /devices/{id}` +__Summary__: Update a Device +##### Parameters +Name | ParamType | Required | DataType | Schema +--- | --- | --- | --- | --- +_id_ | path | __True__ | _integer_ | +_body_ | body | __True__ | | [Device](#definitions_Device) +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [Device](#definitions_Device) +#### `DELETE /devices/{id}` +__Summary__: Update a Device +##### Parameters +Name | ParamType | Required | DataType +--- | --- | --- | --- +_id_ | path | __True__ | _integer_ +##### Responses +Status Code | Description +--- | --- +_204_ | No Content +#### `PUT /devices/{id}/distance` +__Summary__: Update the distance counter of the Device +##### Parameters +Name | ParamType | Required | DataType | Schema +--- | --- | --- | --- | --- +_id_ | path | __True__ | _integer_ | +_body_ | body | __True__ | | [DeviceTotalDistance](#definitions_DeviceTotalDistance) +##### Responses +Status Code | Description +--- | --- +_204_ | No Content + +### events +#### `GET /events/{id}` +##### Parameters +Name | ParamType | Required | DataType +--- | --- | --- | --- +_id_ | path | __True__ | _integer_ +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [Event](#definitions_Event) + +### geofences +#### `PUT /geofences/{id}` +__Summary__: Update a Geofence +##### Parameters +Name | ParamType | Required | DataType | Schema +--- | --- | --- | --- | --- +_id_ | path | __True__ | _integer_ | +_body_ | body | __True__ | | [Geofence](#definitions_Geofence) +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [Geofence](#definitions_Geofence) +#### `DELETE /geofences/{id}` +__Summary__: Delete a Geofence +##### Parameters +Name | ParamType | Required | DataType +--- | --- | --- | --- +_id_ | path | __True__ | _integer_ +##### Responses +Status Code | Description +--- | --- +_204_ | No Content +#### `POST /geofences` +__Summary__: Create a Geofence +##### Parameters +Name | ParamType | Required | Schema +--- | --- | --- | --- +_body_ | body | __True__ | [Geofence](#definitions_Geofence) +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [Geofence](#definitions_Geofence) +#### `GET /geofences` +__Summary__: Fetch a list of Geofences +__Description__: Without params, it returns a list of Geofences the user has access to +##### Parameters +Name | ParamType | Description | Required | DataType +--- | --- | --- | --- | --- +_all_ | query | Can only be used by admin users to fetch all entities | | _boolean_ +_userId_ | query | Standard users can use this only with their own _userId_ | | _integer_ +_groupId_ | query | | | _integer_ +_deviceId_ | query | Standard users can use this only with _userId_s, they have access to | | _integer_ +_refresh_ | query | | False | _boolean_ +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [ [Geofence](#definitions_Geofence) ] + +### groups +#### `POST /groups/geofences` +__Summary__: Link a Geofence to a Group +##### Parameters +Name | ParamType | Required | Schema +--- | --- | --- | --- +_body_ | body | __True__ | [GroupGeofence](#definitions_GroupGeofence) +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [GroupGeofence](#definitions_GroupGeofence) +#### `DELETE /groups/geofences` +__Summary__: Remove a Geofence from a Group +##### Parameters +Name | ParamType | Required | Schema +--- | --- | --- | --- +_body_ | body | __True__ | [GroupGeofence](#definitions_GroupGeofence) +##### Responses +Status Code | Description +--- | --- +_204_ | No Content +#### `POST /groups` +__Summary__: Create a Group +##### Parameters +Name | ParamType | Required | Schema +--- | --- | --- | --- +_body_ | body | __True__ | [Group](#definitions_Group) +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [Group](#definitions_Group) +_400_ | No permission | +#### `GET /groups` +__Summary__: Fetch a list of Groups +__Description__: Without any params, returns a list of the Groups the user belongs to +##### Parameters +Name | ParamType | Description | DataType +--- | --- | --- | --- +_all_ | query | Can only be used by admin users to fetch all entities | _boolean_ +_userId_ | query | Standard users can use this only with their own _userId_ | _integer_ +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [ [Group](#definitions_Group) ] +#### `PUT /groups/{id}` +__Summary__: Update a Group +##### Parameters +Name | ParamType | Required | DataType | Schema +--- | --- | --- | --- | --- +_id_ | path | __True__ | _integer_ | +_body_ | body | __True__ | | [Group](#definitions_Group) +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [Group](#definitions_Group) +#### `DELETE /groups/{id}` +__Summary__: Delete a Group +##### Parameters +Name | ParamType | Required | DataType +--- | --- | --- | --- +_id_ | path | __True__ | _integer_ +##### Responses +Status Code | Description +--- | --- +_204_ | No Content + +### permissions +#### `POST /permissions/devices` +__Summary__: Link a Device to a User +##### Parameters +Name | ParamType | Required | Schema +--- | --- | --- | --- +_body_ | body | __True__ | [DevicePermission](#definitions_DevicePermission) +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [DevicePermission](#definitions_DevicePermission) +_400_ | No permission | +#### `DELETE /permissions/devices` +__Summary__: Remove a Device from a User +##### Parameters +Name | ParamType | Required | Schema +--- | --- | --- | --- +_body_ | body | __True__ | [DevicePermission](#definitions_DevicePermission) +##### Responses +Status Code | Description +--- | --- +_204_ | No Content +#### `POST /permissions/geofences` +__Summary__: Link a Geofence to a User +##### Parameters +Name | ParamType | Required | Schema +--- | --- | --- | --- +_body_ | body | __True__ | [GeofencePermission](#definitions_GeofencePermission) +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [GeofencePermission](#definitions_GeofencePermission) +#### `DELETE /permissions/geofences` +__Summary__: Remove a Geofence from a User +##### Parameters +Name | ParamType | Required | Schema +--- | --- | --- | --- +_body_ | body | __True__ | [GeofencePermission](#definitions_GeofencePermission) +##### Responses +Status Code | Description +--- | --- +_204_ | No Content +#### `POST /permissions/groups` +__Summary__: Link a Group to a User +##### Parameters +Name | ParamType | Required | Schema +--- | --- | --- | --- +_body_ | body | __True__ | [GroupPermission](#definitions_GroupPermission) +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [GroupPermission](#definitions_GroupPermission) +#### `DELETE /permissions/groups` +__Summary__: Remove a Group from a User +##### Parameters +Name | ParamType | Required | Schema +--- | --- | --- | --- +_body_ | body | __True__ | [GroupPermission](#definitions_GroupPermission) +##### Responses +Status Code | Description +--- | --- +_204_ | No Content + +### positions +#### `GET /positions` +__Summary__: Fetches a list of Positions +__Description__: Without any params, it returns a list of last known positions for all the user's Devices. _from_ and _to_ fields are not required with _id_ +##### Parameters +Name | ParamType | Description | Required | DataType +--- | --- | --- | --- | --- +_deviceId_ | query | _deviceId_ is optional, but requires the _from_ and _to_ parameters when used | False | _integer_ +_from_ | query | | False | _string (date-time)_ +_to_ | query | | False | _string (date-time)_ +_id_ | query | To fetch one or more positions. Multiple params can be passed like `id=31&id=42` | False | _integer_ +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [ [Position](#definitions_Position) ] + +### reports +#### `GET /reports/summary` +__Summary__: Fetch a list of ReportSummary within the time period for the Devices or Groups +__Description__: At least one _deviceId_ or one _groupId_ must be passed +##### Parameters +Name | ParamType | Required | DataType +--- | --- | --- | --- +_deviceId_ | query | | [ _integer_ ] +_groupId_ | query | | [ _integer_ ] +_from_ | query | __True__ | _string (date-time)_ +_to_ | query | __True__ | _string (date-time)_ +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [ [ReportSummary](#definitions_ReportSummary) ] +#### `GET /reports/events` +__Summary__: Fetch a list of Events within the time period for the Devices or Groups +__Description__: At least one _deviceId_ or one _groupId_ must be passed +##### Parameters +Name | ParamType | Description | Required | DataType +--- | --- | --- | --- | --- +_deviceId_ | query | | | [ _integer_ ] +_groupId_ | query | | | [ _integer_ ] +_type_ | query | % can be used to return events of all types | | [ _string_ ] +_from_ | query | | __True__ | _string (date-time)_ +_to_ | query | | __True__ | _string (date-time)_ +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [ [Event](#definitions_Event) ] +#### `GET /reports/route` +__Summary__: Fetch a list of Positions within the time period for the Devices or Groups +__Description__: At least one _deviceId_ or one _groupId_ must be passed +##### Parameters +Name | ParamType | Required | DataType +--- | --- | --- | --- +_deviceId_ | query | | [ _integer_ ] +_groupId_ | query | | [ _integer_ ] +_from_ | query | __True__ | _string (date-time)_ +_to_ | query | __True__ | _string (date-time)_ +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [ [Position](#definitions_Position) ] +#### `GET /reports/trips` +__Summary__: Fetch a list of ReportTrips within the time period for the Devices or Groups +__Description__: At least one _deviceId_ or one _groupId_ must be passed +##### Parameters +Name | ParamType | Required | DataType +--- | --- | --- | --- +_deviceId_ | query | | [ _integer_ ] +_groupId_ | query | | [ _integer_ ] +_from_ | query | __True__ | _string (date-time)_ +_to_ | query | __True__ | _string (date-time)_ +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [ [ReportTrips](#definitions_ReportTrips) ] + +### server +#### `PUT /server` +__Summary__: Update Server information +##### Parameters +Name | ParamType | Required | Schema +--- | --- | --- | --- +_body_ | body | __True__ | [Server](#definitions_Server) +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [Server](#definitions_Server) +#### `GET /server` +__Summary__: Fetch Server information +##### Parameters +_None_ +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [Server](#definitions_Server) + +### session +#### `POST /session` +__Summary__: Create a new Session +##### Parameters +Name | ParamType | Required | DataType +--- | --- | --- | --- +_email_ | formData | __True__ | _string_ +_password_ | formData | __True__ | _string (password)_ +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [User](#definitions_User) +_401_ | Unauthorized | +#### `DELETE /session` +__Summary__: Close the Session +##### Parameters +_None_ +##### Responses +Status Code | Description +--- | --- +_204_ | No Content +#### `GET /session` +__Summary__: Fetch Session information +##### Parameters +_None_ +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [User](#definitions_User) +_404_ | Not Found | + +### statistics +#### `GET /statistics` +__Summary__: Fetch server Statistics +##### Parameters +Name | ParamType | Required | DataType +--- | --- | --- | --- +_from_ | query | __True__ | _string (date-time)_ +_to_ | query | __True__ | _string (date-time)_ +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [ [Statistics](#definitions_Statistics) ] + +### users +#### `POST /users/notifications` +__Summary__: Set or unset a Notification +##### Parameters +Name | ParamType | Required | Schema +--- | --- | --- | --- +_body_ | body | __True__ | [Notification](#definitions_Notification) +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [Notification](#definitions_Notification) +#### `GET /users/notifications` +__Summary__: Fetch a list of Notification types +__Description__: Without params, it returns a list of the user's enabled Notifications +##### Parameters +Name | ParamType | Description | DataType +--- | --- | --- | --- +_all_ | query | To fetch a list of all available Notifications | _boolean_ +_userId_ | query | Standard users can use this only with their own _userId_ | _integer_ +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [ [Notification](#definitions_Notification) ] +#### `PUT /users/{id}` +__Summary__: Update a User +##### Parameters +Name | ParamType | Required | DataType | Schema +--- | --- | --- | --- | --- +_id_ | path | __True__ | _integer_ | +_body_ | body | __True__ | | [User](#definitions_User) +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [User](#definitions_User) +#### `DELETE /users/{id}` +__Summary__: Delete a User +##### Parameters +Name | ParamType | Required | DataType +--- | --- | --- | --- +_id_ | path | __True__ | _integer_ +##### Responses +Status Code | Description +--- | --- +_204_ | No Content +#### `POST /users` +__Summary__: Create a User +##### Parameters +Name | ParamType | Required | Schema +--- | --- | --- | --- +_body_ | body | __True__ | [User](#definitions_User) +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [User](#definitions_User) +#### `GET /users` +__Summary__: Fetch a list of Users +##### Parameters +_None_ +##### Responses +Status Code | Description | Schema +--- | --- | --- +_200_ | OK | [ [User](#definitions_User) ] +_400_ | No Permission | + + +## Models +### AttributeAlias +Property | Type +--- | --- +_alias_ | _string_ +_attribute_ | _string_ +_deviceId_ | _integer_ +_id_ | _integer_ +### Command +Property | Type +--- | --- +_attributes_ | +_deviceId_ | _integer_ +_type_ | _string_ +### CommandType +Property | Type +--- | --- +_type_ | _string_ +### Device +Property | Type +--- | --- +_attributes_ | +_category_ | _string_ +_contact_ | _string_ +_geofenceIds_ | _array_ +_groupId_ | _integer_ +_id_ | _integer_ +_lastUpdate_ | _string (date-time)_ +_model_ | _string_ +_name_ | _string_ +_phone_ | _string_ +_positionId_ | _integer_ +_status_ | _string_ +_uniqueId_ | _string_ +### DeviceGeofence +Property | Type +--- | --- +_deviceId_ | _integer_ +_geofenceId_ | _integer_ +### DevicePermission +Property | Type +--- | --- +_deviceId_ | _integer_ +_userId_ | _integer_ +### DeviceTotalDistance +Property | Type | Description +--- | --- | --- +_deviceId_ | _integer_ | +_totalDistance_ | _number_ | in meters +### Event +Property | Type +--- | --- +_attributes_ | +_deviceId_ | _integer_ +_geofenceId_ | _integer_ +_id_ | _integer_ +_positionId_ | _integer_ +_serverTime_ | _string (date-time)_ +_type_ | _string_ +### Geofence +Property | Type +--- | --- +_area_ | _string_ +_attributes_ | +_description_ | _string_ +_id_ | _integer_ +_name_ | _string_ +### GeofencePermission +Property | Type +--- | --- +_geofenceId_ | _integer_ +_userId_ | _integer_ +### Group +Property | Type +--- | --- +_attributes_ | +_groupId_ | _integer_ +_id_ | _integer_ +_name_ | _string_ +### GroupGeofence +Property | Type +--- | --- +_geofenceId_ | _integer_ +_groupId_ | _integer_ +### GroupPermission +Property | Type +--- | --- +_groupId_ | _integer_ +_userId_ | _integer_ +### Notification +Property | Type +--- | --- +_attributes_ | +_id_ | _integer_ +_type_ | _string_ +_userId_ | _integer_ +### Position +Property | Type | Description +--- | --- | --- +_address_ | _string_ | +_altitude_ | _number_ | +_attributes_ | | +_course_ | _number_ | +_deviceId_ | _integer_ | +_deviceTime_ | _string (date-time)_ | +_fixTime_ | _string (date-time)_ | +_id_ | _integer_ | +_latitude_ | _number_ | +_longitude_ | _number_ | +_outdated_ | _boolean_ | +_protocol_ | _string_ | +_serverTime_ | _string (date-time)_ | +_speed_ | _number_ | In knots +_valid_ | _boolean_ | +### ReportSummary +Property | Type | Description +--- | --- | --- +_averageSpeed_ | _number_ | in knots +_deviceId_ | _integer_ | +_deviceName_ | _string_ | +_distance_ | _number_ | in meters +_engineHours_ | _integer_ | +_maxSpeed_ | _number_ | in knots +### ReportTrips +Property | Type | Description +--- | --- | --- +_averageSpeed_ | _number_ | in knots +_deviceId_ | _integer_ | +_deviceName_ | _string_ | +_distance_ | _number_ | in meters +_duration_ | _integer_ | +_endAddress_ | _string_ | +_endLat_ | _number_ | +_endLon_ | _number_ | +_endTime_ | _string (date-time)_ | +_maxSpeed_ | _number_ | in knots +_startAddress_ | _string_ | +_startLat_ | _number_ | +_startLon_ | _number_ | +_startTime_ | _string (date-time)_ | +### Server +Property | Type +--- | --- +_attributes_ | +_bingKey_ | _string_ +_coordinateFormat_ | _string_ +_distanceUnit_ | _string_ +_forceSettings_ | _boolean_ +_id_ | _integer_ +_latitude_ | _number_ +_longitude_ | _number_ +_map_ | _string_ +_mapUrl_ | _string_ +_readonly_ | _boolean_ +_registration_ | _boolean_ +_speedUnit_ | _string_ +_twelveHourFormat_ | _boolean_ +_version_ | _string_ +_zoom_ | _integer_ +### Statistics +Property | Type +--- | --- +_activeDevices_ | _integer_ +_activeUsers_ | _integer_ +_captureTime_ | _string (date-time)_ +_messagesReceived_ | _integer_ +_messagesStored_ | _integer_ +_requests_ | _integer_ +### User +Property | Type +--- | --- +_admin_ | _boolean_ +_attributes_ | +_coordinateFormat_ | _string_ +_deviceLimit_ | _integer_ +_disabled_ | _boolean_ +_distanceUnit_ | _string_ +_email_ | _string_ +_expirationTime_ | _string (date-time)_ +_id_ | _integer_ +_latitude_ | _number_ +_longitude_ | _number_ +_map_ | _string_ +_name_ | _string_ +_password_ | _string_ +_readonly_ | _boolean_ +_speedUnit_ | _string_ +_token_ | _string_ +_twelveHourFormat_ | _boolean_ +_zoom_ | _integer_ + + -- cgit v1.2.3 From 207331d85159abad4e2557338fe144e857088b93 Mon Sep 17 00:00:00 2001 From: Sun Howwrongbum Date: Tue, 13 Dec 2016 09:41:10 +0530 Subject: [swagger] Fix typo - remove api docs --- docs/api.md | 822 ----------------------------------------------------------- swagger.json | 2 +- 2 files changed, 1 insertion(+), 823 deletions(-) delete mode 100644 docs/api.md diff --git a/docs/api.md b/docs/api.md deleted file mode 100644 index 0ceb9467b..000000000 --- a/docs/api.md +++ /dev/null @@ -1,822 +0,0 @@ -# traccar -__Version__: 3.9 -__Base URL__: http://traccar.org/api - -### Contents -[Paths](#paths) -- [attributes](#paths_attributes) - - [PUT /attributes/aliases/{id}](#paths_attributesaliasesid_PUT) - - [DELETE /attributes/aliases/{id}](#paths_attributesaliasesid_DELETE) - - [POST /attributes/aliases](#paths_attributesaliases_POST) - - [GET /attributes/aliases](#paths_attributesaliases_GET) -- [commands](#paths_commands) - - [POST /commands](#paths_commands_POST) -- [commandtypes](#paths_commandtypes) - - [GET /commandtypes](#paths_commandtypes_GET) -- [devices](#paths_devices) - - [POST /devices](#paths_devices_POST) - - [GET /devices](#paths_devices_GET) - - [POST /devices/geofences](#paths_devicesgeofences_POST) - - [DELETE /devices/geofences](#paths_devicesgeofences_DELETE) - - [PUT /devices/{id}](#paths_devicesid_PUT) - - [DELETE /devices/{id}](#paths_devicesid_DELETE) - - [PUT /devices/{id}/distance](#paths_devicesiddistance_PUT) -- [events](#paths_events) - - [GET /events/{id}](#paths_eventsid_GET) -- [geofences](#paths_geofences) - - [PUT /geofences/{id}](#paths_geofencesid_PUT) - - [DELETE /geofences/{id}](#paths_geofencesid_DELETE) - - [POST /geofences](#paths_geofences_POST) - - [GET /geofences](#paths_geofences_GET) -- [groups](#paths_groups) - - [POST /groups/geofences](#paths_groupsgeofences_POST) - - [DELETE /groups/geofences](#paths_groupsgeofences_DELETE) - - [POST /groups](#paths_groups_POST) - - [GET /groups](#paths_groups_GET) - - [PUT /groups/{id}](#paths_groupsid_PUT) - - [DELETE /groups/{id}](#paths_groupsid_DELETE) -- [permissions](#paths_permissions) - - [POST /permissions/devices](#paths_permissionsdevices_POST) - - [DELETE /permissions/devices](#paths_permissionsdevices_DELETE) - - [POST /permissions/geofences](#paths_permissionsgeofences_POST) - - [DELETE /permissions/geofences](#paths_permissionsgeofences_DELETE) - - [POST /permissions/groups](#paths_permissionsgroups_POST) - - [DELETE /permissions/groups](#paths_permissionsgroups_DELETE) -- [positions](#paths_positions) - - [GET /positions](#paths_positions_GET) -- [reports](#paths_reports) - - [GET /reports/summary](#paths_reportssummary_GET) - - [GET /reports/events](#paths_reportsevents_GET) - - [GET /reports/route](#paths_reportsroute_GET) - - [GET /reports/trips](#paths_reportstrips_GET) -- [server](#paths_server) - - [PUT /server](#paths_server_PUT) - - [GET /server](#paths_server_GET) -- [session](#paths_session) - - [POST /session](#paths_session_POST) - - [DELETE /session](#paths_session_DELETE) - - [GET /session](#paths_session_GET) -- [statistics](#paths_statistics) - - [GET /statistics](#paths_statistics_GET) -- [users](#paths_users) - - [POST /users/notifications](#paths_usersnotifications_POST) - - [GET /users/notifications](#paths_usersnotifications_GET) - - [PUT /users/{id}](#paths_usersid_PUT) - - [DELETE /users/{id}](#paths_usersid_DELETE) - - [POST /users](#paths_users_POST) - - [GET /users](#paths_users_GET) - -[Models](#definitions) -- [AttributeAlias](#definitions_AttributeAlias) -- [Command](#definitions_Command) -- [CommandType](#definitions_CommandType) -- [Device](#definitions_Device) -- [DeviceGeofence](#definitions_DeviceGeofence) -- [DevicePermission](#definitions_DevicePermission) -- [DeviceTotalDistance](#definitions_DeviceTotalDistance) -- [Event](#definitions_Event) -- [Geofence](#definitions_Geofence) -- [GeofencePermission](#definitions_GeofencePermission) -- [Group](#definitions_Group) -- [GroupGeofence](#definitions_GroupGeofence) -- [GroupPermission](#definitions_GroupPermission) -- [Notification](#definitions_Notification) -- [Position](#definitions_Position) -- [ReportSummary](#definitions_ReportSummary) -- [ReportTrips](#definitions_ReportTrips) -- [Server](#definitions_Server) -- [Statistics](#definitions_Statistics) -- [User](#definitions_User) - -## Paths -### attributes -#### `PUT /attributes/aliases/{id}` -__Summary__: Update an AttributeAlias -##### Parameters -Name | ParamType | Required | DataType | Schema ---- | --- | --- | --- | --- -_id_ | path | __True__ | _integer_ | -_body_ | body | __True__ | | [AttributeAlias](#definitions_AttributeAlias) -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [AttributeAlias](#definitions_AttributeAlias) -#### `DELETE /attributes/aliases/{id}` -__Summary__: Delete an AttributeAlias -##### Parameters -Name | ParamType | Required | DataType ---- | --- | --- | --- -_id_ | path | __True__ | _integer_ -##### Responses -Status Code | Description ---- | --- -_204_ | No Content -#### `POST /attributes/aliases` -__Summary__: Set an AttributeAlias -##### Parameters -Name | ParamType | Required | Schema ---- | --- | --- | --- -_body_ | body | __True__ | [AttributeAlias](#definitions_AttributeAlias) -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [AttributeAlias](#definitions_AttributeAlias) -#### `GET /attributes/aliases` -__Summary__: Fetch a list of AttributeAlias -__Description__: Without params, it returns a list of AttributeAlias from all the user's Devices -##### Parameters -Name | ParamType | Description | DataType ---- | --- | --- | --- -_deviceId_ | query | Standard users can use this only with _userId_s, they have access to | _integer_ -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [ [AttributeAlias](#definitions_AttributeAlias) ] - -### commands -#### `POST /commands` -__Summary__: Dispatch commands to device -##### Parameters -Name | ParamType | Required | Schema ---- | --- | --- | --- -_body_ | body | __True__ | [Command](#definitions_Command) -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [Command](#definitions_Command) -_400_ | Could happen when dispatching to a device that is offline, the user doesn't have permission or an incorrect command _type_ for the device | - -### commandtypes -#### `GET /commandtypes` -__Summary__: Fetch a list of available Commands for the Device -##### Parameters -Name | ParamType | Required | DataType ---- | --- | --- | --- -_deviceId_ | query | __True__ | _integer_ -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [ [CommandType](#definitions_CommandType) ] -_400_ | Could happen when trying to fetch from an pffline device or the user does not have permission | - -### devices -#### `POST /devices` -__Summary__: Create a Device -##### Parameters -Name | ParamType | Required | Schema ---- | --- | --- | --- -_body_ | body | __True__ | [Device](#definitions_Device) -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [Device](#definitions_Device) -#### `GET /devices` -__Summary__: Fetch a list of Devices -__Description__: Without any params, returns a list of the user's devices -##### Parameters -Name | ParamType | Description | DataType ---- | --- | --- | --- -_all_ | query | Can only be used by admin users to fetch all entities | _boolean_ -_userId_ | query | Standard users can use this only with their own _userId_ | _integer_ -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [ [Device](#definitions_Device) ] -_400_ | No permission | -#### `POST /devices/geofences` -__Summary__: Link a Geofence to a Device -##### Parameters -Name | ParamType | Required | Schema ---- | --- | --- | --- -_body_ | body | __True__ | [DeviceGeofence](#definitions_DeviceGeofence) -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [DeviceGeofence](#definitions_DeviceGeofence) -#### `DELETE /devices/geofences` -__Summary__: Remove a Geofence from a Device -##### Parameters -Name | ParamType | Required | Schema ---- | --- | --- | --- -_body_ | body | __True__ | [DeviceGeofence](#definitions_DeviceGeofence) -##### Responses -Status Code | Description ---- | --- -_204_ | No Content -#### `PUT /devices/{id}` -__Summary__: Update a Device -##### Parameters -Name | ParamType | Required | DataType | Schema ---- | --- | --- | --- | --- -_id_ | path | __True__ | _integer_ | -_body_ | body | __True__ | | [Device](#definitions_Device) -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [Device](#definitions_Device) -#### `DELETE /devices/{id}` -__Summary__: Update a Device -##### Parameters -Name | ParamType | Required | DataType ---- | --- | --- | --- -_id_ | path | __True__ | _integer_ -##### Responses -Status Code | Description ---- | --- -_204_ | No Content -#### `PUT /devices/{id}/distance` -__Summary__: Update the distance counter of the Device -##### Parameters -Name | ParamType | Required | DataType | Schema ---- | --- | --- | --- | --- -_id_ | path | __True__ | _integer_ | -_body_ | body | __True__ | | [DeviceTotalDistance](#definitions_DeviceTotalDistance) -##### Responses -Status Code | Description ---- | --- -_204_ | No Content - -### events -#### `GET /events/{id}` -##### Parameters -Name | ParamType | Required | DataType ---- | --- | --- | --- -_id_ | path | __True__ | _integer_ -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [Event](#definitions_Event) - -### geofences -#### `PUT /geofences/{id}` -__Summary__: Update a Geofence -##### Parameters -Name | ParamType | Required | DataType | Schema ---- | --- | --- | --- | --- -_id_ | path | __True__ | _integer_ | -_body_ | body | __True__ | | [Geofence](#definitions_Geofence) -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [Geofence](#definitions_Geofence) -#### `DELETE /geofences/{id}` -__Summary__: Delete a Geofence -##### Parameters -Name | ParamType | Required | DataType ---- | --- | --- | --- -_id_ | path | __True__ | _integer_ -##### Responses -Status Code | Description ---- | --- -_204_ | No Content -#### `POST /geofences` -__Summary__: Create a Geofence -##### Parameters -Name | ParamType | Required | Schema ---- | --- | --- | --- -_body_ | body | __True__ | [Geofence](#definitions_Geofence) -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [Geofence](#definitions_Geofence) -#### `GET /geofences` -__Summary__: Fetch a list of Geofences -__Description__: Without params, it returns a list of Geofences the user has access to -##### Parameters -Name | ParamType | Description | Required | DataType ---- | --- | --- | --- | --- -_all_ | query | Can only be used by admin users to fetch all entities | | _boolean_ -_userId_ | query | Standard users can use this only with their own _userId_ | | _integer_ -_groupId_ | query | | | _integer_ -_deviceId_ | query | Standard users can use this only with _userId_s, they have access to | | _integer_ -_refresh_ | query | | False | _boolean_ -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [ [Geofence](#definitions_Geofence) ] - -### groups -#### `POST /groups/geofences` -__Summary__: Link a Geofence to a Group -##### Parameters -Name | ParamType | Required | Schema ---- | --- | --- | --- -_body_ | body | __True__ | [GroupGeofence](#definitions_GroupGeofence) -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [GroupGeofence](#definitions_GroupGeofence) -#### `DELETE /groups/geofences` -__Summary__: Remove a Geofence from a Group -##### Parameters -Name | ParamType | Required | Schema ---- | --- | --- | --- -_body_ | body | __True__ | [GroupGeofence](#definitions_GroupGeofence) -##### Responses -Status Code | Description ---- | --- -_204_ | No Content -#### `POST /groups` -__Summary__: Create a Group -##### Parameters -Name | ParamType | Required | Schema ---- | --- | --- | --- -_body_ | body | __True__ | [Group](#definitions_Group) -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [Group](#definitions_Group) -_400_ | No permission | -#### `GET /groups` -__Summary__: Fetch a list of Groups -__Description__: Without any params, returns a list of the Groups the user belongs to -##### Parameters -Name | ParamType | Description | DataType ---- | --- | --- | --- -_all_ | query | Can only be used by admin users to fetch all entities | _boolean_ -_userId_ | query | Standard users can use this only with their own _userId_ | _integer_ -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [ [Group](#definitions_Group) ] -#### `PUT /groups/{id}` -__Summary__: Update a Group -##### Parameters -Name | ParamType | Required | DataType | Schema ---- | --- | --- | --- | --- -_id_ | path | __True__ | _integer_ | -_body_ | body | __True__ | | [Group](#definitions_Group) -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [Group](#definitions_Group) -#### `DELETE /groups/{id}` -__Summary__: Delete a Group -##### Parameters -Name | ParamType | Required | DataType ---- | --- | --- | --- -_id_ | path | __True__ | _integer_ -##### Responses -Status Code | Description ---- | --- -_204_ | No Content - -### permissions -#### `POST /permissions/devices` -__Summary__: Link a Device to a User -##### Parameters -Name | ParamType | Required | Schema ---- | --- | --- | --- -_body_ | body | __True__ | [DevicePermission](#definitions_DevicePermission) -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [DevicePermission](#definitions_DevicePermission) -_400_ | No permission | -#### `DELETE /permissions/devices` -__Summary__: Remove a Device from a User -##### Parameters -Name | ParamType | Required | Schema ---- | --- | --- | --- -_body_ | body | __True__ | [DevicePermission](#definitions_DevicePermission) -##### Responses -Status Code | Description ---- | --- -_204_ | No Content -#### `POST /permissions/geofences` -__Summary__: Link a Geofence to a User -##### Parameters -Name | ParamType | Required | Schema ---- | --- | --- | --- -_body_ | body | __True__ | [GeofencePermission](#definitions_GeofencePermission) -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [GeofencePermission](#definitions_GeofencePermission) -#### `DELETE /permissions/geofences` -__Summary__: Remove a Geofence from a User -##### Parameters -Name | ParamType | Required | Schema ---- | --- | --- | --- -_body_ | body | __True__ | [GeofencePermission](#definitions_GeofencePermission) -##### Responses -Status Code | Description ---- | --- -_204_ | No Content -#### `POST /permissions/groups` -__Summary__: Link a Group to a User -##### Parameters -Name | ParamType | Required | Schema ---- | --- | --- | --- -_body_ | body | __True__ | [GroupPermission](#definitions_GroupPermission) -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [GroupPermission](#definitions_GroupPermission) -#### `DELETE /permissions/groups` -__Summary__: Remove a Group from a User -##### Parameters -Name | ParamType | Required | Schema ---- | --- | --- | --- -_body_ | body | __True__ | [GroupPermission](#definitions_GroupPermission) -##### Responses -Status Code | Description ---- | --- -_204_ | No Content - -### positions -#### `GET /positions` -__Summary__: Fetches a list of Positions -__Description__: Without any params, it returns a list of last known positions for all the user's Devices. _from_ and _to_ fields are not required with _id_ -##### Parameters -Name | ParamType | Description | Required | DataType ---- | --- | --- | --- | --- -_deviceId_ | query | _deviceId_ is optional, but requires the _from_ and _to_ parameters when used | False | _integer_ -_from_ | query | | False | _string (date-time)_ -_to_ | query | | False | _string (date-time)_ -_id_ | query | To fetch one or more positions. Multiple params can be passed like `id=31&id=42` | False | _integer_ -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [ [Position](#definitions_Position) ] - -### reports -#### `GET /reports/summary` -__Summary__: Fetch a list of ReportSummary within the time period for the Devices or Groups -__Description__: At least one _deviceId_ or one _groupId_ must be passed -##### Parameters -Name | ParamType | Required | DataType ---- | --- | --- | --- -_deviceId_ | query | | [ _integer_ ] -_groupId_ | query | | [ _integer_ ] -_from_ | query | __True__ | _string (date-time)_ -_to_ | query | __True__ | _string (date-time)_ -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [ [ReportSummary](#definitions_ReportSummary) ] -#### `GET /reports/events` -__Summary__: Fetch a list of Events within the time period for the Devices or Groups -__Description__: At least one _deviceId_ or one _groupId_ must be passed -##### Parameters -Name | ParamType | Description | Required | DataType ---- | --- | --- | --- | --- -_deviceId_ | query | | | [ _integer_ ] -_groupId_ | query | | | [ _integer_ ] -_type_ | query | % can be used to return events of all types | | [ _string_ ] -_from_ | query | | __True__ | _string (date-time)_ -_to_ | query | | __True__ | _string (date-time)_ -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [ [Event](#definitions_Event) ] -#### `GET /reports/route` -__Summary__: Fetch a list of Positions within the time period for the Devices or Groups -__Description__: At least one _deviceId_ or one _groupId_ must be passed -##### Parameters -Name | ParamType | Required | DataType ---- | --- | --- | --- -_deviceId_ | query | | [ _integer_ ] -_groupId_ | query | | [ _integer_ ] -_from_ | query | __True__ | _string (date-time)_ -_to_ | query | __True__ | _string (date-time)_ -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [ [Position](#definitions_Position) ] -#### `GET /reports/trips` -__Summary__: Fetch a list of ReportTrips within the time period for the Devices or Groups -__Description__: At least one _deviceId_ or one _groupId_ must be passed -##### Parameters -Name | ParamType | Required | DataType ---- | --- | --- | --- -_deviceId_ | query | | [ _integer_ ] -_groupId_ | query | | [ _integer_ ] -_from_ | query | __True__ | _string (date-time)_ -_to_ | query | __True__ | _string (date-time)_ -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [ [ReportTrips](#definitions_ReportTrips) ] - -### server -#### `PUT /server` -__Summary__: Update Server information -##### Parameters -Name | ParamType | Required | Schema ---- | --- | --- | --- -_body_ | body | __True__ | [Server](#definitions_Server) -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [Server](#definitions_Server) -#### `GET /server` -__Summary__: Fetch Server information -##### Parameters -_None_ -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [Server](#definitions_Server) - -### session -#### `POST /session` -__Summary__: Create a new Session -##### Parameters -Name | ParamType | Required | DataType ---- | --- | --- | --- -_email_ | formData | __True__ | _string_ -_password_ | formData | __True__ | _string (password)_ -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [User](#definitions_User) -_401_ | Unauthorized | -#### `DELETE /session` -__Summary__: Close the Session -##### Parameters -_None_ -##### Responses -Status Code | Description ---- | --- -_204_ | No Content -#### `GET /session` -__Summary__: Fetch Session information -##### Parameters -_None_ -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [User](#definitions_User) -_404_ | Not Found | - -### statistics -#### `GET /statistics` -__Summary__: Fetch server Statistics -##### Parameters -Name | ParamType | Required | DataType ---- | --- | --- | --- -_from_ | query | __True__ | _string (date-time)_ -_to_ | query | __True__ | _string (date-time)_ -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [ [Statistics](#definitions_Statistics) ] - -### users -#### `POST /users/notifications` -__Summary__: Set or unset a Notification -##### Parameters -Name | ParamType | Required | Schema ---- | --- | --- | --- -_body_ | body | __True__ | [Notification](#definitions_Notification) -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [Notification](#definitions_Notification) -#### `GET /users/notifications` -__Summary__: Fetch a list of Notification types -__Description__: Without params, it returns a list of the user's enabled Notifications -##### Parameters -Name | ParamType | Description | DataType ---- | --- | --- | --- -_all_ | query | To fetch a list of all available Notifications | _boolean_ -_userId_ | query | Standard users can use this only with their own _userId_ | _integer_ -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [ [Notification](#definitions_Notification) ] -#### `PUT /users/{id}` -__Summary__: Update a User -##### Parameters -Name | ParamType | Required | DataType | Schema ---- | --- | --- | --- | --- -_id_ | path | __True__ | _integer_ | -_body_ | body | __True__ | | [User](#definitions_User) -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [User](#definitions_User) -#### `DELETE /users/{id}` -__Summary__: Delete a User -##### Parameters -Name | ParamType | Required | DataType ---- | --- | --- | --- -_id_ | path | __True__ | _integer_ -##### Responses -Status Code | Description ---- | --- -_204_ | No Content -#### `POST /users` -__Summary__: Create a User -##### Parameters -Name | ParamType | Required | Schema ---- | --- | --- | --- -_body_ | body | __True__ | [User](#definitions_User) -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [User](#definitions_User) -#### `GET /users` -__Summary__: Fetch a list of Users -##### Parameters -_None_ -##### Responses -Status Code | Description | Schema ---- | --- | --- -_200_ | OK | [ [User](#definitions_User) ] -_400_ | No Permission | - - -## Models -### AttributeAlias -Property | Type ---- | --- -_alias_ | _string_ -_attribute_ | _string_ -_deviceId_ | _integer_ -_id_ | _integer_ -### Command -Property | Type ---- | --- -_attributes_ | -_deviceId_ | _integer_ -_type_ | _string_ -### CommandType -Property | Type ---- | --- -_type_ | _string_ -### Device -Property | Type ---- | --- -_attributes_ | -_category_ | _string_ -_contact_ | _string_ -_geofenceIds_ | _array_ -_groupId_ | _integer_ -_id_ | _integer_ -_lastUpdate_ | _string (date-time)_ -_model_ | _string_ -_name_ | _string_ -_phone_ | _string_ -_positionId_ | _integer_ -_status_ | _string_ -_uniqueId_ | _string_ -### DeviceGeofence -Property | Type ---- | --- -_deviceId_ | _integer_ -_geofenceId_ | _integer_ -### DevicePermission -Property | Type ---- | --- -_deviceId_ | _integer_ -_userId_ | _integer_ -### DeviceTotalDistance -Property | Type | Description ---- | --- | --- -_deviceId_ | _integer_ | -_totalDistance_ | _number_ | in meters -### Event -Property | Type ---- | --- -_attributes_ | -_deviceId_ | _integer_ -_geofenceId_ | _integer_ -_id_ | _integer_ -_positionId_ | _integer_ -_serverTime_ | _string (date-time)_ -_type_ | _string_ -### Geofence -Property | Type ---- | --- -_area_ | _string_ -_attributes_ | -_description_ | _string_ -_id_ | _integer_ -_name_ | _string_ -### GeofencePermission -Property | Type ---- | --- -_geofenceId_ | _integer_ -_userId_ | _integer_ -### Group -Property | Type ---- | --- -_attributes_ | -_groupId_ | _integer_ -_id_ | _integer_ -_name_ | _string_ -### GroupGeofence -Property | Type ---- | --- -_geofenceId_ | _integer_ -_groupId_ | _integer_ -### GroupPermission -Property | Type ---- | --- -_groupId_ | _integer_ -_userId_ | _integer_ -### Notification -Property | Type ---- | --- -_attributes_ | -_id_ | _integer_ -_type_ | _string_ -_userId_ | _integer_ -### Position -Property | Type | Description ---- | --- | --- -_address_ | _string_ | -_altitude_ | _number_ | -_attributes_ | | -_course_ | _number_ | -_deviceId_ | _integer_ | -_deviceTime_ | _string (date-time)_ | -_fixTime_ | _string (date-time)_ | -_id_ | _integer_ | -_latitude_ | _number_ | -_longitude_ | _number_ | -_outdated_ | _boolean_ | -_protocol_ | _string_ | -_serverTime_ | _string (date-time)_ | -_speed_ | _number_ | In knots -_valid_ | _boolean_ | -### ReportSummary -Property | Type | Description ---- | --- | --- -_averageSpeed_ | _number_ | in knots -_deviceId_ | _integer_ | -_deviceName_ | _string_ | -_distance_ | _number_ | in meters -_engineHours_ | _integer_ | -_maxSpeed_ | _number_ | in knots -### ReportTrips -Property | Type | Description ---- | --- | --- -_averageSpeed_ | _number_ | in knots -_deviceId_ | _integer_ | -_deviceName_ | _string_ | -_distance_ | _number_ | in meters -_duration_ | _integer_ | -_endAddress_ | _string_ | -_endLat_ | _number_ | -_endLon_ | _number_ | -_endTime_ | _string (date-time)_ | -_maxSpeed_ | _number_ | in knots -_startAddress_ | _string_ | -_startLat_ | _number_ | -_startLon_ | _number_ | -_startTime_ | _string (date-time)_ | -### Server -Property | Type ---- | --- -_attributes_ | -_bingKey_ | _string_ -_coordinateFormat_ | _string_ -_distanceUnit_ | _string_ -_forceSettings_ | _boolean_ -_id_ | _integer_ -_latitude_ | _number_ -_longitude_ | _number_ -_map_ | _string_ -_mapUrl_ | _string_ -_readonly_ | _boolean_ -_registration_ | _boolean_ -_speedUnit_ | _string_ -_twelveHourFormat_ | _boolean_ -_version_ | _string_ -_zoom_ | _integer_ -### Statistics -Property | Type ---- | --- -_activeDevices_ | _integer_ -_activeUsers_ | _integer_ -_captureTime_ | _string (date-time)_ -_messagesReceived_ | _integer_ -_messagesStored_ | _integer_ -_requests_ | _integer_ -### User -Property | Type ---- | --- -_admin_ | _boolean_ -_attributes_ | -_coordinateFormat_ | _string_ -_deviceLimit_ | _integer_ -_disabled_ | _boolean_ -_distanceUnit_ | _string_ -_email_ | _string_ -_expirationTime_ | _string (date-time)_ -_id_ | _integer_ -_latitude_ | _number_ -_longitude_ | _number_ -_map_ | _string_ -_name_ | _string_ -_password_ | _string_ -_readonly_ | _boolean_ -_speedUnit_ | _string_ -_token_ | _string_ -_twelveHourFormat_ | _boolean_ -_zoom_ | _integer_ - - diff --git a/swagger.json b/swagger.json index 8577a106f..2c8830d87 100644 --- a/swagger.json +++ b/swagger.json @@ -664,7 +664,7 @@ } }, "400": { - "description": "Could happen when trying to fetch from an pffline device or the user does not have permission" + "description": "Could happen when trying to fetch from an offline device or the user does not have permission" } } } -- cgit v1.2.3 From 9d707dac529b922f491da45b73121e5e2ca96773 Mon Sep 17 00:00:00 2001 From: Sun Howwrongbum Date: Tue, 13 Dec 2016 14:25:20 +0530 Subject: [swagger] Add security definitions --- swagger.json | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/swagger.json b/swagger.json index 2c8830d87..ea3350a01 100644 --- a/swagger.json +++ b/swagger.json @@ -9,11 +9,16 @@ "schemes": [ "http" ], + "security": [ + { + "basicAuth": [] + } + ], "consumes": [ - "application/json" + "application/json" ], "produces": [ - "application/json" + "application/json" ], "paths": { "/commands": { @@ -1613,5 +1618,11 @@ "type": "string", "format": "date-time" } + }, + "securityDefinitions": { + "basicAuth": { + "type": "basic", + "description": "Basic HTTP authorization with _email_ and _password_" + } } } -- cgit v1.2.3 From a04c318ef92623478cf07b2f9ffca90b0f6507ad Mon Sep 17 00:00:00 2001 From: Sun Howwrongbum Date: Tue, 13 Dec 2016 16:43:31 +0530 Subject: Add script to generate HTML from swagger.json - #2680 --- tools/swagger2html.py | 354 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 354 insertions(+) create mode 100755 tools/swagger2html.py diff --git a/tools/swagger2html.py b/tools/swagger2html.py new file mode 100755 index 000000000..a3488835c --- /dev/null +++ b/tools/swagger2html.py @@ -0,0 +1,354 @@ +#!/usr/bin/python + +import sys, argparse, json, re + +def handleException(etype, e=None): + if etype == 'KeyError': + print "Error: Required property {} not found".format(e) + elif etype == 'IOError': + print "Error ({}): {}".format(e.errno, e.strerror) + elif etype == 'ValueError': + print "Error: Unable to parse input as JSON" + elif etype == 'Custom': + print e + sys.exit(1) + +def get_json(filename): + try: + with open(filename) as json_file: + json_data = json.load(json_file) + return json_data + except IOError as e: + handleException('IOError', e) + except ValueError: + handleException('ValueError') + except: + print "Unexpected error: {}".format(sys.exc_info()[0]) + raise + +def write_file(filename, body): + try: + with open(filename, 'w') as md_file: + md_file.write(body) + except IOError as e: + handleException('IOError', e) + +def make_header(json_data): + try: + if not 'swagger' in json_data: + raise KeyError + info = json_data['info'] + md = "

{}

\n".format(info['title']) + md += "

Version: {}

\n".format(info['version']) + if 'license' in info: + md += "

License: " + license = info['license'] + if 'url' in license: + md += '{}'.format(license['url'], license['name']) + else: + md += license['name'] + md += '

\n' + if 'contact' in info: + contact = info['contact'] + if 'name' in contact or 'email' in contact: + md += '

Contact: ' + if not 'name' in contact: + md += '{0}'.format(contact['email']) + elif not 'email' in contact: + md += contact['name'] + else: + md += '{0} <'.format(contact['name'], contact['email']) + md += ' \n' + if 'url' in contact: + md += "

Website: {}

\n".format(contact['url']) + if 'termsOfService' in info: + md += '

Terms of Service: {}

\n'.format(info['termsOfService']) + if 'host' in json_data: + md += '

Base URL: ' + base = json_data['host'] + if 'basePath' in json_data: + base += json_data['basePath'] + else: + base += '/' + if 'schemes' in json_data: + md += (', ').join(map( + lambda x: '{0}://{1}'.format(x, base), + json_data['schemes'] + )) + else: + md += '{0}'.format(base) + md += '

\n' + if 'description' in info: + md += '

Description: {}

\n'.format(info['description']) + md += '\n' + return md + except KeyErrori as e: + handleException('KeyError', e) + +def make_ref(ref): + href = ref.split('/')[1:] + return '{}'.format('_'.join(href), href[-1]) + +def get_ref(ref, raw): + keys = ref.split('/') + return raw[keys[1]][keys[2]] + +def make_html(s): + reg = re.compile(r"[*_]{3}(.+?)[*_]{3}") + s = reg.sub(r"\1", s) + reg = re.compile(r"[*_]{2}(.+?)[*_]{2}") + s = reg.sub(r"\1", s) + reg = re.compile(r"[*_](.+?)[*_]") + s = reg.sub(r"\1", s) + reg = re.compile(r"\`(.+?)\`") + s = reg.sub(r"\1", s) + return s + +def make_table(data): + md = '\n' + md += ' \n' + md += ' \n' + for col in data[0]: + md += ' \n'.format(col) + md += ' \n' + md += ' \n' + md += ' \n' + for row in data[1:]: + md += ' \n' + for cell in row: + md += ' \n'.format(cell) + md += ' \n' + md += ' \n' + md += '
{}
{}
\n' + return md + +def make_params_table(itemsraw, raw): + items = [] + for item in itemsraw: + if '$ref' in item: + items.append(get_ref(item['$ref'], raw)) + else: + items.append(item) + try: + fields = list(set([]).union(*map(lambda x: x.keys(), items))) + row = [ 'Name', 'ParamType' ] + if 'description' in fields: + row.append('Description') + if 'required' in fields: + row.append('Required') + if 'type' in fields: + row.append('DataType') + if 'schema' in fields: + row.append('Schema') + table = [ row ] + for item in items: + row = [ "{}".format(item['name']), item['in'] ] + if 'description' in fields: + if 'description' in item: + row.append(make_html(item['description'])) + else: + row.append('') + if 'required' in fields: + required = 'False' + if 'required' in item and item['required']: + required = "True" + row.append(required) + if 'type' in fields: + type = '' + if 'type' in item: + if item['type'] == 'array': + type = "[ {} ]".format(item['items']['type']) + else: + type = item['type'] + if 'format' in item: + type += " ({})".format(item['format']) + type = "{}".format(type) + row.append(type) + if 'schema' in fields: + if 'schema' in item: + if '$ref' in item['schema']: + row.append(make_ref(item['schema']['$ref'])) + else: + row.append('') + table.append(row) + return make_table(table) + except KeyError as e: + handleException('KeyError', e) + +def make_responses_table(responses): + try: + fields = list( + set([]).union(*map(lambda x: x.keys(), + map(lambda x: responses[x], responses.keys()) + )) + ) + row = [ 'Status Code', 'Description' ] + if 'headers' in fields: + row.append('Headers') + if 'schema' in fields: + row.append('Schema') + if 'examples' in fields: + row.append('Examples') + table = [ row ] + for key in sorted(responses): + response = responses[key] + row = [ "{}".format(key), make_html(response['description']) ] + if 'headers' in fields: + header = '' + if 'headers' in response: + hrow = [] + for header, h_obj in response['headers'].iteritems(): + hrow += "{} ({})".format(header, h_obj['type']) + if 'description' in h_obj: + hrow += ": {}".format(h_obj['description']) + header = ' \n'.join(hrow) + row.append(header) + if 'schema' in fields: + schema = '' + if 'schema' in response: + if '$ref' in response['schema']: + schema += make_ref(response['schema']['$ref']) + if 'type' in response['schema']: + if response['schema']['type'] == 'array': + if '$ref' in response['schema']['items']: + schema += make_ref(response['schema']['items']['$ref']) + schema = "[ {} ]".format(schema) + row.append(schema) + if 'examples' in fields: + if 'examples' in response: + row.append(response['examples']) + else: + row.append('') + table.append(row) + return make_table(table) + except KeyError as e: + handleException('KeyError', e) + +def make_paths(sections, json_data): + md = '

Paths

\n' + for key in sorted(sections): + md += '

{0}

\n'.format(key) + for section in sections[key]: + md += '

{}

\n'.format( + section['href'], section['title'] + ) + operation = section['operation'] + if 'summary' in operation: + md += '

Summary: {}

\n'.format(make_html(operation['summary'])) + if 'description' in operation: + md += '

Description: {}

\n'.format(make_html(operation['description'])) + md += '
Parameters
\n' + if 'parameters' in operation and len(operation['parameters']) > 0: + md += make_params_table(operation['parameters'], json_data) + else: + md += "

None

\n" + md += '
Responses
\n' + md += make_responses_table(operation['responses']) + md += '\n' + md += '\n' + return md + +def make_contents(path_section, json_data): + md = '

Contents

\n' + md += '
    \n' + md += '
  • Paths\n' + md += '
      \n' + for key in sorted(path_section): + md += '
    • {0}\n'.format(key) + md += '
        \n' + for section in path_section[key]: + md += '
      • {}
        • \n'.format( + section['href'], section['title'] + ) + md += '
      \n' + md += '
      • \n' + md += '
    \n' + md += '
    • \n' + md += '
  • Models\n' + md += '
      \n' + for key in sorted(json_data['definitions']): + md += '
    • {0}
      • \n'.format(key) + md += '
    \n' + md += '
    • \n' + md += '
\n' + return md + +def make_definitions(json_data): + md = '

Models

\n' + for name in sorted(json_data['definitions']): + md += '

{0}

\n'.format(name) + model = json_data['definitions'][name] + if 'properties' in model: + fields = list( + set(['type']).union( + *map(lambda x: x.keys(), + map(lambda x: model['properties'][x], model['properties'].keys()) + ) + ) + ) + row = [ 'Property', 'Type' ] + if 'description' in fields: + row.append('Description') + table = [ row ] + for key in sorted(model['properties']): + property = model['properties'][key] + row = [ "{}".format(key) ] + if 'type' in property: + type = property['type'] + if 'format' in property: + type += " ({})".format(property['format']) + row.append("{}".format(type)) + elif '$ref' in property: + row.append(make_ref(property['$ref'])) + else: + row.append('') + if 'description' in fields: + if 'description' in property: + row.append(make_html(property['description'])) + else: + row.append('') + table.append(row) + md += make_table(table) + return md + +def make_markdown(json_data): + path_sections = {} + for endpoint in json_data['paths']: + path_split = endpoint.split('/') + path_key = path_split[1] + if not path_key in path_sections: + path_sections[path_key] = [] + for method, operation in json_data['paths'][endpoint].iteritems(): + if 'operationId' in operation: + link = operation['operationId'] + else: + link = ''.join([ + c for c in endpoint if c not in ['/', '{', '}'] + ]) + path_sections[path_key].append({ + 'title': '{} {}'.format(method.upper(), endpoint), + 'href': 'paths_{}_{}'.format(link, method.upper()), + 'operation': operation + }) + md = make_header(json_data) + md += make_contents(path_sections, json_data) + md += make_paths(path_sections, json_data) + md += make_definitions(json_data) + return md + +def main(): + parser = argparse.ArgumentParser() + parser.add_argument('SPECFILE', help="path to swagger.json file") + parser.add_argument('OUTFILE', help="path to output HTML file") + args = parser.parse_args() + + marked_down = make_markdown(get_json(args.SPECFILE)) + + if args.OUTFILE: + write_file(args.OUTFILE, marked_down) + print " success: {}".format(args.OUTFILE) + else: + print marked_down + +if __name__ == '__main__': + main() -- cgit v1.2.3 From 652e3334f1ef13ce99193aacbabf89e2f0989e04 Mon Sep 17 00:00:00 2001 From: Sun Howwrongbum Date: Tue, 13 Dec 2016 17:20:50 +0530 Subject: [swagger] Add date format in descriptions - update `host` property --- swagger.json | 33 +++++++++++++++++++++++---------- 1 file changed, 23 insertions(+), 10 deletions(-) diff --git a/swagger.json b/swagger.json index ea3350a01..de9e190f1 100644 --- a/swagger.json +++ b/swagger.json @@ -4,7 +4,7 @@ "version": "3.9", "title": "traccar" }, - "host": "traccar.org", + "host": "demo.traccar.org", "basePath": "/api", "schemes": [ "http" @@ -399,6 +399,7 @@ { "name": "from", "in": "query", + "description": "in IS0 8601 format. eg. `1963-11-22T18:30:00Z`", "required": false, "type": "string", "format": "date-time" @@ -406,6 +407,7 @@ { "name": "to", "in": "query", + "description": "in IS0 8601 format. eg. `1963-11-22T18:30:00Z`", "required": false, "type": "string", "format": "date-time" @@ -1024,15 +1026,18 @@ }, "deviceTime": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "in IS0 8601 format. eg. `1963-11-22T18:30:00Z`" }, "fixTime": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "in IS0 8601 format. eg. `1963-11-22T18:30:00Z`" }, "serverTime": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "in IS0 8601 format. eg. `1963-11-22T18:30:00Z`" }, "outdated": { "type": "boolean" @@ -1111,7 +1116,8 @@ }, "expirationTime": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "in IS0 8601 format. eg. `1963-11-22T18:30:00Z`" }, "deviceLimit": { "type": "integer" @@ -1199,7 +1205,8 @@ }, "lastUpdate": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "in IS0 8601 format. eg. `1963-11-22T18:30:00Z`" }, "positionId": { "type": "integer" @@ -1340,7 +1347,8 @@ }, "serverTime": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "in IS0 8601 format. eg. `1963-11-22T18:30:00Z`" }, "deviceId": { "type": "integer" @@ -1404,7 +1412,8 @@ }, "startTime": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "in IS0 8601 format. eg. `1963-11-22T18:30:00Z`" }, "startAddress": { "type": "string" @@ -1417,7 +1426,8 @@ }, "endTime": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "in IS0 8601 format. eg. `1963-11-22T18:30:00Z`" }, "endAddress": { "type": "string" @@ -1434,7 +1444,8 @@ "properties": { "captureTime": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "in IS0 8601 format. eg. `1963-11-22T18:30:00Z`" }, "activeUsers": { "type": "integer" @@ -1607,6 +1618,7 @@ "fromTime": { "name": "from", "in": "query", + "description": "in IS0 8601 format. eg. `1963-11-22T18:30:00Z`", "required": true, "type": "string", "format": "date-time" @@ -1614,6 +1626,7 @@ "toTime": { "name": "to", "in": "query", + "description": "in IS0 8601 format. eg. `1963-11-22T18:30:00Z`", "required": true, "type": "string", "format": "date-time" -- cgit v1.2.3 From 29b07707b485ea38dd2af13f89dbd2d37dc61b45 Mon Sep 17 00:00:00 2001 From: Sun Howwrongbum Date: Tue, 13 Dec 2016 17:27:33 +0530 Subject: [swagger] Rename parameter references - fix typo. --- swagger.json | 62 ++++++++++++++++++++++++++++++------------------------------ 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/swagger.json b/swagger.json index de9e190f1..0f298f161 100644 --- a/swagger.json +++ b/swagger.json @@ -78,7 +78,7 @@ "summary": "Create a Device", "parameters": [ { - "$ref": "#/parameters/DeviceInBody" + "$ref": "#/parameters/Device" } ], "responses": { @@ -99,7 +99,7 @@ "$ref": "#/parameters/entityId" }, { - "$ref": "#/parameters/DeviceInBody" + "$ref": "#/parameters/Device" } ], "responses": { @@ -153,7 +153,7 @@ "summary": "Link a Geofence to a Device", "parameters": [ { - "$ref": "#/parameters/DeviceGeofenceInBody" + "$ref": "#/parameters/DeviceGeofence" } ], "responses": { @@ -169,7 +169,7 @@ "summary": "Remove a Geofence from a Device", "parameters": [ { - "$ref": "#/parameters/DeviceGeofenceInBody" + "$ref": "#/parameters/DeviceGeofence" } ], "responses": { @@ -207,7 +207,7 @@ "summary": "Create a Group", "parameters": [ { - "$ref": "#/parameters/GroupInBody" + "$ref": "#/parameters/Group" } ], "responses": { @@ -231,7 +231,7 @@ "$ref": "#/parameters/entityId" }, { - "$ref": "#/parameters/GroupInBody" + "$ref": "#/parameters/Group" } ], "responses": { @@ -262,7 +262,7 @@ "summary": "Link a Geofence to a Group", "parameters": [ { - "$ref": "#/parameters/GroupGeofenceInBody" + "$ref": "#/parameters/GroupGeofence" } ], "responses": { @@ -278,7 +278,7 @@ "summary": "Remove a Geofence from a Group", "parameters": [ { - "$ref": "#/parameters/GroupGeofenceInBody" + "$ref": "#/parameters/GroupGeofence" } ], "responses": { @@ -293,7 +293,7 @@ "summary": "Link a Device to a User", "parameters": [ { - "$ref": "#/parameters/DevicePermissionInBody" + "$ref": "#/parameters/DevicePermission" } ], "responses": { @@ -312,7 +312,7 @@ "summary": "Remove a Device from a User", "parameters": [ { - "$ref": "#/parameters/DevicePermissionInBody" + "$ref": "#/parameters/DevicePermission" } ], "responses": { @@ -327,7 +327,7 @@ "summary": "Link a Group to a User", "parameters": [ { - "$ref": "#/parameters/GroupPermissionInBody" + "$ref": "#/parameters/GroupPermission" } ], "responses": { @@ -343,7 +343,7 @@ "summary": "Remove a Group from a User", "parameters": [ { - "$ref": "#/parameters/GroupPermissionInBody" + "$ref": "#/parameters/GroupPermission" } ], "responses": { @@ -358,7 +358,7 @@ "summary": "Link a Geofence to a User", "parameters": [ { - "$ref": "#/parameters/GeofencePermissionInBody" + "$ref": "#/parameters/GeofencePermission" } ], "responses": { @@ -374,7 +374,7 @@ "summary": "Remove a Geofence from a User", "parameters": [ { - "$ref": "#/parameters/GeofencePermissionInBody" + "$ref": "#/parameters/GeofencePermission" } ], "responses": { @@ -553,7 +553,7 @@ "summary": "Create a User", "parameters": [ { - "$ref": "#/parameters/UserInBody" + "$ref": "#/parameters/User" } ], "responses": { @@ -574,7 +574,7 @@ "$ref": "#/parameters/entityId" }, { - "$ref": "#/parameters/UserInBody" + "$ref": "#/parameters/User" } ], "responses": { @@ -718,7 +718,7 @@ "summary": "Create a Geofence", "parameters": [ { - "$ref": "#/parameters/GeofenceInBody" + "$ref": "#/parameters/Geofence" } ], "responses": { @@ -739,7 +739,7 @@ "$ref": "#/parameters/entityId" }, { - "$ref": "#/parameters/GeofenceInBody" + "$ref": "#/parameters/Geofence" } ], "responses": { @@ -964,7 +964,7 @@ "summary": "Set an AttributeAlias", "parameters": [ { - "$ref": "#/parameters/AttributeAliasInBody" + "$ref": "#/parameters/AttributeAlias" } ], "responses": { @@ -985,7 +985,7 @@ "$ref": "#/parameters/entityId" }, { - "$ref": "#/parameters/AttributeAliasInBody" + "$ref": "#/parameters/AttributeAlias" } ], "responses": { @@ -1056,7 +1056,7 @@ }, "speed": { "type": "number", - "description": "In knots" + "description": "in knots" }, "course": { "type": "number" @@ -1517,7 +1517,7 @@ "description": "Standard users can use this only with _userId_s, they have access to", "type": "integer" }, - "DeviceInBody": { + "Device": { "name": "body", "in": "body", "required": true, @@ -1525,7 +1525,7 @@ "$ref": "#/definitions/Device" } }, - "DeviceGeofenceInBody": { + "DeviceGeofence": { "name": "body", "in": "body", "required": true, @@ -1533,7 +1533,7 @@ "$ref": "#/definitions/DeviceGeofence" } }, - "GroupInBody": { + "Group": { "name": "body", "in": "body", "required": true, @@ -1541,7 +1541,7 @@ "$ref": "#/definitions/Group" } }, - "GroupGeofenceInBody": { + "GroupGeofence": { "name": "body", "in": "body", "required": true, @@ -1549,7 +1549,7 @@ "$ref": "#/definitions/GroupGeofence" } }, - "DevicePermissionInBody": { + "DevicePermission": { "name": "body", "in": "body", "required": true, @@ -1557,7 +1557,7 @@ "$ref": "#/definitions/DevicePermission" } }, - "GroupPermissionInBody": { + "GroupPermission": { "name": "body", "in": "body", "required": true, @@ -1565,7 +1565,7 @@ "$ref": "#/definitions/GroupPermission" } }, - "GeofencePermissionInBody": { + "GeofencePermission": { "name": "body", "in": "body", "required": true, @@ -1573,7 +1573,7 @@ "$ref": "#/definitions/GeofencePermission" } }, - "UserInBody": { + "User": { "name": "body", "in": "body", "required": true, @@ -1581,7 +1581,7 @@ "$ref": "#/definitions/User" } }, - "GeofenceInBody": { + "Geofence": { "name": "body", "in": "body", "required": true, @@ -1589,7 +1589,7 @@ "$ref": "#/definitions/Geofence" } }, - "AttributeAliasInBody": { + "AttributeAlias": { "name": "body", "in": "body", "required": true, -- cgit v1.2.3