Merge branch 'main' of github.com:infrasonar/docs

docs/api/alert/assign.md

@@ -1,5 +1,5 @@
 # Assign alert
-**`PUT`/alert/<alertKs\>/assign**
+**`PUT` /alert/<alertKs\>/assign**
 
 ### Description
 Assign an open alert to a user. The user _(userId)_ must be marked as a member of the container. Success _(204)_ is also returned when the alert does not exist.

docs/api/alert/close.md

@@ -1,5 +1,5 @@
 # Close alert
-**`PUT`/alert/<alertKs\>/close**
+**`PUT` /alert/<alertKs\>/close**
 
 ### Description
 Close an alert. An optional message can be provided. Success _(204)_ is also returned when the alert is already closed .

docs/api/alert/message.md

@@ -1,5 +1,5 @@
 # Add message to alert
-**`PUT`/alert/<alertKs\>/message**
+**`PUT` /alert/<alertKs\>/message**
 
 ### Description
 Add a message to an open alert. Success _(204)_ is also returned when the alert does not exist.

docs/api/alert/query.md

@@ -1,5 +1,5 @@
 # Query alert
-**`GET`/alert/<alertKs\>?fields=...&actions=...**
+**`GET` /alert/<alertKs\>?fields=...&actions=...**
 
 ### Description
 Query alert details. This API call will work for both an open _and_ closed alert.

docs/api/asset/add-label.md

@@ -30,6 +30,6 @@ Error code  | Reason
 Curl request:
 ```bash
 curl \
-    -X PUT 'https://api.infrasonar.com/asset/123/label/123' \
+    -X PUT 'https://api.infrasonar.com/asset/123/label/456' \
     -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
 ```

docs/api/asset/query.md

@@ -1,5 +1,5 @@
 # Query asset
-**`GET`/asset/<assetId\>?fields=...**
+**`GET` /asset/<assetId\>?fields=...**
 
 ### Description
 Query asset details.

docs/api/asset/remove-label.md

@@ -28,6 +28,6 @@ Error code  | Reason
 Curl request:
 ```bash
 curl \
-    -X DELETE 'https://api.infrasonar.com/asset/123/label/123' \
+    -X DELETE 'https://api.infrasonar.com/asset/123/label/456' \
     -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
 ```

docs/api/container/create-asset.md

@@ -43,6 +43,6 @@ curl \
 Response:
 ```json
 {
-    "assetId": 123
+    "assetId": 456
 }
 ```

docs/api/container/query.md

@@ -1,5 +1,5 @@
 # Query container
-**`GET`/container/<containerId\>?fields=...**
+**`GET` /container/<containerId\>?fields=...**
 
 ### Description
 Query container details.

docs/api/files/delete-file.md

@@ -0,0 +1,33 @@
+# Delete a file
+**`DELETE` /container/<containerId\>/file/<fileId\>**
+
+### Description
+Delete a file.
+
+### Path parameters
+Param               | Description
+--------------------|-------------
+`containerId`       | Container Id.
+`fileId`            | File Id.
+
+### Query parameters
+_none_
+
+### Body
+_none_
+
+### Return codes
+Error code  | Reason
+------------|--------
+`204`       | Success.
+`401`       | Invalid or missing token.
+`403`       | Insufficient permissions _(required: `API`+`ASSET_MANAGEMENT`)_.
+`404`       | Container or file not found.
+
+### Example
+Curl request:
+```bash
+curl \
+    -X DELETE 'https://api.infrasonar.com/container/123/file/456' \
+    -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
+```

docs/api/files/download-file.md

@@ -0,0 +1,35 @@
+# Upload file
+**`GET` /container/<containerId\>/file/<fileId\>**
+
+### Description
+Download a file. For file info, see the [Query file](../query-file) section.
+
+### Path parameters
+Param               | Description
+--------------------|-------------
+`containerId`       | Container Id.
+`fileId`            | File Id.
+
+### Query parameters
+_none_
+
+### Body
+_none_
+
+### Return codes
+Error code  | Reason
+------------|--------
+`200`       | Success.
+`401`       | Invalid or missing token.
+`403`       | Insufficient permissions _(required: `API`+`READ`)_.
+`404`       | Container or file not found.
+
+### Example
+Curl request:
+```bash
+curl \
+    -X GET 'https://api.infrasonar.com/container/123/file' \
+    -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
+```
+
+_Returns with the raw file_

