nautobot 2.1.0b1__py3-none-any.whl → 2.1.1__py3-none-any.whl

nautobot/project-static/docs/user-guide/feature-guides/graphql.html

@@ -14,7 +14,7 @@
         <link rel="prev" href="git-data-source.html">
       
       
-        <link rel="next" href="relationships.html">
+        <link rel="next" href="ip-address-merge-tool.html">
       
       <link rel="icon" href="../../assets/favicon.ico">
       <meta name="generator" content="mkdocs-1.5.3, mkdocs-material-9.1.21">
@@ -979,20 +979,6 @@
 
             
           
-            
-              
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../administration/configuration/node-configuration.html" class="md-nav__link">
-        Node.js Configuration
-      </a>
-    </li>
-  
-
-            
-          
         </ul>
       </nav>
     </li>
@@ -1414,8 +1400,10 @@
               
   
   
+    
   
-    <li class="md-nav__item">
+  
+    <li class="md-nav__item md-nav__item--active">
       
       <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
       
@@ -1557,150 +1545,6 @@
   
   
   
-    <li class="md-nav__item">
-      <a href="git-data-source.html" class="md-nav__link">
-        Git as a Data Source
-      </a>
-    </li>
-  
-
-            
-          
-            
-              
-  
-  
-    
-  
-  
-    <li class="md-nav__item md-nav__item--active">
-      
-      <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
-      
-      
-        
-      
-      
-        <label class="md-nav__link md-nav__link--active" for="__toc">
-          GraphQL
-          <span class="md-nav__icon md-icon"></span>
-        </label>
-      
-      <a href="graphql.html" class="md-nav__link md-nav__link--active">
-        GraphQL
-      </a>
-      
-        
-
-<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
-  
-  
-  
-    
-  
-  
-    <label class="md-nav__title" for="__toc">
-      <span class="md-nav__icon md-icon"></span>
-      Table of contents
-    </label>
-    <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
-      
-        <li class="md-nav__item">
-  <a href="#introduction" class="md-nav__link">
-    Introduction
-  </a>
-  
-    <nav class="md-nav" aria-label="Introduction">
-      <ul class="md-nav__list">
-        
-          <li class="md-nav__item">
-  <a href="#what-is-graphql" class="md-nav__link">
-    What is GraphQL?
-  </a>
-  
-</li>
-        
-          <li class="md-nav__item">
-  <a href="#how-graphql-simplifies-api-interactions" class="md-nav__link">
-    How GraphQL simplifies API Interactions
-  </a>
-  
-</li>
-        
-          <li class="md-nav__item">
-  <a href="#exploring-graphql-in-nautobot" class="md-nav__link">
-    Exploring GraphQL in Nautobot
-  </a>
-  
-</li>
-        
-          <li class="md-nav__item">
-  <a href="#documentation-explorer" class="md-nav__link">
-    Documentation Explorer
-  </a>
-  
-</li>
-        
-          <li class="md-nav__item">
-  <a href="#first-query" class="md-nav__link">
-    First Query
-  </a>
-  
-</li>
-        
-          <li class="md-nav__item">
-  <a href="#filtering-queries" class="md-nav__link">
-    Filtering Queries
-  </a>
-  
-</li>
-        
-      </ul>
-    </nav>
-  
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#using-the-graphql-api-in-nautobot" class="md-nav__link">
-    Using the GraphQL API in Nautobot
-  </a>
-  
-    <nav class="md-nav" aria-label="Using the GraphQL API in Nautobot">
-      <ul class="md-nav__list">
-        
-          <li class="md-nav__item">
-  <a href="#saving-queries" class="md-nav__link">
-    Saving Queries
-  </a>
-  
-</li>
-        
-      </ul>
-    </nav>
-  
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#closing" class="md-nav__link">
-    Closing
-  </a>
-  
-</li>
-      
-    </ul>
-  
-</nav>
-      
-    </li>
-  
-
-            
-          
-            
-              
-  
-  
-  
     <li class="md-nav__item">
       <a href="relationships.html" class="md-nav__link">
         Relationships
@@ -3786,23 +3630,9 @@
   
   
   
-    <li class="md-nav__item">
-      <a href="../../development/apps/api/views/view-overrides.html" class="md-nav__link">
-        View Overrides
-      </a>
-    </li>
-  
-
-            
-          
-            
-              
-  
-  
-  
     <li class="md-nav__item">
       <a href="../../development/apps/api/views/core-view-overrides.html" class="md-nav__link">
