nautobot 2.3.16__py3-none-any.whl → 2.4.0__py3-none-any.whl

nautobot/project-static/docs/user-guide/platform-functionality/rest-api/overview.html

@@ -11,7 +11,7 @@
         <link rel="canonical" href="https://docs.nautobot.com/projects/core/en/stable/user-guide/platform-functionality/rest-api/overview.html">
       
       
-        <link rel="prev" href="../relationship.html">
+        <link rel="prev" href="../rendering-jinja-templates.html">
       
       
         <link rel="next" href="filtering.html">
@@ -2117,6 +2117,27 @@
 
               
             
+              
+                
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="../../feature-guides/wireless-networks-and-controllers.html" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Wireless Networks and Controllers
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
           </ul>
         </nav>
       
@@ -3949,6 +3970,27 @@
 
               
             
+              
+                
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="../../core-data-model/dcim/virtualdevicecontext.html" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Virtual Device Context
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
           </ul>
         </nav>
       
@@ -4561,6 +4603,123 @@
 
               
             
+              
+                
+  
+  
+  
+  
+    
+    
+    
+      
+      
+    
+    
+    <li class="md-nav__item md-nav__item--nested">
+      
+        
+        
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_3_9" >
+        
+          
+          
+          <div class="md-nav__link md-nav__container">
+            <a href="../../core-data-model/wireless/index.html" class="md-nav__link ">
+              
+  
+  <span class="md-ellipsis">
+    Wireless
+  </span>
+  
+
+            </a>
+            
+              
+              <label class="md-nav__link " for="__nav_2_3_9" id="__nav_2_3_9_label" tabindex="0">
+                <span class="md-nav__icon md-icon"></span>
+              </label>
+            
+          </div>
+        
+        <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_2_3_9_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_2_3_9">
+            <span class="md-nav__icon md-icon"></span>
+            Wireless
+          </label>
+          <ul class="md-nav__list" data-md-scrollfix>
+            
+              
+                
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="../../core-data-model/wireless/supporteddatarate.html" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Supported Data Rate
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="../../core-data-model/wireless/radioprofile.html" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Radio Profile
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="../../core-data-model/wireless/wirelessnetwork.html" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Wireless Network
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+          </ul>
+        </nav>
+      
+    </li>
+  
+
+              
+            
           </ul>
         </nav>
       
@@ -4774,6 +4933,27 @@
   
   
   
+    <li class="md-nav__item">
+      <a href="../events.html" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Event Notifications
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
     <li class="md-nav__item">
       <a href="../exporttemplate.html" class="md-nav__link">
         
@@ -4848,7 +5028,7 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_4_9" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_4_10" >
         
           
           
@@ -4864,14 +5044,14 @@
             </a>
             
               
-              <label class="md-nav__link " for="__nav_2_4_9" id="__nav_2_4_9_label" tabindex="0">
+              <label class="md-nav__link " for="__nav_2_4_10" id="__nav_2_4_10_label" tabindex="0">
                 <span class="md-nav__icon md-icon"></span>
               </label>
             
           </div>
         
-        <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_2_4_9_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_2_4_9">
+        <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_2_4_10_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_2_4_10">
             <span class="md-nav__icon md-icon"></span>
             GraphQL
           </label>
@@ -4944,7 +5124,7 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_4_11" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_4_12" >
         
           
           
@@ -4960,14 +5140,14 @@
             </a>
             
               
-              <label class="md-nav__link " for="__nav_2_4_11" id="__nav_2_4_11_label" tabindex="0">
+              <label class="md-nav__link " for="__nav_2_4_12" id="__nav_2_4_12_label" tabindex="0">
                 <span class="md-nav__icon md-icon"></span>
               </label>
             
           </div>
         
-        <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_2_4_11_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_2_4_11">
+        <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_2_4_12_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_2_4_12">
             <span class="md-nav__icon md-icon"></span>
             Jobs
           </label>
@@ -4979,6 +5159,27 @@
   
   
   
+    <li class="md-nav__item">
+      <a href="../jobs/kubernetes-job-support.html" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Kubernetes Job Support
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
     <li class="md-nav__item">
       <a href="../jobs/jobbutton.html" class="md-nav__link">
         
@@ -5042,6 +5243,27 @@
   
   
   