docs/api/files/modify-file.md

@@ -0,0 +1,41 @@
+# Modify file
+**`PUT` /container/<containerId\>/file/<fileId\>**
+
+### Description
+Rename the file or change the attached labels for a file.
+
+Note that if _labels_ are provided, they will overwrite existing labels.
+
+### Path parameters
+Param               | Description
+--------------------|-------------
+`containerId`       | Container Id.
+`fileId`            | File Id.
+
+### Body
+Param           | Type          | Required  | Description
+----------------|---------------|-----------|-------------
+`name`          | string        | No        | New file name.
+`labels`        | array(integer)| No        | Overwrite labels. Be careful with an empty list as this will remove all labels from the file.
+
+### Return codes
+Error code  | Reason
+------------|--------
+`204`       | Success.
+`400`       | Invalid body.
+`401`       | Invalid or missing token.
+`403`       | Insufficient permissions _(required: `API`+`ASSET_MANAGEMENT`)_.
+`404`       | Container, file or one of the labels not found.
+
+### Example
+Curl request:
+```bash
+curl \
+    -X PUT 'https://api.infrasonar.com/container/123/file/456' \
+    -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
+    -H 'Content-Type: application/json' \
+    --data-raw '{
+    "name": "My file.docx",
+    "labels": [456, 789]
+}'
+```

docs/api/files/query-file.md

@@ -0,0 +1,55 @@
+# Upload file
+**`GET` /container/<containerId\>/file/<fileId\>/info?fields=...**
+
+### Description
+Query file info. For downloading the file, see the [Download file](../download-file) section.
+
+### Path parameters
+Param               | Description
+--------------------|-------------
+`containerId`       | Container Id.
+`fileId`            | File Id.
+
+### Query parameters
+Param               | Default           | Description
+--------------------|-------------------|-------------
+`fields`            | _all fields_      | Fields to return _(see fields below for all available fields)_.
+
+### Body
+_none_
+
+### Fields
+Field               | Return type       | Description
+--------------------|------------------ |-------------
+`id`                | integer           | Key string of the alert.
+`size`              | integer           | Initial message when the alert was opened.
+`created`           | integer           | Unix timestamp in seconds when the file was created in InfraSonar.
+`type`              | string            | One of `xml`, `json`, `docx`, `xlsx`, `csv`, `pdf`, `image`, `text`, `markdown`, `compressed` or `unknown`.
+`name`              | string            | File name.
+`labels`            | array(integer)    | List with label Ids.
+
+### Return codes
+Error code  | Reason
+------------|--------
+`200`       | Success.
+`400`       | Unknown field.
+`401`       | Invalid or missing token.
+`403`       | Insufficient permissions _(required: `API`+`READ`)_.
+`404`       | Container or file not found.
+
+### Example
+Curl request:
+```bash
+curl \
+    -X GET 'https://api.infrasonar.com/container/123/file/456/info?fields=id,name,labels' \
+    -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
+```
+
+Response:
+```json
+{
+    "id": 456,
+    "name": "network-diagram.png",
+    "labels": [789]
+}
+```

docs/api/files/query-files.md