-        Legacy View Overrides
+        View Overrides
       </a>
     </li>
   
@@ -3891,7 +3721,7 @@
   
     <li class="md-nav__item">
       <a href="../../development/apps/api/platform-features/filter-extensions.html" class="md-nav__link">
-        Filter Extentions
+        Filter Extensions
       </a>
     </li>
   
@@ -4099,21 +3929,7 @@
   
     <li class="md-nav__item">
       <a href="../../development/apps/api/ui-extensions/object-detail-views.html" class="md-nav__link">
-        Object Detail Views
-      </a>
-    </li>
-  
-
-            
-          
-            
-              
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../../development/apps/api/ui-extensions/tabs.html" class="md-nav__link">
-        Tabs
+        Object Detail Views and Tabs
       </a>
     </li>
   
@@ -4784,6 +4600,20 @@
   
   
   
+    <li class="md-nav__item">
+      <a href="../../development/core/bootstrap-ui.html" class="md-nav__link">
+        Bootstrap UI
+      </a>
+    </li>
+  
+
+            
+          
+            
+              
+  
+  
+  
     <li class="md-nav__item">
       <a href="../../development/core/best-practices.html" class="md-nav__link">
         Best Practices
@@ -4896,20 +4726,6 @@
   
   
   
-    <li class="md-nav__item">
-      <a href="../../development/core/react-ui.html" class="md-nav__link">
-        React UI
-      </a>
-    </li>
-  
-
-            
-          
-            
-              
-  
-  
-  
     <li class="md-nav__item">
       <a href="../../development/core/role-internals.html" class="md-nav__link">
         Role Internals
@@ -5590,9 +5406,7 @@
 <a id="__codelineno-0-68" name="__codelineno-0-68" href="#__codelineno-0-68"></a><span class="p">}</span>
 </code></pre></div>
 </details>
-<!-- markdownlint-disable-next-line MD033 -->
-<p><br />
-There is a lot of useful information in that API call, but there is also a lot of information that is missing; such as interfaces and ip addresses associated with the devices. There is also potentially a lot of information that isn't needed for the specific task. To retrieve the missing information, subsequent API calls would need to be performed; and those API results would need to be correlated to the correct device.</p>
+<p>There is a lot of useful information in that API call, but there is also a lot of information that is missing; such as interfaces and ip addresses associated with the devices. There is also potentially a lot of information that isn't needed for the specific task. To retrieve the missing information, subsequent API calls would need to be performed; and those API results would need to be correlated to the correct device.</p>
 <p>GraphQL reduces the complexity of performing multiple API calls and correlating results by empowering the user to create their own query that provides the user exactly what they want and nothing that they don't, in a single API call.</p>
 <h3 id="exploring-graphql-in-nautobot">Exploring GraphQL in Nautobot<a class="headerlink" href="#exploring-graphql-in-nautobot" title="Permanent link">&para;</a></h3>
 <p>In Nautobot, there is a link to the GraphQL web interface at the bottom right-hand side of the page. The GraphQL web interface is called GraphiQL. Navigating to the URI (<code>/graphql</code>), brings up the GraphiQL tool for creating queries. This interface is useful for exploring the possibilities of GraphQL and validating that written queries execute successfully.</p>
@@ -5616,12 +5430,9 @@ There is a lot of useful information in that API call, but there is also a lot o
 <p>This query will retrieve a list of all devices by their hostname.</p>
 <details class="info">
 <summary>View GraphQL Query Results</summary>
-<p><!-- markdownlint-disable-next-line MD033 -->
-<img src="../images/graphql/04-graphql-query-01.png"></p>
+<p><img alt="GraphQL: Query Results" src="images/graphql/04-graphql-query-01.png" /></p>
 </details>