+    <li class="md-nav__item">
+      <a href="../jobs/jobqueue.html" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Job Queues
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
     <li class="md-nav__item">
       <a href="../jobs/job-scheduling-and-approvals.html" class="md-nav__link">
         
@@ -5153,6 +5375,27 @@
                 
   
   
+  
+  
+    <li class="md-nav__item">
+      <a href="../rendering-jinja-templates.html" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Rendering Jinja Templates
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
     
   
   
@@ -5168,7 +5411,7 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_4_16" checked>
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_4_18" checked>
         
           
           
@@ -5184,14 +5427,14 @@
             </a>
             
               
-              <label class="md-nav__link md-nav__link--active" for="__nav_2_4_16" id="__nav_2_4_16_label" tabindex="0">
+              <label class="md-nav__link md-nav__link--active" for="__nav_2_4_18" id="__nav_2_4_18_label" tabindex="0">
                 <span class="md-nav__icon md-icon"></span>
               </label>
             
           </div>
         
-        <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_2_4_16_label" aria-expanded="true">
-          <label class="md-nav__title" for="__nav_2_4_16">
+        <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_2_4_18_label" aria-expanded="true">
+          <label class="md-nav__title" for="__nav_2_4_18">
             <span class="md-nav__icon md-icon"></span>
             REST API
           </label>
@@ -5411,10 +5654,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_4_23" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_4_25" >
         
           
-          <label class="md-nav__link" for="__nav_2_4_23" id="__nav_2_4_23_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_2_4_25" id="__nav_2_4_25_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -5425,8 +5668,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_2_4_23_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_2_4_23">
+        <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_2_4_25_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_2_4_25">
             <span class="md-nav__icon md-icon"></span>
             Users
           </label>
@@ -6831,6 +7074,27 @@
   
   
   
+    <li class="md-nav__item">
+      <a href="../../../code-reference/nautobot/apps/events.html" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    nautobot.apps.events
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
     <li class="md-nav__item">
       <a href="../../../code-reference/nautobot/apps/exceptions.html" class="md-nav__link">
         
@@ -7379,6 +7643,123 @@
 
               
             
+              
+                
+  
+  
+  
+  
+    
+    
+    
+      
+      
+    
+    
+    <li class="md-nav__item md-nav__item--nested">
+      
+        
+        
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_2_9_5" >
+        
+          
+          
+          <div class="md-nav__link md-nav__container">
+            <a href="../../../development/apps/migration/ui-component-framework/index.html" class="md-nav__link ">
+              
+  
+  <span class="md-ellipsis">
+    UI Component Framework
+  </span>
+  
+
+            </a>
+            
+              
+              <label class="md-nav__link " for="__nav_3_2_9_5" id="__nav_3_2_9_5_label" tabindex="0">
+                <span class="md-nav__icon md-icon"></span>
+              </label>
+            
+          </div>
+        
+        <nav class="md-nav" data-md-level="4" aria-labelledby="__nav_3_2_9_5_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_3_2_9_5">
+            <span class="md-nav__icon md-icon"></span>
+            UI Component Framework
+          </label>
+          <ul class="md-nav__list" data-md-scrollfix>
+            
+              
+                
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="../../../development/apps/migration/ui-component-framework/migration-steps.html" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Migration steps
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="../../../development/apps/migration/ui-component-framework/custom-content.html" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Custom content
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="../../../development/apps/migration/ui-component-framework/best-practices.html" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Best practices
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+          </ul>
+        </nav>
+      
+    </li>
+  
+
+              
+            
           </ul>
         </nav>
       
@@ -7724,6 +8105,27 @@
   
   
   
+    <li class="md-nav__item">
+      <a href="../../../development/core/minikube-dev-environment-for-k8s-jobs.html" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Minikube Dev Environment for K8s Jobs
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
     <li class="md-nav__item">
       <a href="../../../development/core/model-checklist.html" class="md-nav__link">
         
@@ -7913,6 +8315,27 @@
   
   
   
+    <li class="md-nav__item">
+      <a href="../../../development/core/ui-component-framework.html" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    UI Component Framework
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
     <li class="md-nav__item">
       <a href="../../../development/core/release-checklist.html" class="md-nav__link">
         
@@ -7995,6 +8418,27 @@
   
   
   