@@ -0,0 +1,53 @@
+# Query container files
+**`GET` /container/<containerId\>/files?fields=...**
+
+### Description
+Query all files for a given container.
+
+### Path parameters
+Param               | Description
+--------------------|-------------
+`containerId`       | Container Id.
+
+### Query parameters
+Param               | Default           | Description
+--------------------|-------------------|-------------
+`fields`            | `id`              | Fields to return _(see fields below for all available fields)_.
+
+### Fields
+Field               | Return type       | Description
+--------------------|------------------ |-------------
+`id`                | integer           | Key string of the alert.
+`size`              | integer           | Initial message when the alert was opened.
+`created`           | integer           | Unix timestamp in seconds when the file was created in InfraSonar.
+`type`              | string            | One of `xml`, `json`, `docx`, `xlsx`, `csv`, `pdf`, `image`, `text`, `markdown`, `compressed` or `unknown`.
+`name`              | string            | File name.
+`labels`            | array(integer)    | List with label Ids.
+
+### Return codes
+Error code  | Reason
+------------|--------
+`200`       | Success.
+`400`       | Unknown field.
+`401`       | Invalid or missing token.
+`403`       | Insufficient permissions _(required: `API`+`READ`)_.
+`404`       | Container not found.
+
+### Example
+Curl request:
+```bash
+curl \
+    -X GET 'https://api.infrasonar.com/container/123/files?fields=id,name,type' \
+    -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
+```
+
+Response:
+```json
+[
+    {
+        "id": 456,
+        "name": "network-diagram.png",
+        "type": "image"
+    }
+]
+```

docs/api/files/upload-file.md

@@ -0,0 +1,93 @@
+# Upload file
+**`POST` /container/<containerId\>/file**
+
+### Description
+Upload a new file. Only files with a size less than 250KB are allowed.
+
+### Path parameters
+Param               | Description
+--------------------|-------------
+`containerId`       | Container Id.
+
+### Query parameters
+_none_
+
+### Body
+Files must be uploaded using multipart/form-data. See the examples below.
+
+### Return codes
+Error code  | Reason
+------------|--------
+`201`       | Success.
+`400`       | Invalid file _(for example too large)_.
+`401`       | Invalid or missing token.
+`403`       | Insufficient permissions _(required: `API`+`INSERT_CHECK_DATA`)_.
+`404`       | Container not found.
+
+### Examples
+Curl request:
+```bash
+curl \
+    -X POST 'https://api.infrasonar.com/container/123/file' \
+    -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
+    -H 'Content-Type: application/json' \
+    --form '=@"/path-to-file/network-drawing.png"'
+```
+
+Response:
+```json
+{
+    "id": 456
+}
+```
+
+Python:
+```python
+import requests
+
+url = "https://api.infrasonar.com/container/123/file"
+
+files = [('', (
+    'network-drawing.png',
+    open('/path-to-file/network-drawing.png','rb'),
+    'image/jpeg'
+))]
+
+headers = {
+    'Content-Type': 'multipart/form-data',
+    'Authorization': 'Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
+}
+
+response = requests.request("POST", url, headers=headers, files=files)
+
+print(response.json())  # {"id":456}
+```
+
+C# (Http Client)
+```c#
+var client = new HttpClient();
+var request = new HttpRequestMessage(
+    HttpMethod.Post,
+    "https://api.infrasonar.com/container/123/file");
+
+// Set Authentication header
+request.Headers.Add(
+    "Authorization",
+    "Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX");
+
+// Create multipart content
+var content = new MultipartFormDataContent();
+content.Add(
+    new StreamContent(File.OpenRead("/path-to-file/network-drawing.png")),
+    "",
+    "/path-to-file/network-drawing.png");
+
+// Add contend to request
+request.Content = content;
+
+var response = await client.SendAsync(request);
+response.EnsureSuccessStatusCode();
+
+Console.WriteLine(await response.Content.ReadAsStringAsync());
+// "{\"id\":456}"
+```

docs/api/label/query.md

@@ -1,5 +1,5 @@
 # Query label
-**`GET`/label/<labelId\>?fields=...**
+**`GET` /label/<labelId\>?fields=...**
 
 ### Description
 Query label details.

docs/api/reporting/get-report.md

@@ -1,5 +1,5 @@
 # Download report
-**`GET`/reporting/<reportingId\>/report/<reportId\>**
+**`GET` /reporting/<reportingId\>/report/<reportId\>**
 
 ### Description
 Download a report.