19724 update documentation

docs/integrations/graphql-api.md

@@ -11,7 +11,7 @@ curl -H "Authorization: Token $TOKEN" \
 -H "Content-Type: application/json" \
 -H "Accept: application/json" \
 http://netbox/graphql/ \
---data '{"query": "query {circuit_list(filters:{status: STATUS_ACTIVE}) {cid provider {name}}}"}'
+--data '{"query": "query {circuit_list(filters:{status: STATUS_ACTIVE}) {results {cid provider {name}}}}"}'
 ```
 
 The response will include the requested data formatted as JSON:
@@ -19,7 +19,8 @@ The response will include the requested data formatted as JSON:
 ```json
 {
   "data": {
-    "circuits": [
+    "circuit_list": {
+      "results": [
         {
           "cid": "1002840283",
           "provider": {
@@ -34,6 +35,7 @@ The response will include the requested data formatted as JSON:
         }
       ]
     }
+  }
 }
 ```
 
@@ -63,8 +65,10 @@ query {
       status: STATUS_ACTIVE
     }
   ) {
+    results {
       name
     }
+  }
 }
 ```
 
@@ -84,8 +88,10 @@ query {
       }
     }
   ) {
+    results {
       name
     }
+  }
 }
 ```
 
@@ -94,12 +100,14 @@ Filtering can also be applied to related objects. For example, the following que
 ```
 query {
   device_list {
+    results {
       id
       name
       interfaces(filters: {enabled: true}) {
         name
       }
     }
+  }
 }
 ```
 
@@ -110,6 +118,7 @@ Certain queries can return multiple types of objects, for example cable terminat
 ```
 {
   cable_list {
+    results {
       id
       a_terminations {
         ... on CircuitTerminationType {
@@ -126,6 +135,7 @@ Certain queries can return multiple types of objects, for example cable terminat
         }
       }
     }
+  }
 }
 ```
 
@@ -133,16 +143,46 @@ The field "class_type" is an easy way to distinguish what type of object it is w
 
 ## Pagination
 
-Queries can be paginated by specifying pagination in the query and supplying an offset and optionaly a limit in the query.  If no limit is given, a default of 100 is used.  Queries are not paginated unless requested in the query. An example paginated query is shown below:
+All list queries return paginated results using the `OffsetPaginated` type, which includes:
+
+- `results`: The list of objects matching the query
+- `total_count`: The total number of objects matching the filters (without pagination)
+- `page_info`: Pagination metadata including `offset` and `limit`
+
+By default, queries return up to 100 results. You can control pagination by specifying the `pagination` parameter with `offset` and `limit` values:
 
 ```
 query {
   device_list(pagination: { offset: 0, limit: 20 }) {
+    total_count
+    page_info {
+      offset
+      limit
+    }
+    results {
       id
+      name
+    }
   }
 }
 ```
 
+If you don't need pagination metadata, you can simply query the `results`:
+
+```
+query {
+  device_list {
+    results {
+      id
+      name
+    }
+  }
+}
+```
+
+!!! note
+    When not specifying the `pagination` parameter, avoid querying `page_info.limit` as it may return an undefined value. Either provide explicit pagination parameters or only query the `results` and `total_count` fields.
+
 ## Authentication
 
 NetBox's GraphQL API uses the same API authentication tokens as its REST API. Authentication tokens are included with requests by attaching an `Authorization` HTTP header in the following form: