SRV-754 Add Network Device Creation Endpoint Documentation

docs/api/create-device-using-network.api.mdx

@@ -0,0 +1,204 @@
+---
+id: create-device-using-network
+title: "Create Device using Network"
+description: "Create either an immutable or a mutable device."
+sidebar_label: "Create Device using Network"
+hide_title: true
+hide_table_of_contents: true
+api: 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
+sidebar_class_name: "post api-method"
+info_path: docs/api/tagoio-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+
+<Heading as={"h1"} className={"openapi__heading"} children={"Create Device using Network"}></Heading>
+
+<MethodEndpoint method={"post"} path={"/integration/network/device"} context={"endpoint"}></MethodEndpoint>
+
+Create either an immutable or a mutable device.
+
+- Immutable devices require chunking parameters and are optimized for long-term, append-only storage.
+- Mutable devices behave like classic devices and do not require chunk settings.
+
+You must have a Network and a Network-Token to use this endpoint.
+:::warning  
+Your Network-Token must have the create device privilege as true.  
+:::
+
+<Heading id={"request"} as={"h2"} className={"openapi-tabs__heading"} children={"Request"}></Heading>
+
+<ParamsDetails parameters={undefined}></ParamsDetails>
+
+<RequestSchema
+  title={"Body"}
+  body={{
+    content: {
+      "application/json": {
+        schema: {
+          oneOf: [
+            {
+              title: "Immutable Device Creation",
+              type: "object",
+              required: ["name", "type", "connector", "chunk_period", "chunk_retention"],
+              properties: {
+                name: { type: "string", description: "Device name", example: "My first immutable device" },
+                type: {
+                  type: "string",
+                  enum: ["immutable"],
+                  description: "Device type - must be 'immutable' for immutable devices",
+                  example: "immutable",
+                },
+                connector: {
+                  type: "string",
+                  description: "Connector ID for the device",
+                  example: "5f5a8f3351d4db99c40dece5",
+                },
+                chunk_period: {
+                  type: "string",
+                  enum: ["day", "week", "month", "quarter"],
+                  description: "Chunk period for data storage - one of day, week, month, quarter",
+                  example: "quarter",
+                },
+                chunk_retention: {
+                  type: "number",
+                  minimum: 0,
+                  maximum: 36,
+                  description: "Number of chunks to retain (0-36)",
+                  example: 36,
+                },
+                serie_number: {
+                  type: "string",
+                  description: "Serial number - only required if specified by the network",
+                  example: "AB87392C17CA",
+                },
+                tags: {
+                  type: "array",
+                  description: "Device tags as key-value string pairs",
+                  items: {
+                    type: "object",
+                    properties: {
+                      key: { type: "string", description: "Tag key", example: "tagKey1" },
+                      value: { type: "string", description: "Tag value", example: "value1" },
+                    },
+                  },
+                  example: [
+                    { key: "tagKey1", value: "value1" },
+                    { key: "tagKey2", value: "value2" },
+                  ],
+                },
+              },
+            },
+            {
+              title: "Mutable Device Creation",
+              type: "object",
+              required: ["name", "type", "connector"],
+              properties: {
+                name: { type: "string", description: "Device name", example: "My first device" },
+                type: {
+                  type: "string",
+                  enum: ["mutable"],
+                  description: "Device type - must be 'mutable' for mutable devices",
+                  example: "mutable",
+                },
+                connector: {
+                  type: "string",
+                  description: "Connector ID for the device",
+                  example: "5f5a8f3351d4db99c40dece5",
+                },
+                serie_number: {
+                  type: "string",
+                  description: "Serial number - only required if specified by the network",
+                  example: "AB87392C12CA",
+                },
+                active: { type: "boolean", description: "Device active status", example: true },
+                tags: {
+                  type: "array",
+                  description: "Device tags",
+                  items: {
+                    type: "object",
+                    properties: {
+                      key: { type: "string", example: "tagKey1" },
+                      value: { type: "string", example: "value1" },
+                    },
+                  },
+                  example: [
+                    { key: "tagKey1", value: "value1" },
+                    { key: "tagKey2", value: "value2" },
+                  ],
+                },
+                visible: { type: "boolean", description: "Device visibility status", example: true },
+              },
+            },
+          ],
+        },
+        examples: {
+          "Create Immutable Device": {
+            value: {
+              name: "My first immutable device",
+              type: "immutable",
+              connector: "5f5a8f3351d4db99c40dece5",
+              chunk_period: "quarter",
+              chunk_retention: 36,
+              serie_number: "AB87392C17CA",
+            },
+          },
+          "Create Mutable Device": {
+            value: {
+              name: "My first device",
+              type: "mutable",
+              connector: "5f5a8f3351d4db99c40dece5",
+              serie_number: "AB87392C12CA",
+            },
+          },
+        },
+      },
+      "text/plain": {
+        examples: {
+          "Create Immutable Device": {
+            value:
+              '{\r\n  "name": "My first immutable device",\r\n  "type": "immutable",\r\n  "connector": "5f5a8f3351d4db99c40dece5",\r\n  "chunk_period": "quarter", //define a chunk period by "day","week", "month", "quarter"\r\n  "chunk_retention": 36, //acceptable range between 0-36\r\n  "serie_number": "AB87392C17CA" //only if required by network (optional)\r\n }',
+          },
+          "Create Mutable Device": {
+            value:
+              '{\r\n  "name": "My first device",\r\n  "type": "mutable",\r\n  "connector": "5f5a8f3351d4db99c40dece5",\r\n  "serie_number": "AB87392C12CA" //only if required by network (optional)\r\n }',
+          },
+        },
+      },
+    },
+  }}
+></RequestSchema>
+
+<StatusCodes
+  id={undefined}
+  label={undefined}
+  responses={{
+    "201": {
+      description: "Mutable device created / Immutable device created",
+      content: {
+        "application/json": {
+          schema: {
+            type: "object",
+            properties: {
+              result: {
+                type: "object",
+                properties: {
+                  deviceID: { type: "string", example: "5dcad1c216174c001ca23ab9" },
+                  token: { type: "string", example: "5a16405f-b32c-4c91-ae39-cbb2caba18d8" },
+                },
+              },
+              status: { type: "boolean", example: true },
+            },
+          },
+        },
+      },
+    },
+  }}
+></StatusCodes>