+    <li class="md-nav__item">
+      <a href="../../../release-notes/version-2.4.html" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Version 2.4
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
     <li class="md-nav__item">
       <a href="../../../release-notes/version-2.3.html" class="md-nav__link">
         
@@ -9250,7 +9694,32 @@
 <details class="version-added">
 <summary>Added in version 2.0.0</summary>
 </details>
-<p>Many-to-many relationships differ from one-to-many and one-to-one relationships because they utilize a separate database table called a "through table" to track the relationships instead of a single field in an existing table. In Nautobot 2.0, some relationships such as <code>IPAddress</code> to <code>Interface</code>/<code>VMInterface</code>, <code>Prefix</code> to <code>VRF</code>, and <code>VRF</code> to <code>Device</code>/<code>VirtualMachine</code> are represented as many-to-many relationships. The REST API represents these relationships as nested objects for retrieval, but in order to create, update or delete these relationships, the through table endpoint must be used. Currently, the only through table endpoint available is the <a href="../../administration/upgrading/from-v1/upgrading-from-nautobot-v1.html#new-interface-to-ip-address-relationship-endpoint"><code>IPAddress</code> to <code>Interface</code>/<code>VMInterface</code> at <code>/api/ipam/ip-address-to-interface/</code></a>.</p>
+<p>Many-to-many relationships differ from one-to-many and one-to-one relationships because they utilize a separate database table called a "through table" to track the relationships instead of a single field in an existing table. In Nautobot 2.0, some relationships such as <code>IPAddress</code> to <code>Interface</code>/<code>VMInterface</code>, <code>Prefix</code> to <code>VRF</code>, and <code>VRF</code> to <code>Device</code>/<code>VirtualMachine</code> are represented as many-to-many relationships. The REST API typically provides a separate endpoint for manipulating the contents of each such "through table", for example:</p>
+<ul>
+<li><code>/api/dcim/interface-redundancy-group-associations/</code></li>
+<li><code>/api/dcim/device-types-to-software-image-files/</code></li>
+<li><code>/api/extras/contact-associations/</code></li>
+<li><code>/api/extras/job-queue-assignments/</code></li>
+<li><code>/api/extras/secrets-groups-associations/</code></li>
+<li><code>/api/extras/static-group-associations/</code></li>
+<li><code>/api/ipam/ip-address-to-interface/</code></li>
+<li><code>/api/ipam/prefix-location-assignments/</code></li>
+<li><code>/api/ipam/vlan-location-assignments/</code></li>
+<li><code>/api/ipam/vrf-device-assignments/</code></li>
+<li><code>/api/ipam/vrf-prefix-assignments/</code></li>
+<li>etc.</li>
+</ul>
+<p>In many (but not necessarily all) cases, as a convenience for users, the REST API for objects involved in a many-to-many relationship may also represent -- as a <strong>read-only</strong> field -- the objects on the other side of the relationship (bypassing the through table itself). For example, the <code>/api/ipam/vrfs/</code> REST API may include fields for each VRF record such as <code>prefixes</code> (the set of <code>Prefix</code> objects related to a given <code>VRF</code> by the <code>VRFPrefixAssignment</code> through table) and <code>devices</code> (the set of <code>Device</code> objects related to a given <code>VRF</code> by the <code>VRFDeviceAssignment</code> through table).</p>
+<div class="admonition warning">
+<p class="admonition-title">Many-to-many at scale</p>
+<p>When Nautobot contains a substantial number of related records, the inclusion of many-to-many related objects in the REST API may impose a significant amount of performance overhead in terms of processing time and memory usage. For example, if you have many VRFs, each of which is associated to 1000 Prefixes, listing VRFs in the REST API would also by default retrieve, serialize, and list the 1000 Prefix records <em>per VRF retrieved</em>.</p>
+</div>
+<p>To address the aforementioned performance/scalability concern, Nautobot supports the REST API query parameter <code>exclude_m2m</code>. When this parameter is specified (for example <code>GET /api/ipam/vrfs/?exclude_m2m=true</code>), many-to-many related objects will <strong>not</strong> be included in the REST API response, and in most cases will not even be retrieved from the database.</p>
+<details class="version-added">
+<summary>Added in version 2.4.0 — Added support for the <code>exclude_m2m</code> query parameter</summary>
+</details>
+<p>In a future Nautobot major release, a change in the REST API may make <code>exclude_m2m=true</code> the default behavior.</p>
+<p>See also <a href="filtering.html#filtering-included-fields">Filtering Included Fields</a>.</p>
 <h2 id="pagination">Pagination<a class="headerlink" href="#pagination" title="Permanent link">&para;</a></h2>
 <p>API responses which contain a list of many objects will be paginated for efficiency. The root JSON object returned by a list endpoint contains the following attributes:</p>
 <ul>