-<!-- markdownlint-disable-next-line MD033 -->
-<p><br />
-Now, let's modify the query to provide interface names for each device. We can do that by modifying the existing query to add <code>interfaces { name }</code> as a sub-query of <code>devices</code>. GraphiQL makes this process a bit easier, because it has syntax completion built in.</p>
+<p>Now, let's modify the query to provide interface names for each device. We can do that by modifying the existing query to add <code>interfaces { name }</code> as a sub-query of <code>devices</code>. GraphiQL makes this process a bit easier, because it has syntax completion built in.</p>
 <p><img alt="GraphQL: Autocompletion" src="images/graphql/05-graphiql-autocomplete.png" /></p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a><span class="k">query</span><span class="w"> </span><span class="p">{</span>
 <a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a><span class="w">  </span><span class="n">devices</span><span class="w"> </span><span class="p">{</span>
@@ -5635,12 +5446,9 @@ Now, let's modify the query to provide interface names for each device. We can d
 <p>The result is a list of all the devices by their hostname and associated interfaces by their names.</p>
 <details class="info">
 <summary>View GraphQL Query Results</summary>
-<p><!-- markdownlint-disable-next-line MD033 -->
-<img src="../images/graphql/06-graphql-query-02.png"></p>
+<p><img alt="GraphQL: Query Results" src="images/graphql/06-graphql-query-02.png" /></p>
 </details>
-<!-- markdownlint-disable-next-line MD033 -->
-<p><br />
-We can continue iterating on the query until we get exactly what we want from the query. For example, if I wanted to iterate on the previous query to not only display the interfaces of the devices, but also display the interface description, the IP Addresses associated with the interface, and whether or not the interface was a dedicated management interface; I would structure the query like:</p>
+<p>We can continue iterating on the query until we get exactly what we want from the query. For example, if I wanted to iterate on the previous query to not only display the interfaces of the devices, but also display the interface description, the IP Addresses associated with the interface, and whether or not the interface was a dedicated management interface; I would structure the query like:</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a><span class="k">query</span><span class="w"> </span><span class="p">{</span>
 <a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a><span class="w">  </span><span class="n">devices</span><span class="w"> </span><span class="p">{</span>
 <a id="__codelineno-3-3" name="__codelineno-3-3" href="#__codelineno-3-3"></a><span class="w">    </span><span class="n">name</span>
@@ -5658,20 +5466,16 @@ We can continue iterating on the query until we get exactly what we want from th
 <p>The results of the query look like:</p>
 <details class="info">
 <summary>View GraphQL Query Results</summary>
-<p><!-- markdownlint-disable-next-line MD033 -->
-<img src="../images/graphql/07-graphql-query-03.png"></p>
+<p><img alt="GraphQL: Query Results" src="images/graphql/07-graphql-query-03.png" /></p>
 </details>
 <h3 id="filtering-queries">Filtering Queries<a class="headerlink" href="#filtering-queries" title="Permanent link">&para;</a></h3>
 <p>These queries are great, but they are displaying the interface attributes and device names for every device in the Nautobot inventory. Nautobot allows users to filter queries at any level as desired to narrow the scope of the returned data. As an example, we can filter the queried devices by their location. This is done by adding <code>(location: "&lt;location name&gt;")</code> after <code>devices</code>. For example: <code>query { devices(location: "ams") { name }}</code> will display all devices in the <code>ams</code> location.</p>
 <p>As an example. We can query devices by their location. This is done by adding <code>(location: "&lt;location name&gt;")</code> after <code>devices</code>. For example: <code>query { devices(location: "ams") { name }}</code> will display all devices in the <code>ams</code> location.</p>
 <details class="info">
 <summary>View GraphQL Query Results</summary>
-<p><!-- markdownlint-disable-next-line MD033 -->
-<img src="../images/graphql/08-graphql-query-04.png"></p>
+<p><img alt="GraphQL: Query Results" src="images/graphql/08-graphql-query-04.png" /></p>
 </details>
-<!-- markdownlint-disable-next-line MD033 -->
-<p><br />
-GraphQL also allows you to filter by multiple attributes at once if desired. You can use the <em>Documentation Explorer</em> to assist you in finding criteria attributes to filter on. In this example, I add the <code>role</code> attribute in addition to <code>location</code>.</p>
+<p>GraphQL also allows you to filter by multiple attributes at once if desired. You can use the <em>Documentation Explorer</em> to assist you in finding criteria attributes to filter on. In this example, I add the <code>role</code> attribute in addition to <code>location</code>.</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a><span class="k">query</span><span class="w"> </span><span class="p">{</span>
 <a id="__codelineno-4-2" name="__codelineno-4-2" href="#__codelineno-4-2"></a><span class="w">  </span><span class="n">devices</span><span class="p">(</span><span class="n">location</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;ams&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">role</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;edge&quot;</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
 <a id="__codelineno-4-3" name="__codelineno-4-3" href="#__codelineno-4-3"></a><span class="w">    </span><span class="n">name</span>
@@ -5680,12 +5484,9 @@ GraphQL also allows you to filter by multiple attributes at once if desired. You
 </code></pre></div>
 <details class="info">
 <summary>View GraphQL Query Results</summary>
-<p><!-- markdownlint-disable-next-line MD033 -->
-<img src="../images/graphql/09-graphql-query-05.png"></p>
+<p><img alt="GraphQL: Query Results" src="images/graphql/09-graphql-query-05.png" /></p>
 </details>
-<!-- markdownlint-disable-next-line MD033 -->
-<p><br />
-You can also filter at deeper levels of the query. On many to one relationships you can filter the results based on an attribute of the field. Any attribute that relates to a GraphQLType can be filtered.</p>
+<p>You can also filter at deeper levels of the query. On many to one relationships you can filter the results based on an attribute of the field. Any attribute that relates to a GraphQLType can be filtered.</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a><span class="k">query</span><span class="w"> </span><span class="p">{</span>
 <a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a><span class="w">  </span><span class="n">devices</span><span class="p">(</span><span class="n">location</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;ams&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">role</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;edge&quot;</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
 <a id="__codelineno-5-3" name="__codelineno-5-3" href="#__codelineno-5-3"></a><span class="w">    </span><span class="n">name</span>
@@ -5706,21 +5507,22 @@ You can also filter at deeper levels of the query. On many to one relationships
 <a id="__codelineno-6-9" name="__codelineno-6-9" href="#__codelineno-6-9"></a><span class="w">  </span><span class="p">}</span>
 <a id="__codelineno-6-10" name="__codelineno-6-10" href="#__codelineno-6-10"></a><span class="p">}</span>
 </code></pre></div>
-<details class="info">
-<summary>View GraphQL Query Results</summary>
-<p><!-- markdownlint-disable-next-line MD033 -->
-<img src="../images/graphql/11-graphql-query-06.png"></p>
-</details>
 <div class="admonition version-added">
 <p class="admonition-title">Added in version 1.3.0</p>
+</div>
 <p>You can also paginate the results returned to you when the data set gets larger. To do so, use the keywords "limit" and "offset". The "limit" keyword will limit the count of results returned after the "offset". If no "offset" is specified, then the default offset is zero.</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-7-1" name="__codelineno-7-1" href="#__codelineno-7-1"></a><span class="k">query</span><span class="w"> </span><span class="p">{</span>
-<a id="__codelineno-7-2" name="__codelineno-7-2" href="#__codelineno-7-2"></a><span class="w">  </span><span class="n">devices</span><span class="p">(</span><span class="n">location</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;ams01&quot;</span><span class="p">,</span><span class="w"> </span><span class="p">,</span><span class="w"> </span><span class="n">limit</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="n">offset</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
-<a id="__codelineno-7-3" name="__codelineno-7-3" href="#__codelineno-7-3"></a><span class="w">    </span><span class="n">name</span>
-<a id="__codelineno-7-4" name="__codelineno-7-4" href="#__codelineno-7-4"></a><span class="w">  </span><span class="p">}</span>
-<a id="__codelineno-7-5" name="__codelineno-7-5" href="#__codelineno-7-5"></a><span class="p">}</span>
+<div class="highlight"><pre><span></span><code>```graphql
+query {
+  devices(location: &quot;ams01&quot;, limit: 1, offset: 1) {
+    name
+  }
+}
+```
 </code></pre></div>
-</div>
+<details class="info">
+<summary>View GraphQL Query Results</summary>
+<p><img alt="GraphQL: Query Results" src="images/graphql/11-graphql-query-06.png" /></p>
+</details>
 <h2 id="using-the-graphql-api-in-nautobot">Using the GraphQL API in Nautobot<a class="headerlink" href="#using-the-graphql-api-in-nautobot" title="Permanent link">&para;</a></h2>
 <p>Now that we've explored how to use the GraphiQL interface to help us create GraphQL queries, let's take our queries and call them with the REST API. This is where the real advantage is going to come in to play, because it will allow us to utilize these queries in a programmatic way.</p>
 <p><img alt="GraphQL: Swagger" src="images/graphql/10-graphql-swagger.png" /></p>
@@ -5832,13 +5634,13 @@ You can also filter at deeper levels of the query. On many to one relationships
         
         
           
-          <a href="relationships.html" class="md-footer__link md-footer__link--next" aria-label="Next: Relationships" rel="next">
+          <a href="ip-address-merge-tool.html" class="md-footer__link md-footer__link--next" aria-label="Next: IP Address Merge Tool" rel="next">
             <div class="md-footer__title">
               <span class="md-footer__direction">
                 Next
               </span>
               <div class="md-ellipsis">
-                Relationships
+                IP Address Merge Tool
               </div>
             </div>
             <div class="md-footer__button md-icon">