docs/api/create-network-token.api.mdx

@@ -0,0 +1,84 @@
+---
+id: create-network-token
+title: "Create a Token for the Network"
+description: "Create a token for the network to use in network endpoints"
+sidebar_label: "Create a Token for the Network"
+hide_title: true
+hide_table_of_contents: true
+api: eJy9V9tu2zgQ/RWCeShgSL47jvVQINsGu8EWbZALikUSoGNpLLGRSZWk4hqG/30xpGRLTpN2t9t9SQxxOHPmfrjhFlLDo1v+Hu1K6Qd2LlM0lt8HPEETa1FYoSSP+BuNYJEBs+oBJVsozWyGTFbXrGKlQSbk7gvKpFBCWsMDrgrUQIrOEx7x2KmqDF6TOh5wg3GphV3z6HbDL7RaiBxDfxjd3m/vA67xS4nG/qaSNY82PFbSorT0E4oiF7Ez0PtsCO6GmzjDJdAvuy6QR1zNP2NsudcjNCbktYQl8oBXmMnrQhNYK9DQ3fpgr8ZYLWTKA45fYVnk9On4eDqZ9o+H02QIyaDf789msySGId8G3sCLt72PW7KMjyLHtDJ9CLsNzMfwLT6KuKl/rlSOIJsGrC5xu91uG59uG449j74Gz+sUHQBsQ/Bm7vdmnMyuapwOthI2Y9U3f5EVWjilzotHyMtfjM+HQqMplDRecNjv079n6v0HkAf/vhjbWdVoytx+X+4fVNVPV/CvLcuAW9/jL8EDgPl8HsfhYDAYhMPhcBiORqNROB6Px+AP59wpMxZsaX6sIdyFJdpM0VAqlHHugM14xHtCWkz9zOpVIezZ3ajSj6iNq9NS5zzimbWFiXo9KES3NCEOuhZS1RWKb4NvyWAZrhoy9/vxd0WV4mPpo1jPwJ1HUIg/cc0P5/Mpa8ozm4FlwrBSii8l0nheq1KzxMl02e8oaSLv5/l8zSCO0RghUy/q1b0yrIAUu/tua8EKuCDjGUKCmgf8a7jP2gQHw9F4AmEy7UM4xmESzk9GSTiJ++7geHoyowKrFsGPO1qvqhc9rYS67NS5xc73CTXs9U7Ha6/F0L30MCi05FrKns6cQ/ffClPksH7vpdqutcOzSCbjGSTD8GQwisNxcnwczhfTYTjpn+BkPjuBBY4oPAe78PvhqS5UPjwTHpRWaJphTrZREEJ6AYhjVUrLDForZGoavrcRvVQCMJggTBDCJBkm4Tg+HoUns/EknA3nk3EC4+l0CJzakAbl5X6/n/0Pm4pwL5QLqLB+ZkKqzj+w04vzJ1E9Ojo6Yp3OH2pVMx2bCcMSFZdLlNaVVadzJ68zbH+k0JsiF5Y6bJWJOKvyslblK42sJiMNAkW0quI6XcbuZAWr0OpRJGjYmCVisUCN0npdJrqTIet0mp3Z6USMwFSFrNWyOQCCCspalSwGyVK0XoZsJ63Gv5OMEQoy0Eo8WTjNjWIPUq0YGGo0qhh/2mV/qXKv19muim1XUk8NtPqFDJwbB+nQi11zf5D5msEjiBzmOTKxqOOqVhI1U4sWSa1rWzRnwRMQpxLytRHGo4g6nW8GEiqpoGneJ68+qlWHYXgnXQVdec+d1OnFOTurODK7xFQoeSc/ZijZEh5ICOoqoNqgG/v6DFzmlqWxDCgFpsBYLNbeekErWQtqZu3UQr4j4132JlPKIFMS6+gsVJ6rFVncUXY2B4MJU1W8UlSphiITMeSVzuhO+mjdSGExYVcWLBp2BsayAcWM+ZDe1K1S62arDOsRs2dK1CbeZhVDBGNRS9ZS3621djo3l+/IyqdnN2/vUzOnZyXRFPYR/wN4pISgeZ3fwdTa9ITJ46FUsrdY5Gq9Q0MNYzJV5ombBA6DWklXKDeX73aTvFVvflWrJQhpmMHYoa0SS0a8DRreRFn8MBt0+91+RVohJrpJI5gI0BLknl4eUuD6yVc13+GMbLzIfu6xWO03i19tr8hBOBrrONSmome3vNHBjedbTSbvA54RnYtu+WZDebvR+XZLn7+UqOmJeR/wR9CCouiel0G9v2jjPOCafPDehNcEJ6ifJk/pPTE8f4OYRmFflL1vMM6LD1fXPODz6j27VAnd0bCiNyqseMTdy9lNKfc4oG8bnoNMS6D3Evc6KXlQUlya3ODBcYPqB3lVH8l1A+HhKveO0F9y65tXNhvPPLbbnbw/evbGjhp4aUoovcP+Bm8llIw=
+sidebar_class_name: "post api-method"
+info_path: docs/api/tagoio-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+
+<Heading as={"h1"} className={"openapi__heading"} children={"Create a Token for the Network"}></Heading>
+
+<MethodEndpoint method={"post"} path={"/integration/network/token"} context={"endpoint"}></MethodEndpoint>
+
+Create a token for the network to use in network endpoints
+
+<Heading id={"request"} as={"h2"} className={"openapi-tabs__heading"} children={"Request"}></Heading>
+
+<ParamsDetails parameters={undefined}></ParamsDetails>
+
+<RequestSchema
+  title={"Body"}
+  body={{
+    content: {
+      "application/json": {
+        schema: {
+          type: "object",
+          required: ["name", "network"],
+          properties: {
+            network: { type: "string", example: "667570627d2ad1000999dca2" },
+            name: { type: "string", example: "Token" },
+            previlegies: { type: "object", properties: { createDevice: { type: "boolean", example: true } } },
+          },
+          example: [{ network: "667570627d2ad1000999dca2", name: "Token", previlegies: { createDevice: true } }],
+        },
+        examples: {
+          "Create a Token with Create Device privilege": {
+            value: [{ network: "667570627d2ad1000999dca2", name: "Token", previlegies: { createDevice: true } }],
+          },
+        },
+      },
+    },
+  }}
+></RequestSchema>
+
+<StatusCodes
+  id={undefined}
+  label={undefined}
+  responses={{
+    "200": {
+      description: "Create a Token with Create Device privilege",
+      content: {
+        "application/json": {
+          schema: {
+            type: "object",
+            properties: {
+              result: {
+                type: "object",
+                properties: {
+                  name: { type: "string", example: "Token" },
+                  network: { type: "string", example: "667570627d2ad1000999dca2" },
+                  previlegies: { type: "object", properties: { createDevice: { type: "boolean", example: true } } },
+                  token: { type: "string", example: "aaabbbcc-1111-2222-3333-4444aaaabbbb" },
+                },
+              },
+              status: { type: "boolean", example: true },
+            },
+          },
+        },
+      },
+    },
+  }}
+></StatusCodes>

docs/api/sidebar/api-sidebar.ts

@@ -97,6 +97,18 @@ const sidebar: SidebarsConfig = {
           label: "Send Data using Network",
           className: "api-method post",
         },
+        {
+          type: "doc",
+          id: "api/create-device-using-network",
+          label: "Create Device using Network",
+          className: "api-method post",
+        },
+        {
+          type: "doc",
+          id: "api/create-network-token",
+          label: "Create Network Token",
+          className: "api-method post",
+        },
       ],
     },
     {