@@ -9690,12 +10159,14 @@ This parameter is an positive integer value that can range from 0 to 10. In most
 </li>
 </ul>
 <p>In the example above we can see that a single VRF, <code>green</code>, is a destination for the <code>site-to-vrf</code> Relationship from this Site, while there are currently no VRFs associated as sources for the <code>vrfs-to-locations</code> Relationship to this Site.</p>
+<p>See also <a href="filtering.html#filtering-included-fields">Filtering Included Fields</a>.</p>
 <h3 id="including-config-contexts">Including Config Contexts<a class="headerlink" href="#including-config-contexts" title="Permanent link">&para;</a></h3>
 <p>When retrieving Devices and Virtual Machines via the REST API, it is possible to also retrive the rendered <a href="../../core-data-model/extras/configcontext.html">configuration context data</a> for each such object if desired. Because rendering this data can be time consuming, it is <em>not</em> included in the REST API responses by default. If you wish to include config context data in the response, you must opt in by specifying the query parameter <code>include=config_context</code> as a part of your request.</p>
 <details class="version-changed">
 <summary>Changed in version 2.0.0</summary>
 <p>In Nautobot 1.x, the rendered configuration context was included by default in the REST API response unless specifically excluded with the query parameter <code>exclude=config_context</code>. This behavior has been reversed in Nautobot 2.0 and the <code>exclude</code> query parameter is no longer supported.</p>
 </details>
+<p>See also <a href="filtering.html#filtering-included-fields">Filtering Included Fields</a>.</p>
 <h3 id="creating-a-new-object">Creating a New Object<a class="headerlink" href="#creating-a-new-object" title="Permanent link">&para;</a></h3>
 <p>To create a new object, make a <code>POST</code> request to the model's <em>list</em> endpoint with JSON data pertaining to the object being created. Note that a REST API token is required for all write operations; see the <a href="authentication.html">authentication documentation</a> for more information. Also be sure to set the <code>Content-Type</code> HTTP header to <code>application/json</code>. As always, it's a good practice to also set the <code>Accept</code> HTTP header to include the requested REST API version.</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-26-1" name="__codelineno-26-1" href="#__codelineno-26-1"></a>curl -s -X POST \
@@ -9933,7 +10404,7 @@ This parameter is an positive integer value that can range from 0 to 10. In most
       <nav class="md-footer__inner md-grid" aria-label="Footer" >
         
           
-          <a href="../relationship.html" class="md-footer__link md-footer__link--prev" aria-label="Previous: Relationships">
+          <a href="../rendering-jinja-templates.html" class="md-footer__link md-footer__link--prev" aria-label="Previous: Rendering Jinja Templates">
             <div class="md-footer__button md-icon">
               
               <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg>
@@ -9943,7 +10414,7 @@ This parameter is an positive integer value that can range from 0 to 10. In most
                 Previous
               </span>
               <div class="md-ellipsis">
-                Relationships
+                Rendering Jinja Templates
               </div>
             </div>
           </a>
@@ -10045,7 +10516,7 @@ This parameter is an positive integer value that can range from 0 to 10. In most
     </div>
     
     
-    <script id="__config" type="application/json">{"base": "../../..", "features": ["content.code.copy", "content.tabs.link", "navigation.footer", "navigation.tabs", "navigation.tabs.sticky", "navigation.tracking", "search.highlight", "search.share", "search.suggest"], "search": "../../../assets/javascripts/workers/search.6ce7567c.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script>
+    <script id="__config" type="application/json">{"base": "../../..", "features": ["content.code.annotate", "content.code.copy", "content.tabs.link", "navigation.footer", "navigation.tabs", "navigation.tabs.sticky", "navigation.tracking", "search.highlight", "search.share", "search.suggest"], "search": "../../../assets/javascripts/workers/search.6ce7567c.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script>
     
     
       <script src="../../../assets/javascripts/bundle.88dd0f4e.min.js"></script>