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": {
@@ -35,6 +36,7 @@ The response will include the requested data formatted as JSON:
       ]
     }
   }
+}
 ```
 
 !!! note
@@ -63,9 +65,11 @@ query {
       status: STATUS_ACTIVE
     }
   ) {
+    results {
       name
     }
   }
+}
 ```
 
 Filters can be combined with logical operators, such as `OR` and `NOT`. For example, the following will return every site that is planned _or_ assigned to a tenant named Foo:
@@ -84,9 +88,11 @@ query {
       }
     }
   ) {
+    results {
       name
     }
   }
+}
 ```
 
 Filtering can also be applied to related objects. For example, the following query will return only enabled interfaces for each device:
@@ -94,6 +100,7 @@ Filtering can also be applied to related objects. For example, the following que
 ```
 query {
   device_list {
+    results {
       id
       name
       interfaces(filters: {enabled: true}) {
@@ -101,6 +108,7 @@ query {
       }
     }
   }
+}
 ```
 
 ## Multiple Return Types
@@ -110,6 +118,7 @@ Certain queries can return multiple types of objects, for example cable terminat
 ```
 {
   cable_list {
+    results {
       id
       a_terminations {
         ... on CircuitTerminationType {
@@ -127,22 +136,53 @@ Certain queries can return multiple types of objects, for example cable terminat
       }
     }
   }
+}
 ```
 
 The field "class_type" is an easy way to distinguish what type of object it is when viewing the returned data, or when filtering.  It contains the class name, for example "CircuitTermination" or "ConsoleServerPort".
 
 ## 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: