| <!doctype html> |
| <html class="docs-version-3.12" lang="en" dir="ltr"> |
| <head> |
| <meta charset="UTF-8"> |
| <meta name="viewport" content="width=device-width,initial-scale=1"> |
| <meta name="ahrefs-site-verification" content="c2f7370ecf46173f4fb25f114e74c97e0a2976d4f02f61c9b00a9d7d34e34698"> |
| <meta name="generator" content="Docusaurus v2.0.0-beta.6"> |
| <link rel="search" type="application/opensearchdescription+xml" title="Apache APISIX® -- Cloud-Native API Gateway and AI Gateway" href="/opensearch.xml"> |
| <script type="application/ld+json">{"@context":"https://schema.org","@type":"WebSite","name":"Apache APISIX","url":"https://apisix.apache.org"}</script> |
| <script src="https://widget.kapa.ai/kapa-widget.bundle.js" data-website-id="24b59d9a-682e-4c3d-9e83-bf2ee85cdc19" data-project-name="APISIX" data-project-color="#E8442E" data-project-logo="https://static.apiseven.com/202202/apache-apisix.png" data-modal-disclaimer="This is a custom LLM for APISIX with access to all developer documentation, GitHub issues and discussions." data-modal-example-questions="How to set up canary release in APISIX?,How to develop a custom APISIX plugin?,How to use custom NGINX configuration in APISIX?,How to configure mTLS between clients and APISIX?,How to only allow a specific APISIX consumer to access special services or routes?" async></script><title data-react-helmet="true">Admin API | Apache APISIX® -- Cloud-Native API Gateway and AI Gateway</title><meta data-react-helmet="true" property="og:image" content="https://static.apiseven.com/202202/apache-apisix.png"><meta data-react-helmet="true" name="twitter:image" content="https://static.apiseven.com/202202/apache-apisix.png"><meta data-react-helmet="true" property="og:url" content="https://apisix.apache.org/docs/apisix/3.12/admin-api/"><meta data-react-helmet="true" name="docsearch:language" content="en"><meta data-react-helmet="true" name="docsearch:version" content="3.12"><meta data-react-helmet="true" name="docsearch:docusaurus_tag" content="docs-docs-apisix-3.12"><meta data-react-helmet="true" name="robots" content="index,follow"><meta data-react-helmet="true" name="twitter:card" content="summary"><meta data-react-helmet="true" property="og:title" content="Admin API | Apache APISIX® -- Cloud-Native API Gateway and AI Gateway"><meta data-react-helmet="true" name="description" content="This article introduces the functions supported by the Apache APISIX Admin API, which you can use to get, create, update, and delete resources."><meta data-react-helmet="true" property="og:description" content="This article introduces the functions supported by the Apache APISIX Admin API, which you can use to get, create, update, and delete resources."><meta data-react-helmet="true" name="keywords" content="Apache APISIX,API Gateway,Admin API,Route,Plugin,Upstream"><link data-react-helmet="true" rel="shortcut icon" href="https://static.apiseven.com/202202/favicon.png"><link data-react-helmet="true" rel="canonical" href="https://apisix.apache.org/docs/apisix/3.12/admin-api/"><link data-react-helmet="true" rel="alternate" href="https://apisix.apache.org/docs/apisix/3.12/admin-api/" hreflang="en"><link data-react-helmet="true" rel="alternate" href="https://apisix.apache.org/zh/docs/apisix/3.12/admin-api/" hreflang="zh"><link data-react-helmet="true" rel="alternate" href="https://apisix.apache.org/docs/apisix/3.12/admin-api/" hreflang="x-default"><link data-react-helmet="true" rel="preconnect" href="https://38VC84A2WJ-dsn.algolia.net" crossorigin="anonymous"><link rel="preload" href="https://static.apiseven.com/202202/MaisonNeue-Medium.otf" as="font" type="font/otf" crossorigin> |
| <link rel="preload" href="https://static.apiseven.com/202202/MaisonNeue-Bold.otf" as="font" type="font/otf" crossorigin> |
| <link rel="preload" href="https://static.apiseven.com/202202/MaisonNeue-Light.otf" as="font" type="font/otf" crossorigin> |
| <link rel="preload" href="https://static.apiseven.com/202202/MaisonNeue-Demi.otf" as="font" type="font/otf" crossorigin> |
| <link rel="preload" href="https://static.apiseven.com/202202/MaisonNeue-ExtraBold.otf" as="font" type="font/otf" crossorigin> |
| <link rel="preload" href="https://apisix-website-static.apiseven.com/assets/js/runtime~main.4fb0d5b2.js" as="script"> |
| <link rel="preload" href="https://apisix-website-static.apiseven.com/assets/js/main.bee0d8fc.js" as="script"> |
| <link rel="stylesheet" href="https://apisix-website-static.apiseven.com/assets/css/styles.8de0825e.css"> |
| |
| <script>var _paq=window._paq=window._paq||[];_paq.push(["disableCookies"]),_paq.push(["trackPageView"]),_paq.push(["enableLinkTracking"]),function(){var a="https://analytics.apache.org/";_paq.push(["setTrackerUrl",a+"matomo.php"]),_paq.push(["setSiteId","17"]);var e=document,p=e.createElement("script"),t=e.getElementsByTagName("script")[0];p.async=!0,p.src=a+"matomo.js",t.parentNode.insertBefore(p,t)}()</script> |
| |
| </head> |
| <body> |
| <script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){var t=null;try{t=localStorage.getItem("theme")}catch(t){}return t}();t(null!==e?e:"light")}(),document.documentElement.setAttribute("data-announcement-bar-initially-dismissed",function(){try{return"true"===localStorage.getItem("docusaurus.announcement.dismiss")}catch(t){}return!1}())</script><div id="__docusaurus"> |
| <div><a href="#" class="skipToContent_OuoZ">Skip to main content</a></div><div class="announcementBar_axC9" style="background-color:#e8433e;color:white" role="banner"><div class="announcementBarPlaceholder_xYHE"></div><div class="announcementBarContent_6uhP">🤔 Introducing APISIX AI Gateway – Built for LLMs and AI workloads. <a target="_blank" rel="noopener noreferrer" href="/ai-gateway/"> Learn More</a></div><button type="button" class="clean-btn close announcementBarClose_A3A1" aria-label="Close"><svg viewBox="0 0 24 24" width="14" height="14" fill="currentColor"><path d="M24 20.188l-8.315-8.209 8.2-8.282-3.697-3.697-8.212 8.318-8.31-8.203-3.666 3.666 8.321 8.24-8.206 8.313 3.666 3.666 8.237-8.318 8.285 8.203z"></path></svg></button></div><nav class="navbar navbar--fixed-top navbarHideable_RReh"><div class="navbar__inner"><div class="navbar__items"><button aria-label="Navigation bar toggle" class="navbar__toggle clean-btn" type="button" tabindex="0"><svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><a target="_parent" class="navbar__brand" href="/"><img src="/img/logo2.svg" alt="Apache APISIX®" class="themedImage_TMUO themedImage--light_4Vu1 navbar__logo"><img src="/img/logo2.svg" alt="Apache APISIX®" class="themedImage_TMUO themedImage--dark_uzRr navbar__logo"><b class="navbar__title">Apache APISIX®</b></a></div><div class="navbar__items navbar__items--right"><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a aria-current="page" class="navbar__link" target="_parent" href="/docs/">Docs</a><ul class="dropdown__menu"><li><a class="dropdown__link" target="_parent" href="/docs/apisix/getting-started/">Apache APISIX®️</a></li><li><a class="dropdown__link" target="_parent" href="/docs/apisix/next/dashboard/">Apache APISIX®️ Dashboard</a></li><li><a class="dropdown__link" target="_parent" href="/docs/ingress-controller/overview/">Apache APISIX®️ Ingress Controller</a></li><li><a class="dropdown__link" target="_parent" href="/docs/helm-chart/apisix/">Apache APISIX®️ Helm Charts</a></li><li><a class="dropdown__link" target="_parent" href="/docs/docker/build/">Apache APISIX®️ Docker</a></li><li><a class="dropdown__link" target="_parent" href="/docs/java-plugin-runner/development/">Apache APISIX®️ Java Plugin Runner</a></li><li><a class="dropdown__link" target="_parent" href="/docs/go-plugin-runner/getting-started/">Apache APISIX®️ Go Plugin Runner</a></li><li><a class="dropdown__link" target="_parent" href="/docs/python-plugin-runner/getting-started/">Apache APISIX®️ Python Plugin Runner</a></li><li><a class="dropdown__link" target="_parent" href="/docs/general/join/">General</a></li></ul></div><a class="navbar__item navbar__link" target="_parent" href="/blog/">Blog</a><a class="navbar__item navbar__link" target="_parent" href="/blog/tags/case-studies/">Case Studies</a><a class="navbar__item navbar__link" target="_parent" href="/downloads/">Downloads</a><a class="navbar__item navbar__link" target="_parent" href="/help/">Help</a><a class="navbar__item navbar__link" target="_parent" href="/team/">Team</a><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a class="navbar__link">Resources</a><ul class="dropdown__menu"><li><a class="dropdown__link" target="_parent" href="/showcase/">Showcase</a></li><li><a class="dropdown__link" target="_parent" href="/docs/general/code-samples/">Code Samples</a></li><li><a class="dropdown__link" target="_parent" href="/plugins/">PluginHub</a></li><li><a class="dropdown__link" target="_parent" href="/docs/general/join/">Community</a></li><li><a class="dropdown__link" target="_parent" href="/docs/general/events/">Events</a></li><li><a href="https://github.com/apache/apisix/milestones" target="_parent" rel="noopener noreferrer" class="dropdown__link">Roadmap</a></li></ul></div><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a href="#" class="navbar__link"><span><svg viewBox="0 0 20 20" width="20" height="20" aria-hidden="true" class="iconLanguage_zID8"><path fill="currentColor" d="M19.753 10.909c-.624-1.707-2.366-2.726-4.661-2.726-.09 0-.176.002-.262.006l-.016-2.063 3.525-.607c.115-.019.133-.119.109-.231-.023-.111-.167-.883-.188-.976-.027-.131-.102-.127-.207-.109-.104.018-3.25.461-3.25.461l-.013-2.078c-.001-.125-.069-.158-.194-.156l-1.025.016c-.105.002-.164.049-.162.148l.033 2.307s-3.061.527-3.144.543c-.084.014-.17.053-.151.143.019.09.19 1.094.208 1.172.018.08.072.129.188.107l2.924-.504.035 2.018c-1.077.281-1.801.824-2.256 1.303-.768.807-1.207 1.887-1.207 2.963 0 1.586.971 2.529 2.328 2.695 3.162.387 5.119-3.06 5.769-4.715 1.097 1.506.256 4.354-2.094 5.98-.043.029-.098.129-.033.207l.619.756c.08.096.206.059.256.023 2.51-1.73 3.661-4.515 2.869-6.683zm-7.386 3.188c-.966-.121-.944-.914-.944-1.453 0-.773.327-1.58.876-2.156a3.21 3.21 0 011.229-.799l.082 4.277a2.773 2.773 0 01-1.243.131zm2.427-.553l.046-4.109c.084-.004.166-.01.252-.01.773 0 1.494.145 1.885.361.391.217-1.023 2.713-2.183 3.758zm-8.95-7.668a.196.196 0 00-.196-.145h-1.95a.194.194 0 00-.194.144L.008 16.916c-.017.051-.011.076.062.076h1.733c.075 0 .099-.023.114-.072l1.008-3.318h3.496l1.008 3.318c.016.049.039.072.113.072h1.734c.072 0 .078-.025.062-.076-.014-.05-3.083-9.741-3.494-11.04zm-2.618 6.318l1.447-5.25 1.447 5.25H3.226z"></path></svg><span>English</span></span></a><ul class="dropdown__menu"><li><a href="/docs/apisix/3.12/admin-api/" target="_self" rel="noopener noreferrer" class="dropdown__link dropdown__link--active" style="text-transform:capitalize">English</a></li><li><a href="/zh/docs/apisix/3.12/admin-api/" target="_self" rel="noopener noreferrer" class="dropdown__link" style="text-transform:capitalize">简体中文</a></li></ul></div><div class="react-toggle toggle_2i4l react-toggle--disabled"><div class="react-toggle-track" role="button" tabindex="-1"><div class="react-toggle-track-check"><span class="toggle_iYfV">🌜</span></div><div class="react-toggle-track-x"><span class="toggle_iYfV">🌞</span></div><div class="react-toggle-thumb"></div></div><input type="checkbox" class="react-toggle-screenreader-only" aria-label="Switch between dark and light mode"></div><div class="searchBox_fBfG"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><svg width="20" height="20" class="DocSearch-Search-Icon" viewBox="0 0 20 20"><path d="M14.386 14.386l4.0877 4.0877-4.0877-4.0877c-2.9418 2.9419-7.7115 2.9419-10.6533 0-2.9419-2.9418-2.9419-7.7115 0-10.6533 2.9418-2.9419 7.7115-2.9419 10.6533 0 2.9419 2.9418 2.9419 7.7115 0 10.6533z" stroke="currentColor" fill="none" fill-rule="evenodd" stroke-linecap="round" stroke-linejoin="round"></path></svg><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"></span></button></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div class="main-wrapper docs-wrapper docs-doc-page"><div class="docPage_GMj9"><button class="clean-btn backToTopButton_i9tI" type="button"><svg viewBox="0 0 24 24" width="28"><path d="M7.41 15.41L12 10.83l4.59 4.58L18 14l-6-6-6 6z" fill="currentColor"></path></svg></button><aside class="docSidebarContainer_k0Pq"><div class="sidebar_LIo8 sidebarWithHideableNavbar_CMI-"><a target="_parent" tabindex="-1" class="sidebarLogo_P87M" href="/"><img src="/img/logo2.svg" alt="Apache APISIX®" class="themedImage_TMUO themedImage--light_4Vu1"><img src="/img/logo2.svg" alt="Apache APISIX®" class="themedImage_TMUO themedImage--dark_uzRr"><b>Apache APISIX®</b></a><div class="sidebarVersionSwitch_0QIZ">Version:<div class="navbar__item dropdown dropdown--hoverable"><a class="navbar__link" href="/docs/apisix/3.12/getting-started/README/">3.12</a><ul class="dropdown__menu"><li><a class="dropdown__link" href="/docs/apisix/next/admin-api/"><div>Next</div></a></li><li><a class="dropdown__link" href="/docs/apisix/admin-api/"><div>3.14<div class="badge_6FVu Latest_oyqS">Latest</div></div></a></li><li><a class="dropdown__link" href="/docs/apisix/3.13/admin-api/"><div>3.13</div></a></li><li><a aria-current="page" class="dropdown__link dropdown__link--active" href="/docs/apisix/3.12/admin-api/"><div>3.12</div></a></li><li><a class="dropdown__link" href="/docs/apisix/3.11/admin-api/"><div>3.11</div></a></li><li><a class="dropdown__link" href="/docs/apisix/3.10/admin-api/"><div>3.10</div></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/3.9/getting-started/readme/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>3.9<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/3.8/getting-started/readme/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>3.8<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/3.7/getting-started/readme/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>3.7<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/3.6/getting-started/readme/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>3.6<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/3.5/getting-started/readme/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>3.5<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/3.4/getting-started/readme/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>3.4<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/3.3/getting-started/readme/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>3.3<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/3.2/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>3.2<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/3.1/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>3.1<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/3.0/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>3.0<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/2.15/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>2.15<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/2.14/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>2.14<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/2.13/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>2.13<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/2.12/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>2.12<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/2.11/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>2.11<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/2.10/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>2.10<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/2.9/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>2.9<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/2.8/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>2.8<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/2.7/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>2.7<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/2.6/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>2.6<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/2.5/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>2.5<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/2.4/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>2.4<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li></ul></div></div><nav class="menu thin-scrollbar menu_oAhv menuWithAnnouncementBar_IVfW"><ul class="theme-doc-sidebar-menu menu__list"><li class="theme-doc-sidebar-item-category menu__list-item menu__list-item--collapsed"><a class="menu__link menu__link--sublist" href="#">Getting Started</a></li><li class="theme-doc-sidebar-item-link menu__list-item"><a class="menu__link" href="/docs/apisix/3.12/installation-guide/">Installation</a></li><li class="theme-doc-sidebar-item-link menu__list-item"><a class="menu__link" href="/docs/apisix/3.12/architecture-design/apisix/">Architecture</a></li><li class="theme-doc-sidebar-item-category menu__list-item menu__list-item--collapsed"><a class="menu__link menu__link--sublist" href="#">Tutorials</a></li><li class="theme-doc-sidebar-item-category menu__list-item menu__list-item--collapsed"><a class="menu__link menu__link--sublist" href="#">Terminology</a></li><li class="theme-doc-sidebar-item-category menu__list-item menu__list-item--collapsed"><a class="menu__link menu__link--sublist" href="#">Plugins</a></li><li class="theme-doc-sidebar-item-category menu__list-item"><a class="menu__link menu__link--sublist menu__link--active" href="#">API</a><ul style="display:block;overflow:visible;height:auto" class="menu__list"><li class="theme-doc-sidebar-item-link menu__list-item"><a class="menu__link menu__link--active" aria-current="page" tabindex="0" href="/docs/apisix/3.12/admin-api/">Admin API</a></li><li class="theme-doc-sidebar-item-link menu__list-item"><a class="menu__link" tabindex="0" href="/docs/apisix/3.12/control-api/">Control API</a></li></ul></li><li class="theme-doc-sidebar-item-category menu__list-item menu__list-item--collapsed"><a class="menu__link menu__link--sublist" href="#">Development</a></li><li class="theme-doc-sidebar-item-link menu__list-item"><a class="menu__link" href="/docs/apisix/3.12/deployment-modes/">Deployment modes</a></li><li class="theme-doc-sidebar-item-link menu__list-item"><a class="menu__link" href="/docs/apisix/3.12/FAQ/">FAQ</a></li><li class="theme-doc-sidebar-item-category menu__list-item menu__list-item--collapsed"><a class="menu__link menu__link--sublist" href="#">Others</a></li><li class="theme-doc-sidebar-item-link menu__list-item"><a href="https://github.com/apache/apisix/blob/master/CHANGELOG.md" target="_blank" rel="noopener noreferrer" class="menu__link"><span>CHANGELOG<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li class="theme-doc-sidebar-item-link menu__list-item"><a class="menu__link" href="/docs/apisix/3.12/upgrade-guide-from-2.15.x-to-3.0.0/">Upgrade Guide</a></li></ul></nav><button type="button" title="Collapse sidebar" aria-label="Collapse sidebar" class="button button--secondary button--outline collapseSidebarButton_EBxv"><svg width="20" height="20" aria-hidden="true" class="collapseSidebarButtonIcon_AF9Q"><g fill="#7a7a7a"><path d="M9.992 10.023c0 .2-.062.399-.172.547l-4.996 7.492a.982.982 0 01-.828.454H1c-.55 0-1-.453-1-1 0-.2.059-.403.168-.551l4.629-6.942L.168 3.078A.939.939 0 010 2.528c0-.548.45-.997 1-.997h2.996c.352 0 .649.18.828.45L9.82 9.472c.11.148.172.347.172.55zm0 0"></path><path d="M19.98 10.023c0 .2-.058.399-.168.547l-4.996 7.492a.987.987 0 01-.828.454h-3c-.547 0-.996-.453-.996-1 0-.2.059-.403.168-.551l4.625-6.942-4.625-6.945a.939.939 0 01-.168-.55 1 1 0 01.996-.997h3c.348 0 .649.18.828.45l4.996 7.492c.11.148.168.347.168.55zm0 0"></path></g></svg></button></div></aside><main class="docMainContainer_Q970"><div class="container padding-top--md padding-bottom--lg"><div class="row"><div class="col docItemCol_zHA2"><div class="theme-doc-version-banner alert alert--warning margin-bottom--md" role="alert"><div>This is documentation for Apache APISIX® -- Cloud-Native API Gateway and AI Gateway <b>3.12</b>, which is no longer actively maintained.</div><div class="margin-top--md">For up-to-date documentation, see the <b><a href="/docs/apisix/admin-api/">latest version</a></b> (3.14).</div></div><div class="docItemContainer_oiyr"><article><span class="theme-doc-version-badge badge badge--secondary">Version: 3.12</span><div class="tocCollapsible_aw-L theme-doc-toc-mobile tocMobile_Tx6Y"><button type="button" class="clean-btn tocCollapsibleButton_zr6a">On this page</button></div><div class="theme-doc-markdown markdown"><header><h1>Admin API</h1></header><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="description"></a>Description<a class="hash-link" href="#description" title="Direct link to heading">#</a></h2><p>The Admin API lets users control their deployed Apache APISIX instance. The <a href="/docs/apisix/3.12/architecture-design/apisix/">architecture design</a> gives an idea about how everything fits together.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="configuration"></a>Configuration<a class="hash-link" href="#configuration" title="Direct link to heading">#</a></h2><p>When APISIX is started, the Admin API will listen on port <code>9180</code> by default and take the API prefixed with <code>/apisix/admin</code>.</p><p>Therefore, to avoid conflicts between your designed API and <code>/apisix/admin</code>, you can modify the configuration file <a href="https://github.com/apache/apisix/blob/master/conf/config.yaml" rel="noopener noreferrer"><code>/conf/config.yaml</code></a> to modify the default listening port.</p><p>APISIX supports setting the IP access allowlist of Admin API to prevent APISIX from being illegally accessed and attacked. You can configure the IP addresses to allow access in the <code>deployment.admin.allow_admin</code> option in the <code>./conf/config.yaml</code> file.</p><p>The <code>X-API-KEY</code> shown below refers to the <code>deployment.admin.admin_key.key</code> in the <code>./conf/config.yaml</code> file, which is the access token for the Admin API.</p><div class="admonition admonition-tip alert alert--success"><div class="admonition-heading"><h5><span class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" width="12" height="16" viewBox="0 0 12 16"><path fill-rule="evenodd" d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"></path></svg></span>tip</h5></div><div class="admonition-content"><p>For security reasons, please modify the default <code>admin_key</code>, and check the <code>allow_admin</code> IP access list.</p></div></div><div class="codeBlockContainer_EiTO"><div style="color:#393A34;background-color:#f6f8fa" class="codeBlockTitle_PQMO">./conf/config.yaml</div><div class="codeBlockContent_X2I6 yaml"><pre tabindex="0" class="prism-code language-yaml codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token key atrule" style="color:#00a4db">deployment</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">admin</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">admin_key</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">-</span><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">name</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> admin</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">key</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> edd1c9f034335f136f87ad84b625c8f1 </span><span class="token comment" style="color:#999988;font-style:italic"># using fixed API token has security risk, please update it when you deploy to production environment</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">role</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> admin</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">allow_admin</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token comment" style="color:#999988;font-style:italic"># http://nginx.org/en/docs/http/ngx_http_access_module.html#allow</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">-</span><span class="token plain"> 127.0.0.0/24</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">admin_listen</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">ip</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> 0.0.0.0 </span><span class="token comment" style="color:#999988;font-style:italic"># Specific IP, if not set, the default value is `0.0.0.0`.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">port</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">9180</span><span class="token plain"> </span><span class="token comment" style="color:#999988;font-style:italic"># Specific port, which must be different from node_listen's port.</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="using-environment-variables"></a>Using environment variables<a class="hash-link" href="#using-environment-variables" title="Direct link to heading">#</a></h3><p>To configure via environment variables, you can use the <code>${{VAR}}</code> syntax. For instance:</p><div class="codeBlockContainer_EiTO"><div style="color:#393A34;background-color:#f6f8fa" class="codeBlockTitle_PQMO">./conf/config.yaml</div><div class="codeBlockContent_X2I6 yaml"><pre tabindex="0" class="prism-code language-yaml codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token key atrule" style="color:#00a4db">deployment</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">admin</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">admin_key</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">-</span><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">name</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> admin</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">key</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> $</span><span class="token punctuation" style="color:#393A34">{</span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain">ADMIN_KEY</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">role</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> admin</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">allow_admin</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">-</span><span class="token plain"> 127.0.0.0/24</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">admin_listen</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">ip</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> 0.0.0.0</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">port</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">9180</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>And then run <code>export ADMIN_KEY=$your_admin_key</code> before running <code>make init</code>.</p><p>If the configured environment variable can't be found, an error will be thrown.</p><p>If you want to use a default value when the environment variable is not set, use <code>${{VAR:=default_value}}</code> instead. For instance:</p><div class="codeBlockContainer_EiTO"><div style="color:#393A34;background-color:#f6f8fa" class="codeBlockTitle_PQMO">./conf/config.yaml</div><div class="codeBlockContent_X2I6 yaml"><pre tabindex="0" class="prism-code language-yaml codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token key atrule" style="color:#00a4db">deployment</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">admin</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">admin_key</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">-</span><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">name</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> admin</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">key</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> $</span><span class="token punctuation" style="color:#393A34">{</span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain">ADMIN_KEY</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain">=edd1c9f034335f136f87ad84b625c8f1</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">role</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> admin</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">allow_admin</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">-</span><span class="token plain"> 127.0.0.0/24</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">admin_listen</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">ip</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> 0.0.0.0</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">port</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">9180</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>This will find the environment variable <code>ADMIN_KEY</code> first, and if it does not exist, it will use <code>edd1c9f034335f136f87ad84b625c8f1</code> as the default value.</p><p>You can also specify environment variables in yaml keys. This is specifically useful in the <code>standalone</code> <a href="/docs/apisix/3.12/deployment-modes/#standalone">mode</a> where you can specify the upstream nodes as follows:</p><div class="codeBlockContainer_EiTO"><div style="color:#393A34;background-color:#f6f8fa" class="codeBlockTitle_PQMO">./conf/apisix.yaml</div><div class="codeBlockContent_X2I6 yaml"><pre tabindex="0" class="prism-code language-yaml codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token key atrule" style="color:#00a4db">routes</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">-</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">uri</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"/test"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">upstream</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">nodes</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">"${{HOST_IP}}:${{PORT}}"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">type</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> roundrobin</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic">#END</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="force-delete"></a>Force Delete<a class="hash-link" href="#force-delete" title="Direct link to heading">#</a></h3><p>By default, the Admin API checks for references between resources and will refuse to delete resources in use.</p><p>You can make a force deletion by adding the request argument <code>force=true</code> to the delete request, for example:</p><div class="admonition admonition-note alert alert--secondary"><div class="admonition-heading"><h5><span class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" width="14" height="16" viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</h5></div><div class="admonition-content"><p>You can fetch the <code>admin_key</code> from <code>config.yaml</code> and save to an environment variable with the following command:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 bash"><pre tabindex="0" class="prism-code language-bash codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token assign-left variable" style="color:#36acaa">admin_key</span><span class="token operator" style="color:#393A34">=</span><span class="token variable" style="color:#36acaa">$(</span><span class="token variable" style="color:#36acaa">yq </span><span class="token variable string" style="color:#e3116c">'.deployment.admin.admin_key[0].key'</span><span class="token variable" style="color:#36acaa"> conf/config.yaml </span><span class="token variable operator" style="color:#393A34">|</span><span class="token variable" style="color:#36acaa"> </span><span class="token variable function" style="color:#d73a49">sed</span><span class="token variable" style="color:#36acaa"> </span><span class="token variable string" style="color:#e3116c">'s/"//g'</span><span class="token variable" style="color:#36acaa">)</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 bash"><pre tabindex="0" class="prism-code language-bash codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">$ </span><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/upstreams/1 -H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PUT -d </span><span class="token string" style="color:#e3116c">'{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "nodes": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "127.0.0.1:8080": 1</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> },</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "type": "roundrobin"</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">$ </span><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/routes/1 -H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PUT -d </span><span class="token string" style="color:#e3116c">'{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "uri": "/*",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "upstream_id": 1</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"value"</span><span class="token plain">:</span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"priority"</span><span class="token plain">:0,</span><span class="token string" style="color:#e3116c">"upstream_id"</span><span class="token plain">:1,</span><span class="token string" style="color:#e3116c">"uri"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"/*"</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"create_time"</span><span class="token plain">:1689038794,</span><span class="token string" style="color:#e3116c">"id"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"1"</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"status"</span><span class="token plain">:1,</span><span class="token string" style="color:#e3116c">"update_time"</span><span class="token plain">:1689038916</span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"key"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"/apisix/routes/1"</span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">$ </span><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/upstreams/1 -H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X DELETE</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"error_msg"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"can not delete this upstream, route [1] is still using it now"</span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">$ </span><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"http://127.0.0.1:9180/apisix/admin/upstreams/1?force=anyvalue"</span><span class="token plain"> -H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X DELETE</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"error_msg"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"can not delete this upstream, route [1] is still using it now"</span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">$ </span><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"http://127.0.0.1:9180/apisix/admin/upstreams/1?force=true"</span><span class="token plain"> -H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X DELETE</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"deleted"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"1"</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"key"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"/apisix/upstreams/1"</span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="v3-new-feature"></a>V3 new feature<a class="hash-link" href="#v3-new-feature" title="Direct link to heading">#</a></h2><p>The Admin API has made some breaking changes in V3 version, as well as supporting additional features.</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="support-new-response-body-format"></a>Support new response body format<a class="hash-link" href="#support-new-response-body-format" title="Direct link to heading">#</a></h3><ol><li>Remove <code>action</code> field in response body;</li><li>Adjust the response body structure when fetching the list of resources, the new response body structure like:</li></ol><p>Return single resource:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 json"><pre tabindex="0" class="prism-code language-json codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"modifiedIndex"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">2685183</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"value"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"id"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"1"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> ...</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"key"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"/apisix/routes/1"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"createdIndex"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">2684956</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>Return multiple resources:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 json"><pre tabindex="0" class="prism-code language-json codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"list"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"modifiedIndex"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">2685183</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"value"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"id"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"1"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> ...</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"key"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"/apisix/routes/1"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"createdIndex"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">2684956</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"modifiedIndex"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">2685163</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"value"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"id"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"2"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> ...</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"key"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"/apisix/routes/2"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"createdIndex"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">2685163</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">]</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"total"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">2</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="support-paging-query"></a>Support paging query<a class="hash-link" href="#support-paging-query" title="Direct link to heading">#</a></h3><p>Paging query is supported when getting the resource list, paging parameters include:</p><table><thead><tr><th>parameter</th><th>Default</th><th>Valid range</th><th>Description</th></tr></thead><tbody><tr><td>page</td><td>1</td><td>[1, ...]</td><td>Number of pages.</td></tr><tr><td>page_size</td><td></td><td>[10, 500]</td><td>Number of resources per page.</td></tr></tbody></table><p>The example is as follows:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"http://127.0.0.1:9180/apisix/admin/routes?page=1&page_size=10"</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X GET</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 json"><pre tabindex="0" class="prism-code language-json codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"total"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"list"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> ...</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>Resources that support paging queries:</p><ul><li>Consumer</li><li>Consumer Group</li><li>Global Rules</li><li>Plugin Config</li><li>Proto</li><li>Route</li><li>Service</li><li>SSL</li><li>Stream Route</li><li>Upstream</li><li>Secret</li></ul><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="support-filtering-query"></a>Support filtering query<a class="hash-link" href="#support-filtering-query" title="Direct link to heading">#</a></h3><p>When getting a list of resources, it supports filtering resources based on <code>name</code>, <code>label</code>, <code>uri</code>.</p><table><thead><tr><th>parameter</th><th>parameter</th></tr></thead><tbody><tr><td>name</td><td>Query resource by their <code>name</code>, which will not appear in the query results if the resource itself does not have <code>name</code>.</td></tr><tr><td>label</td><td>Query resource by their <code>label</code>, which will not appear in the query results if the resource itself does not have <code>label</code>.</td></tr><tr><td>uri</td><td>Supported on Route resources only. If the <code>uri</code> of a Route is equal to the uri of the query or if the <code>uris</code> contains the uri of the query, the Route resource appears in the query results.</td></tr></tbody></table><div class="admonition admonition-tip alert alert--success"><div class="admonition-heading"><h5><span class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" width="12" height="16" viewBox="0 0 12 16"><path fill-rule="evenodd" d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"></path></svg></span>tip</h5></div><div class="admonition-content"><p>When multiple filter parameters are enabled, use the intersection of the query results for different filter parameters.</p></div></div><p>The following example will return a list of routes, and all routes in the list satisfy: the <code>name</code> of the route contains the string "test", the <code>uri</code> contains the string "foo", and there is no restriction on the <code>label</code> of the route, since the label of the query is the empty string.</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">'http://127.0.0.1:9180/apisix/admin/routes?name=test&uri=foo&label='</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X GET</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 json"><pre tabindex="0" class="prism-code language-json codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"total"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"list"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> ...</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="route"></a>Route<a class="hash-link" href="#route" title="Direct link to heading">#</a></h2><p><a href="/docs/apisix/3.12/terminology/route/">Routes</a> match the client's request based on defined rules, loads and executes the corresponding <a href="#plugin">plugins</a>, and forwards the request to the specified <a href="#upstream">Upstream</a>.</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="route-api"></a>Route API<a class="hash-link" href="#route-api" title="Direct link to heading">#</a></h3><p>Route resource request address: /apisix/admin/routes/{id}?ttl=0</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="quick-note-on-id-syntax"></a>Quick Note on ID Syntax<a class="hash-link" href="#quick-note-on-id-syntax" title="Direct link to heading">#</a></h3><p>ID's as a text string must be of a length between 1 and 64 characters and they should only contain uppercase, lowercase, numbers and no special characters apart from dashes ( - ), periods ( . ) and underscores ( _ ). For integer values they simply must have a minimum character count of 1.</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-methods"></a>Request Methods<a class="hash-link" href="#request-methods" title="Direct link to heading">#</a></h3><table><thead><tr><th>Method</th><th>Request URI</th><th>Request Body</th><th>Description</th></tr></thead><tbody><tr><td>GET</td><td>/apisix/admin/routes</td><td>NULL</td><td>Fetches a list of all configured Routes.</td></tr><tr><td>GET</td><td>/apisix/admin/routes/{id}</td><td>NULL</td><td>Fetches specified Route by id.</td></tr><tr><td>PUT</td><td>/apisix/admin/routes/{id}</td><td>{...}</td><td>Creates a Route with the specified id.</td></tr><tr><td>POST</td><td>/apisix/admin/routes</td><td>{...}</td><td>Creates a Route and assigns a random id.</td></tr><tr><td>DELETE</td><td>/apisix/admin/routes/{id}</td><td>NULL</td><td>Removes the Route with the specified id.</td></tr><tr><td>PATCH</td><td>/apisix/admin/routes/{id}</td><td>{...}</td><td>Updates the selected attributes of the specified, existing Route. To delete an attribute, set value of attribute set to null.</td></tr><tr><td>PATCH</td><td>/apisix/admin/routes/{id}/{path}</td><td>{...}</td><td>Updates the attribute specified in the path. The values of other attributes remain unchanged.</td></tr></tbody></table><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="uri-request-parameters"></a>URI Request Parameters<a class="hash-link" href="#uri-request-parameters" title="Direct link to heading">#</a></h3><table><thead><tr><th>parameter</th><th>Required</th><th>Type</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>ttl</td><td>False</td><td>Auxiliary</td><td>Request expires after the specified target seconds.</td><td>ttl=1</td></tr></tbody></table><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-body-parameters"></a>Request Body Parameters<a class="hash-link" href="#request-body-parameters" title="Direct link to heading">#</a></h3><table><thead><tr><th>Parameter</th><th>Required</th><th>Type</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>name</td><td>False</td><td>Auxiliary</td><td>Identifier for the Route.</td><td>route-xxxx</td></tr><tr><td>desc</td><td>False</td><td>Auxiliary</td><td>Description of usage scenarios.</td><td>route xxxx</td></tr><tr><td>uri</td><td>True, can't be used with <code>uris</code></td><td>Match Rules</td><td>Matches the uri. For more advanced matching see <a href="/docs/apisix/3.12/terminology/router/">Router</a>.</td><td>"/hello"</td></tr><tr><td>uris</td><td>True, can't be used with <code>uri</code></td><td>Match Rules</td><td>Matches with any one of the multiple <code>uri</code>s specified in the form of a non-empty list.</td><td>["/hello", "/word"]</td></tr><tr><td>host</td><td>False, can't be used with <code>hosts</code></td><td>Match Rules</td><td>Matches with domain names such as <code>foo.com</code> or PAN domain names like <code>*.foo.com</code>.</td><td>"foo.com"</td></tr><tr><td>hosts</td><td>False, can't be used with <code>host</code></td><td>Match Rules</td><td>Matches with any one of the multiple <code>host</code>s specified in the form of a non-empty list.</td><td>["foo.com", "*.bar.com"]</td></tr><tr><td>remote_addr</td><td>False, can't be used with <code>remote_addrs</code></td><td>Match Rules</td><td>Matches with the specified IP address in standard IPv4 format (<code>192.168.1.101</code>), CIDR format (<code>192.168.1.0/24</code>), or in IPv6 format (<code>::1</code>, <code>fe80::1</code>, <code>fe80::1/64</code>).</td><td>"192.168.1.0/24"</td></tr><tr><td>remote_addrs</td><td>False, can't be used with <code>remote_addr</code></td><td>Match Rules</td><td>Matches with any one of the multiple <code>remote_addr</code>s specified in the form of a non-empty list.</td><td>["127.0.0.1", "192.0.0.0/8", "::1"]</td></tr><tr><td>methods</td><td>False</td><td>Match Rules</td><td>Matches with the specified methods. Matches all methods if empty or unspecified.</td><td>["GET", "POST"]</td></tr><tr><td>priority</td><td>False</td><td>Match Rules</td><td>If different Routes matches to the same <code>uri</code>, then the Route is matched based on its <code>priority</code>. A higher value corresponds to higher priority. It is set to <code>0</code> by default.</td><td>priority = 10</td></tr><tr><td>vars</td><td>False</td><td>Match Rules</td><td>Matches based on the specified variables consistent with variables in Nginx. Takes the form <code>[[var, operator, val], [var, operator, val], ...]]</code>. Note that this is case sensitive when matching a cookie name. See <a href="https://github.com/api7/lua-resty-expr" target="_blank" rel="noopener noreferrer">lua-resty-expr</a> for more details.</td><td>[["arg_name", "==", "json"], ["arg_age", ">", 18]]</td></tr><tr><td>filter_func</td><td>False</td><td>Match Rules</td><td>Matches using a user-defined function in Lua. Used in scenarios where <code>vars</code> is not sufficient. Functions accept an argument <code>vars</code> which provides access to built-in variables (including Nginx variables).</td><td>function(vars) return tonumber(vars.arg_userid) % 4 > 2; end</td></tr><tr><td>plugins</td><td>False</td><td>Plugin</td><td>Plugins that are executed during the request/response cycle. See <a href="/docs/apisix/3.12/terminology/plugin/">Plugin</a> for more.</td><td></td></tr><tr><td>script</td><td>False</td><td>Script</td><td>Used for writing arbitrary Lua code or directly calling existing plugins to be executed. See <a href="/docs/apisix/3.12/terminology/script/">Script</a> for more.</td><td></td></tr><tr><td>upstream</td><td>False</td><td>Upstream</td><td>Configuration of the <a href="/docs/apisix/3.12/terminology/upstream/">Upstream</a>.</td><td></td></tr><tr><td>upstream_id</td><td>False</td><td>Upstream</td><td>Id of the <a href="/docs/apisix/3.12/terminology/upstream/">Upstream</a> service.</td><td></td></tr><tr><td>service_id</td><td>False</td><td>Service</td><td>Configuration of the bound <a href="/docs/apisix/3.12/terminology/service/">Service</a>.</td><td></td></tr><tr><td>plugin_config_id</td><td>False, can't be used with <code>script</code></td><td>Plugin</td><td><a href="/docs/apisix/3.12/terminology/plugin-config/">Plugin config</a> bound to the Route.</td><td></td></tr><tr><td>labels</td><td>False</td><td>Match Rules</td><td>Attributes of the Route specified as key-value pairs.</td><td>{"version":"v2","build":"16","env":"production"}</td></tr><tr><td>timeout</td><td>False</td><td>Auxiliary</td><td>Sets the timeout (in seconds) for connecting to, and sending and receiving messages between the Upstream and the Route. This will overwrite the <code>timeout</code> value configured in your <a href="#upstream">Upstream</a>.</td><td>{"connect": 3, "send": 3, "read": 3}</td></tr><tr><td>enable_websocket</td><td>False</td><td>Auxiliary</td><td>Enables a websocket. Set to <code>false</code> by default.</td><td></td></tr><tr><td>status</td><td>False</td><td>Auxiliary</td><td>Enables the current Route. Set to <code>1</code> (enabled) by default.</td><td><code>1</code> to enable, <code>0</code> to disable</td></tr></tbody></table><p>Example configuration:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"id"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"1"</span><span class="token plain">, </span><span class="token comment" style="color:#999988;font-style:italic"># id, unnecessary.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"uris"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"/a"</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"/b"</span><span class="token punctuation" style="color:#393A34">]</span><span class="token plain">, </span><span class="token comment" style="color:#999988;font-style:italic"># A set of uri.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"methods"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"GET"</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"POST"</span><span class="token punctuation" style="color:#393A34">]</span><span class="token plain">, </span><span class="token comment" style="color:#999988;font-style:italic"># Can fill multiple methods</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"hosts"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"a.com"</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"b.com"</span><span class="token punctuation" style="color:#393A34">]</span><span class="token plain">, </span><span class="token comment" style="color:#999988;font-style:italic"># A set of host.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"plugins"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain">, </span><span class="token comment" style="color:#999988;font-style:italic"># Bound plugin</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"priority"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">0</span><span class="token plain">, </span><span class="token comment" style="color:#999988;font-style:italic"># If different routes contain the same `uri`, determine which route is matched first based on the attribute` priority`, the default value is 0.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"name"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"route-xxx"</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"desc"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"hello world"</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"remote_addrs"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"127.0.0.1"</span><span class="token punctuation" style="color:#393A34">]</span><span class="token plain">, </span><span class="token comment" style="color:#999988;font-style:italic"># A set of Client IP.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"vars"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">[</span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"http_user"</span><span class="token plain">, </span><span class="token string" style="color:#e3116c">"=="</span><span class="token plain">, </span><span class="token string" style="color:#e3116c">"ios"</span><span class="token punctuation" style="color:#393A34">]</span><span class="token punctuation" style="color:#393A34">]</span><span class="token plain">, </span><span class="token comment" style="color:#999988;font-style:italic"># A list of one or more `[var, operator, val]` elements</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"upstream_id"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"1"</span><span class="token plain">, </span><span class="token comment" style="color:#999988;font-style:italic"># upstream id, recommended</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"upstream"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain">, </span><span class="token comment" style="color:#999988;font-style:italic"># upstream, not recommended</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"timeout"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"> </span><span class="token comment" style="color:#999988;font-style:italic"># Set the upstream timeout for connecting, sending and receiving messages of the route.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"connect"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">3</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"send"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">3</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"read"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">3</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"filter_func"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">""</span><span class="token plain"> </span><span class="token comment" style="color:#999988;font-style:italic"># User-defined filtering function</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="example-api-usage"></a>Example API usage<a class="hash-link" href="#example-api-usage" title="Direct link to heading">#</a></h3><ul><li><p>Create a route</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/routes/1 -H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PUT -i -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "uri": "/index.html",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "hosts": ["foo.com", "*.bar.com"],</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "remote_addrs": ["127.0.0.0/8"],</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "methods": ["PUT", "GET"],</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "enable_websocket": true,</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "upstream": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "type": "roundrobin",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "nodes": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "127.0.0.1:1980": 1</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">201</span><span class="token plain"> Created</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">Date: Sat, </span><span class="token number" style="color:#36acaa">31</span><span class="token plain"> Aug </span><span class="token number" style="color:#36acaa">2019</span><span class="token plain"> 01:17:15 GMT</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div></li><li><p>Create a route expires after 60 seconds, then it's deleted automatically</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">'http://127.0.0.1:9180/apisix/admin/routes/2?ttl=60'</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PUT -i -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "uri": "/aa/index.html",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "upstream": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "type": "roundrobin",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "nodes": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "127.0.0.1:1980": 1</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">201</span><span class="token plain"> Created</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">Date: Sat, </span><span class="token number" style="color:#36acaa">31</span><span class="token plain"> Aug </span><span class="token number" style="color:#36acaa">2019</span><span class="token plain"> 01:17:15 GMT</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div></li><li><p>Add an upstream node to the Route</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/routes/1 </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PATCH -i -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "upstream": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "nodes": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "127.0.0.1:1981": 1</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">200</span><span class="token plain"> OK</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p> After successful execution, upstream nodes will be updated to:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"127.0.0.1:1980"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"127.0.0.1:1981"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div></li><li><p>Update the weight of an upstream node to the Route</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/routes/1 </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PATCH -i -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "upstream": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "nodes": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "127.0.0.1:1981": 10</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">200</span><span class="token plain"> OK</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p> After successful execution, upstream nodes will be updated to:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"127.0.0.1:1980"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"127.0.0.1:1981"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">10</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div></li><li><p>Delete an upstream node for the Route</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/routes/1 </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PATCH -i -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "upstream": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "nodes": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "127.0.0.1:1980": null</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">200</span><span class="token plain"> OK</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p> After successful execution, upstream nodes will be updated to:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"127.0.0.1:1981"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">10</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div></li><li><p>Replace methods of the Route -- array</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/routes/1 </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PATCH -i -d </span><span class="token string" style="color:#e3116c">'{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "methods": ["GET", "POST"]</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">200</span><span class="token plain"> OK</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p> After successful execution, methods will not retain the original data, and the entire update is:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"GET"</span><span class="token plain">, </span><span class="token string" style="color:#e3116c">"POST"</span><span class="token punctuation" style="color:#393A34">]</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div></li><li><p>Replace upstream nodes of the Route -- sub path</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/routes/1/upstream/nodes </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PATCH -i -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "127.0.0.1:1982": 1</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">200</span><span class="token plain"> OK</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p> After successful execution, nodes will not retain the original data, and the entire update is:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"127.0.0.1:1982"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div></li><li><p>Replace methods of the Route -- sub path</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/routes/1/methods </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PATCH -i -d</span><span class="token string" style="color:#e3116c">'["POST", "DELETE", " PATCH"]'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">200</span><span class="token plain"> OK</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p> After successful execution, methods will not retain the original data, and the entire update is:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"POST"</span><span class="token plain">, </span><span class="token string" style="color:#e3116c">"DELETE"</span><span class="token plain">, </span><span class="token string" style="color:#e3116c">"PATCH"</span><span class="token punctuation" style="color:#393A34">]</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div></li><li><p>Disable route</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/routes/1 </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PATCH -i -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "status": 0</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">200</span><span class="token plain"> OK</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p> After successful execution, status nodes will be updated to:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"status"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">0</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div></li><li><p>Enable route</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/routes/1 </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PATCH -i -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "status": 1</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">200</span><span class="token plain"> OK</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p> After successful execution, status nodes will be updated to:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"status"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div></li></ul><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="response-parameters"></a>Response Parameters<a class="hash-link" href="#response-parameters" title="Direct link to heading">#</a></h3><p>Currently, the response is returned from etcd.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="service"></a>Service<a class="hash-link" href="#service" title="Direct link to heading">#</a></h2><p>A Service is an abstraction of an API (which can also be understood as a set of Route abstractions). It usually corresponds to an upstream service abstraction.</p><p>The relationship between Routes and a Service is usually N:1.</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="service-api"></a>Service API<a class="hash-link" href="#service-api" title="Direct link to heading">#</a></h3><p>Service resource request address: /apisix/admin/services/{id}</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-methods-1"></a>Request Methods<a class="hash-link" href="#request-methods-1" title="Direct link to heading">#</a></h3><table><thead><tr><th>Method</th><th>Request URI</th><th>Request Body</th><th>Description</th></tr></thead><tbody><tr><td>GET</td><td>/apisix/admin/services</td><td>NULL</td><td>Fetches a list of available Services.</td></tr><tr><td>GET</td><td>/apisix/admin/services/{id}</td><td>NULL</td><td>Fetches specified Service by id.</td></tr><tr><td>PUT</td><td>/apisix/admin/services/{id}</td><td>{...}</td><td>Creates a Service with the specified id.</td></tr><tr><td>POST</td><td>/apisix/admin/services</td><td>{...}</td><td>Creates a Service and assigns a random id.</td></tr><tr><td>DELETE</td><td>/apisix/admin/services/{id}</td><td>NULL</td><td>Removes the Service with the specified id.</td></tr><tr><td>PATCH</td><td>/apisix/admin/services/{id}</td><td>{...}</td><td>Updates the selected attributes of the specified, existing Service. To delete an attribute, set value of attribute set to null.</td></tr><tr><td>PATCH</td><td>/apisix/admin/services/{id}/{path}</td><td>{...}</td><td>Updates the attribute specified in the path. The values of other attributes remain unchanged.</td></tr></tbody></table><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-body-parameters-1"></a>Request Body Parameters<a class="hash-link" href="#request-body-parameters-1" title="Direct link to heading">#</a></h3><table><thead><tr><th>Parameter</th><th>Required</th><th>Type</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>plugins</td><td>False</td><td>Plugin</td><td>Plugins that are executed during the request/response cycle. See <a href="/docs/apisix/3.12/terminology/plugin/">Plugin</a> for more.</td><td></td></tr><tr><td>upstream</td><td>False</td><td>Upstream</td><td>Configuration of the <a href="/docs/apisix/3.12/terminology/upstream/">Upstream</a>.</td><td></td></tr><tr><td>upstream_id</td><td>False</td><td>Upstream</td><td>Id of the <a href="/docs/apisix/3.12/terminology/upstream/">Upstream</a> service.</td><td></td></tr><tr><td>name</td><td>False</td><td>Auxiliary</td><td>Identifier for the Service.</td><td>service-xxxx</td></tr><tr><td>desc</td><td>False</td><td>Auxiliary</td><td>Description of usage scenarios.</td><td>service xxxx</td></tr><tr><td>labels</td><td>False</td><td>Match Rules</td><td>Attributes of the Service specified as key-value pairs.</td><td>{"version":"v2","build":"16","env":"production"}</td></tr><tr><td>enable_websocket</td><td>False</td><td>Auxiliary</td><td>Enables a websocket. Set to <code>false</code> by default.</td><td></td></tr><tr><td>hosts</td><td>False</td><td>Match Rules</td><td>Matches with any one of the multiple <code>host</code>s specified in the form of a non-empty list.</td><td>["foo.com", "*.bar.com"]</td></tr></tbody></table><p>Example configuration:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"id"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"1"</span><span class="token plain">, </span><span class="token comment" style="color:#999988;font-style:italic"># id</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"plugins"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain">, </span><span class="token comment" style="color:#999988;font-style:italic"># Bound plugin</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"upstream_id"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"1"</span><span class="token plain">, </span><span class="token comment" style="color:#999988;font-style:italic"># upstream id, recommended</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"upstream"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain">, </span><span class="token comment" style="color:#999988;font-style:italic"># upstream, not recommended</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"name"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"service-test"</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"desc"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"hello world"</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"enable_websocket"</span><span class="token builtin class-name">:</span><span class="token plain"> true,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"hosts"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"foo.com"</span><span class="token punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="example-api-usage-1"></a>Example API usage<a class="hash-link" href="#example-api-usage-1" title="Direct link to heading">#</a></h3><ul><li><p>Create a service</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/services/201 </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PUT -i -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "plugins": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "limit-count": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "count": 2,</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "time_window": 60,</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "rejected_code": 503,</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "key": "remote_addr"</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> },</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "enable_websocket": true,</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "upstream": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "type": "roundrobin",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "nodes": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "127.0.0.1:1980": 1</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">201</span><span class="token plain"> Created</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div></li><li><p>Add an upstream node to the Service</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/services/201 </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PATCH -i -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "upstream": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "nodes": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "127.0.0.1:1981": 1</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">200</span><span class="token plain"> OK</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p> After successful execution, upstream nodes will be updated to:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"127.0.0.1:1980"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"127.0.0.1:1981"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div></li><li><p>Update the weight of an upstream node to the Service</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/services/201 </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H</span><span class="token string" style="color:#e3116c">'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'</span><span class="token plain"> -X PATCH -i -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "upstream": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "nodes": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "127.0.0.1:1981": 10</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">200</span><span class="token plain"> OK</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p> After successful execution, upstream nodes will be updated to:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"127.0.0.1:1980"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"127.0.0.1:1981"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">10</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div></li><li><p>Delete an upstream node for the Service</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/services/201 </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H</span><span class="token string" style="color:#e3116c">'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'</span><span class="token plain"> -X PATCH -i -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "upstream": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "nodes": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "127.0.0.1:1980": null</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">200</span><span class="token plain"> OK</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p> After successful execution, upstream nodes will be updated to:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"127.0.0.1:1981"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">10</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div></li><li><p>Replace upstream nodes of the Service</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/services/201/upstream/nodes </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H</span><span class="token string" style="color:#e3116c">'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'</span><span class="token plain"> -X PATCH -i -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "127.0.0.1:1982": 1</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">200</span><span class="token plain"> OK</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p> After successful execution, upstream nodes will not retain the original data, and the entire update is:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"127.0.0.1:1982"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div></li></ul><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="response-parameters-1"></a>Response Parameters<a class="hash-link" href="#response-parameters-1" title="Direct link to heading">#</a></h3><p>Currently, the response is returned from etcd.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="consumer"></a>Consumer<a class="hash-link" href="#consumer" title="Direct link to heading">#</a></h2><p>Consumers are users of services and can only be used in conjunction with a user authentication system. A Consumer is identified by a <code>username</code> property. So, for creating a new Consumer, only the HTTP <code>PUT</code> method is supported.</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="consumer-api"></a>Consumer API<a class="hash-link" href="#consumer-api" title="Direct link to heading">#</a></h3><p>Consumer resource request address: /apisix/admin/consumers/{username}</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-methods-2"></a>Request Methods<a class="hash-link" href="#request-methods-2" title="Direct link to heading">#</a></h3><table><thead><tr><th>Method</th><th>Request URI</th><th>Request Body</th><th>Description</th></tr></thead><tbody><tr><td>GET</td><td>/apisix/admin/consumers</td><td>NULL</td><td>Fetches a list of all Consumers.</td></tr><tr><td>GET</td><td>/apisix/admin/consumers/{username}</td><td>NULL</td><td>Fetches specified Consumer by username.</td></tr><tr><td>PUT</td><td>/apisix/admin/consumers</td><td>{...}</td><td>Create new Consumer.</td></tr><tr><td>DELETE</td><td>/apisix/admin/consumers/{username}</td><td>NULL</td><td>Removes the Consumer with the specified username.</td></tr></tbody></table><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-body-parameters-2"></a>Request Body Parameters<a class="hash-link" href="#request-body-parameters-2" title="Direct link to heading">#</a></h3><table><thead><tr><th>Parameter</th><th>Required</th><th>Type</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>username</td><td>True</td><td>Name</td><td>Name of the Consumer.</td><td></td></tr><tr><td>group_id</td><td>False</td><td>Name</td><td>Group of the Consumer.</td><td></td></tr><tr><td>plugins</td><td>False</td><td>Plugin</td><td>Plugins that are executed during the request/response cycle. See <a href="/docs/apisix/3.12/terminology/plugin/">Plugin</a> for more.</td><td></td></tr><tr><td>desc</td><td>False</td><td>Auxiliary</td><td>Description of usage scenarios.</td><td>customer xxxx</td></tr><tr><td>labels</td><td>False</td><td>Match Rules</td><td>Attributes of the Consumer specified as key-value pairs.</td><td>{"version":"v2","build":"16","env":"production"}</td></tr></tbody></table><p>Example Configuration:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"plugins"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain">, </span><span class="token comment" style="color:#999988;font-style:italic"># Bound plugin</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"username"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"name"</span><span class="token plain">, </span><span class="token comment" style="color:#999988;font-style:italic"># Consumer name</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"desc"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"hello world"</span><span class="token plain"> </span><span class="token comment" style="color:#999988;font-style:italic"># Consumer desc</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>When bound to a Route or Service, the Authentication Plugin infers the Consumer from the request and does not require any parameters. Whereas, when it is bound to a Consumer, username, password and other information needs to be provided.</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="example-api-usage-2"></a>Example API usage<a class="hash-link" href="#example-api-usage-2" title="Direct link to heading">#</a></h3><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/consumers </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PUT -i -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "username": "jack",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "plugins": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "key-auth": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "key": "auth-one"</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> },</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "limit-count": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "count": 2,</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "time_window": 60,</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "rejected_code": 503,</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "key": "remote_addr"</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">200</span><span class="token plain"> OK</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">Date: Thu, </span><span class="token number" style="color:#36acaa">26</span><span class="token plain"> Dec </span><span class="token number" style="color:#36acaa">2019</span><span class="token plain"> 08:17:49 GMT</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"node"</span><span class="token plain">:</span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"value"</span><span class="token plain">:</span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"username"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"jack"</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"plugins"</span><span class="token plain">:</span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"key-auth"</span><span class="token plain">:</span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"key"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"auth-one"</span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"limit-count"</span><span class="token plain">:</span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"time_window"</span><span class="token plain">:60,</span><span class="token string" style="color:#e3116c">"count"</span><span class="token plain">:2,</span><span class="token string" style="color:#e3116c">"rejected_code"</span><span class="token plain">:503,</span><span class="token string" style="color:#e3116c">"key"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"remote_addr"</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"policy"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"local"</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"createdIndex"</span><span class="token plain">:64,</span><span class="token string" style="color:#e3116c">"key"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"\/apisix\/consumers\/jack"</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"modifiedIndex"</span><span class="token plain">:64</span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"prevNode"</span><span class="token plain">:</span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"value"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"{</span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c">username</span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c">:</span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c">jack</span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c">,</span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c">plugins</span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c">:{</span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c">key-auth</span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c">:{</span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c">key</span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c">:</span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c">auth-one</span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c">},</span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c">limit-count</span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c">:{</span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c">time_window</span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c">:60,</span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c">count</span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c">:2,</span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c">rejected_code</span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c">:503,</span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c">key</span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c">:</span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c">remote_addr</span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c">,</span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c">policy</span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c">:</span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c">local</span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c">}}}"</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"createdIndex"</span><span class="token plain">:63,</span><span class="token string" style="color:#e3116c">"key"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"\/apisix\/consumers\/jack"</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"modifiedIndex"</span><span class="token plain">:63</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>Since <code>v2.2</code>, we can bind multiple authentication plugins to the same consumer.</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="response-parameters-2"></a>Response Parameters<a class="hash-link" href="#response-parameters-2" title="Direct link to heading">#</a></h3><p>Currently, the response is returned from etcd.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="credential"></a>Credential<a class="hash-link" href="#credential" title="Direct link to heading">#</a></h2><p>Credential is used to hold the authentication credentials for the Consumer. |
| Credentials are used when multiple credentials need to be configured for a Consumer.</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="credential-api"></a>Credential API<a class="hash-link" href="#credential-api" title="Direct link to heading">#</a></h3><p>Credential resource request address：/apisix/admin/consumers/{username}/credentials/{credential_id}</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-methods-3"></a>Request Methods<a class="hash-link" href="#request-methods-3" title="Direct link to heading">#</a></h3><table><thead><tr><th>Method</th><th>Request URI</th><th>Request Body</th><th>Description</th></tr></thead><tbody><tr><td>GET</td><td>/apisix/admin/consumers/{username}/credentials</td><td>NUll</td><td>Fetches list of all credentials of the Consumer</td></tr><tr><td>GET</td><td>/apisix/admin/consumers/{username}/credentials/{credential_id}</td><td>NUll</td><td>Fetches the Credential by <code>credential_id</code></td></tr><tr><td>PUT</td><td>/apisix/admin/consumers/{username}/credentials/{credential_id}</td><td>{...}</td><td>Create or update a Creddential</td></tr><tr><td>DELETE</td><td>/apisix/admin/consumers/{username}/credentials/{credential_id}</td><td>NUll</td><td>Delete the Credential</td></tr></tbody></table><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-body-parameters-3"></a>Request Body Parameters<a class="hash-link" href="#request-body-parameters-3" title="Direct link to heading">#</a></h3><table><thead><tr><th>Parameter</th><th>Required</th><th>Type</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>plugins</td><td>False</td><td>Plugin</td><td>Auth plugins configuration.</td><td></td></tr><tr><td>desc</td><td>False</td><td>Auxiliary</td><td>Description of usage scenarios.</td><td>credential xxxx</td></tr><tr><td>labels</td><td>False</td><td>Match Rules</td><td>Attributes of the Credential specified as key-value pairs.</td><td>{"version":"v2","build":"16","env":"production"}</td></tr></tbody></table><p>Example Configuration:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"plugins"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"key-auth"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"key"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"auth-one"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"desc"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"hello world"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="example-api-usage-3"></a>Example API usage<a class="hash-link" href="#example-api-usage-3" title="Direct link to heading">#</a></h3><p>Prerequisite: Consumer <code>jack</code> has been created.</p><p>Create the <code>key-auth</code> Credential for consumer <code>jack</code>:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials/auth-one </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PUT -i -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "plugins": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "key-auth": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "key": "auth-one"</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 bash"><pre tabindex="0" class="prism-code language-bash codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">200</span><span class="token plain"> OK</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">Date: Thu, </span><span class="token number" style="color:#36acaa">26</span><span class="token plain"> Dec </span><span class="token number" style="color:#36acaa">2019</span><span class="token plain"> 08:17:49 GMT</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"key"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"\/apisix\/consumers\/jack\/credentials\/auth-one"</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"value"</span><span class="token plain">:</span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"update_time"</span><span class="token plain">:1666260780,</span><span class="token string" style="color:#e3116c">"plugins"</span><span class="token plain">:</span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"key-auth"</span><span class="token plain">:</span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"key"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"auth-one"</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"create_time"</span><span class="token plain">:1666260780</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="upstream"></a>Upstream<a class="hash-link" href="#upstream" title="Direct link to heading">#</a></h2><p>Upstream is a virtual host abstraction that performs load balancing on a given set of service nodes according to the configured rules.</p><p>An Upstream configuration can be directly bound to a Route or a Service, but the configuration in Route has a higher priority. This behavior is consistent with priority followed by the Plugin object.</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="upstream-api"></a>Upstream API<a class="hash-link" href="#upstream-api" title="Direct link to heading">#</a></h3><p>Upstream resource request address: /apisix/admin/upstreams/{id}</p><p>For notes on ID syntax please refer to: <a href="#quick-note-on-id-syntax">ID Syntax</a></p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-methods-4"></a>Request Methods<a class="hash-link" href="#request-methods-4" title="Direct link to heading">#</a></h3><table><thead><tr><th>Method</th><th>Request URI</th><th>Request Body</th><th>Description</th></tr></thead><tbody><tr><td>GET</td><td>/apisix/admin/upstreams</td><td>NULL</td><td>Fetch a list of all configured Upstreams.</td></tr><tr><td>GET</td><td>/apisix/admin/upstreams/{id}</td><td>NULL</td><td>Fetches specified Upstream by id.</td></tr><tr><td>PUT</td><td>/apisix/admin/upstreams/{id}</td><td>{...}</td><td>Creates an Upstream with the specified id.</td></tr><tr><td>POST</td><td>/apisix/admin/upstreams</td><td>{...}</td><td>Creates an Upstream and assigns a random id.</td></tr><tr><td>DELETE</td><td>/apisix/admin/upstreams/{id}</td><td>NULL</td><td>Removes the Upstream with the specified id.</td></tr><tr><td>PATCH</td><td>/apisix/admin/upstreams/{id}</td><td>{...}</td><td>Updates the selected attributes of the specified, existing Upstream. To delete an attribute, set value of attribute set to null.</td></tr><tr><td>PATCH</td><td>/apisix/admin/upstreams/{id}/{path}</td><td>{...}</td><td>Updates the attribute specified in the path. The values of other attributes remain unchanged.</td></tr></tbody></table><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-body-parameters-4"></a>Request Body Parameters<a class="hash-link" href="#request-body-parameters-4" title="Direct link to heading">#</a></h3><p>In addition to the equalization algorithm selections, Upstream also supports passive health check and retry for the upstream. See the table below for more details:</p><table><thead><tr><th>Parameter</th><th>Required</th><th>Type</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>type</td><td>False</td><td>Enumeration</td><td>Load balancing algorithm to be used, and the default value is <code>roundrobin</code>.</td><td></td></tr><tr><td>nodes</td><td>True, can't be used with <code>service_name</code></td><td>Node</td><td>IP addresses (with optional ports) of the Upstream nodes represented as a hash table or an array. In the hash table, the key is the IP address and the value is the weight of the node for the load balancing algorithm. For hash table case, if the key is IPv6 address with port, then the IPv6 address must be quoted with square brackets. In the array, each item is a hash table with keys <code>host</code>, <code>weight</code>, and the optional <code>port</code> and <code>priority</code> (defaults to <code>0</code>). Nodes with lower priority are used only when all nodes with a higher priority are tried and are unavailable. Empty nodes are treated as placeholders and clients trying to access this Upstream will receive a 502 response.</td><td><code>192.168.1.100:80</code>, <code>[::1]:80</code></td></tr><tr><td>service_name</td><td>True, can't be used with <code>nodes</code></td><td>String</td><td>Service name used for <a href="/docs/apisix/3.12/discovery/">service discovery</a>.</td><td><code>a-bootiful-client</code></td></tr><tr><td>discovery_type</td><td>True, if <code>service_name</code> is used</td><td>String</td><td>The type of service <a href="/docs/apisix/3.12/discovery/">discovery</a>.</td><td><code>eureka</code></td></tr><tr><td>hash_on</td><td>False</td><td>Auxiliary</td><td>Only valid if the <code>type</code> is <code>chash</code>. Supports Nginx variables (<code>vars</code>), custom headers (<code>header</code>), <code>cookie</code> and <code>consumer</code>. Defaults to <code>vars</code>.</td><td></td></tr><tr><td>key</td><td>False</td><td>Match Rules</td><td>Only valid if the <code>type</code> is <code>chash</code>. Finds the corresponding node <code>id</code> according to <code>hash_on</code> and <code>key</code> values. When <code>hash_on</code> is set to <code>vars</code>, <code>key</code> is a required parameter and it supports <a href="http://nginx.org/en/docs/varindex.html" target="_blank" rel="noopener noreferrer">Nginx variables</a>. When <code>hash_on</code> is set as <code>header</code>, <code>key</code> is a required parameter, and <code>header name</code> can be customized. When <code>hash_on</code> is set to <code>cookie</code>, <code>key</code> is also a required parameter, and <code>cookie name</code> can be customized. When <code>hash_on</code> is set to <code>consumer</code>, <code>key</code> need not be set and the <code>key</code> used by the hash algorithm would be the authenticated <code>consumer_name</code>.</td><td><code>uri</code>, <code>server_name</code>, <code>server_addr</code>, <code>request_uri</code>, <code>remote_port</code>, <code>remote_addr</code>, <code>query_string</code>, <code>host</code>, <code>hostname</code>, <code>arg_***</code>, <code>arg_***</code></td></tr><tr><td>checks</td><td>False</td><td>Health Checker</td><td>Configures the parameters for the <a href="/docs/apisix/3.12/tutorials/health-check/">health check</a>.</td><td></td></tr><tr><td>retries</td><td>False</td><td>Integer</td><td>Sets the number of retries while passing the request to Upstream using the underlying Nginx mechanism. Set according to the number of available backend nodes by default. Setting this to <code>0</code> disables retry.</td><td></td></tr><tr><td>retry_timeout</td><td>False</td><td>Integer</td><td>Timeout to continue with retries. Setting this to <code>0</code> disables the retry timeout.</td><td></td></tr><tr><td>timeout</td><td>False</td><td>Timeout</td><td>Sets the timeout (in seconds) for connecting to, and sending and receiving messages to and from the Upstream.</td><td><code>{"connect": 0.5,"send": 0.5,"read": 0.5}</code></td></tr><tr><td>name</td><td>False</td><td>Auxiliary</td><td>Identifier for the Upstream.</td><td></td></tr><tr><td>desc</td><td>False</td><td>Auxiliary</td><td>Description of usage scenarios.</td><td></td></tr><tr><td>pass_host</td><td>False</td><td>Enumeration</td><td>Configures the <code>host</code> when the request is forwarded to the upstream. Can be one of <code>pass</code>, <code>node</code> or <code>rewrite</code>. Defaults to <code>pass</code> if not specified. <code>pass</code>- transparently passes the client's host to the Upstream. <code>node</code>- uses the host configured in the node of the Upstream. <code>rewrite</code>- Uses the value configured in <code>upstream_host</code>.</td><td></td></tr><tr><td>upstream_host</td><td>False</td><td>Auxiliary</td><td>Specifies the host of the Upstream request. This is only valid if the <code>pass_host</code> is set to <code>rewrite</code>.</td><td></td></tr><tr><td>scheme</td><td>False</td><td>Auxiliary</td><td>The scheme used when communicating with the Upstream. For an L7 proxy, this value can be one of <code>http</code>, <code>https</code>, <code>grpc</code>, <code>grpcs</code>. For an L4 proxy, this value could be one of <code>tcp</code>, <code>udp</code>, <code>tls</code>. Defaults to <code>http</code>.</td><td></td></tr><tr><td>labels</td><td>False</td><td>Match Rules</td><td>Attributes of the Upstream specified as <code>key-value</code> pairs.</td><td>{"version":"v2","build":"16","env":"production"}</td></tr><tr><td>tls.client_cert</td><td>False, can't be used with <code>tls.client_cert_id</code></td><td>HTTPS certificate</td><td>Sets the client certificate while connecting to a TLS Upstream.</td><td></td></tr><tr><td>tls.client_key</td><td>False, can't be used with <code>tls.client_cert_id</code></td><td>HTTPS certificate private key</td><td>Sets the client private key while connecting to a TLS Upstream.</td><td></td></tr><tr><td>tls.client_cert_id</td><td>False, can't be used with <code>tls.client_cert</code> and <code>tls.client_key</code></td><td>SSL</td><td>Set the referenced <a href="#ssl">SSL</a> id.</td><td></td></tr><tr><td>keepalive_pool.size</td><td>False</td><td>Auxiliary</td><td>Sets <code>keepalive</code> directive dynamically.</td><td></td></tr><tr><td>keepalive_pool.idle_timeout</td><td>False</td><td>Auxiliary</td><td>Sets <code>keepalive_timeout</code> directive dynamically.</td><td></td></tr><tr><td>keepalive_pool.requests</td><td>False</td><td>Auxiliary</td><td>Sets <code>keepalive_requests</code> directive dynamically.</td><td></td></tr></tbody></table><p>An Upstream can be one of the following <code>types</code>:</p><ul><li><code>roundrobin</code>: Round robin balancing with weights.</li><li><code>chash</code>: Consistent hash.</li><li><code>ewma</code>: Pick the node with minimum latency. See <a href="https://en.wikipedia.org/wiki/EWMA_chart" target="_blank" rel="noopener noreferrer">EWMA Chart</a> for more details.</li><li><code>least_conn</code>: Picks the node with the lowest value of <code>(active_conn + 1) / weight</code>. Here, an active connection is a connection being used by the request and is similar to the concept in Nginx.</li><li>user-defined load balancer loaded via <code>require("apisix.balancer.your_balancer")</code>.</li></ul><p>The following should be considered when setting the <code>hash_on</code> value:</p><ul><li>When set to <code>vars</code>, a <code>key</code> is required. The value of the key can be any of the <a href="http://nginx.org/en/docs/varindex.html" target="_blank" rel="noopener noreferrer">Nginx variables</a> without the <code>$</code> prefix.</li><li>When set to <code>header</code>, a <code>key</code> is required. This is equal to "http_<code>key</code>".</li><li>When set to <code>cookie</code>, a <code>key</code> is required. This key is equal to "cookie_<code>key</code>". The cookie name is case-sensitive.</li><li>When set to <code>consumer</code>, the <code>key</code> is optional and the key is set to the <code>consumer_name</code> captured from the authentication Plugin.</li><li>When set to <code>vars_combinations</code>, the <code>key</code> is required. The value of the key can be a combination of any of the <a href="http://nginx.org/en/docs/varindex.html" target="_blank" rel="noopener noreferrer">Nginx variables</a> like <code>$request_uri$remote_addr</code>.</li></ul><p>The features described below requires APISIX to be run on <a href="/docs/apisix/3.12/FAQ/#how-do-i-build-the-apisix-runtime-environment">APISIX-Runtime</a>:</p><p>You can set the <code>scheme</code> to <code>tls</code>, which means "TLS over TCP".</p><p>To use mTLS to communicate with Upstream, you can use the <code>tls.client_cert/key</code> in the same format as SSL's <code>cert</code> and <code>key</code> fields.</p><p>Or you can reference SSL object by <code>tls.client_cert_id</code> to set SSL cert and key. The SSL object can be referenced only if the <code>type</code> field is <code>client</code>, otherwise the request will be rejected by APISIX. In addition, only <code>cert</code> and <code>key</code> will be used in the SSL object.</p><p>To allow Upstream to have a separate connection pool, use <code>keepalive_pool</code>. It can be configured by modifying its child fields.</p><p>Example Configuration:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"id"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"1"</span><span class="token plain">, </span><span class="token comment" style="color:#999988;font-style:italic"># id</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"retries"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1</span><span class="token plain">, </span><span class="token comment" style="color:#999988;font-style:italic"># retry times</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"timeout"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"> </span><span class="token comment" style="color:#999988;font-style:italic"># Set the timeout for connecting, sending and receiving messages, each is 15 seconds.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"connect"</span><span class="token plain">:15,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"send"</span><span class="token plain">:15,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"read"</span><span class="token plain">:15</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"nodes"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"host:80"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">100</span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain">, </span><span class="token comment" style="color:#999988;font-style:italic"># Upstream machine address list, the format is `Address + Port`</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token comment" style="color:#999988;font-style:italic"># is the same as "nodes": [ {"host": "host", "port": 80, "weight": 100} ],</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"type"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"roundrobin"</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"checks"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain">, </span><span class="token comment" style="color:#999988;font-style:italic"># Health check parameters</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"hash_on"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">""</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"key"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">""</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"name"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"upstream-for-test"</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"desc"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"hello world"</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"scheme"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"http"</span><span class="token plain"> </span><span class="token comment" style="color:#999988;font-style:italic"># The scheme used when communicating with upstream, the default is `http`</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="example-api-usage-4"></a>Example API usage<a class="hash-link" href="#example-api-usage-4" title="Direct link to heading">#</a></h3><h4><a aria-hidden="true" tabindex="-1" class="anchor anchor__h4 anchorWithHideOnScrollNavbar_3ly5" id="create-an-upstream-and-modify-the-data-in-nodes"></a>Create an Upstream and modify the data in <code>nodes</code><a class="hash-link" href="#create-an-upstream-and-modify-the-data-in-nodes" title="Direct link to heading">#</a></h4><ol><li><p>Create upstream</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/upstreams/100 </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -i -X PUT -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "type":"roundrobin",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "nodes":{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "127.0.0.1:1980": 1</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">201</span><span class="token plain"> Created</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div></li><li><p>Add a node to the Upstream</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/upstreams/100 </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PATCH -i -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "nodes": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "127.0.0.1:1981": 1</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 bash"><pre tabindex="0" class="prism-code language-bash codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">200</span><span class="token plain"> OK</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>After successful execution, nodes will be updated to:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"127.0.0.1:1980"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"127.0.0.1:1981"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div></li><li><p>Update the weight of a node to the Upstream</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/upstreams/100 </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H</span><span class="token string" style="color:#e3116c">'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'</span><span class="token plain"> -X PATCH -i -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "nodes": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "127.0.0.1:1981": 10</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">200</span><span class="token plain"> OK</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>After successful execution, nodes will be updated to:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"127.0.0.1:1980"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"127.0.0.1:1981"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">10</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div></li><li><p>Delete a node for the Upstream</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/upstreams/100 </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PATCH -i -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "nodes": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "127.0.0.1:1980": null</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 bash"><pre tabindex="0" class="prism-code language-bash codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">200</span><span class="token plain"> OK</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>After successful execution, nodes will be updated to:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"127.0.0.1:1981"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">10</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div></li><li><p>Replace the nodes of the Upstream</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/upstreams/100/nodes </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PATCH -i -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "127.0.0.1:1982": 1</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 bash"><pre tabindex="0" class="prism-code language-bash codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">200</span><span class="token plain"> OK</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>After the execution is successful, nodes will not retain the original data, and the entire update is:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"127.0.0.1:1982"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div></li></ol><h4><a aria-hidden="true" tabindex="-1" class="anchor anchor__h4 anchorWithHideOnScrollNavbar_3ly5" id="proxy-client-request-to-https-upstream-service"></a>Proxy client request to <code>https</code> Upstream service<a class="hash-link" href="#proxy-client-request-to-https-upstream-service" title="Direct link to heading">#</a></h4><ol><li><p>Create a route and configure the upstream scheme as <code>https</code>.</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> -i http://127.0.0.1:9180/apisix/admin/routes/1 </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PUT -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "uri": "/get",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "upstream": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "type": "roundrobin",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "scheme": "https",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "nodes": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "httpbin.org:443": 1</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>After successful execution, the scheme when requesting to communicate with the upstream will be <code>https</code>.</p></li><li><p>Send a request to test.</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9080/get</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token string" style="color:#e3116c">"args"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token string" style="color:#e3116c">"headers"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"Accept"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"*/*"</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"Host"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"127.0.0.1"</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"User-Agent"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"curl/7.29.0"</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"X-Amzn-Trace-Id"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"Root=1-6058324a-0e898a7f04a5e95b526bb183"</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"X-Forwarded-Host"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"127.0.0.1"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token string" style="color:#e3116c">"origin"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"127.0.0.1"</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token string" style="color:#e3116c">"url"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"https://127.0.0.1/get"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div></li></ol><p>The request is successful, meaning that the proxy Upstream <code>https</code> is valid.</p><div class="admonition admonition-note alert alert--secondary"><div class="admonition-heading"><h5><span class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" width="14" height="16" viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</h5></div><div class="admonition-content"><p>Each node can be configured with a priority. A node with low priority will only be |
| used when all the nodes with higher priority have been tried or are unavailable.</p></div></div><p>As the default priority is 0, nodes with negative priority can be configured as a backup.</p><p>For example:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 json"><pre tabindex="0" class="prism-code language-json codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"uri"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"/hello"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"upstream"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"type"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"roundrobin"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"nodes"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"> </span><span class="token property" style="color:#36acaa">"host"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"127.0.0.1"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token property" style="color:#36acaa">"port"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1980</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token property" style="color:#36acaa">"weight"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">2000</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"> </span><span class="token property" style="color:#36acaa">"host"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"127.0.0.1"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token property" style="color:#36acaa">"port"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1981</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token property" style="color:#36acaa">"weight"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token property" style="color:#36acaa">"priority"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">-1</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">]</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"checks"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"active"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"http_path"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"/status"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"healthy"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"interval"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"successes"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"unhealthy"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"interval"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"http_failures"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>Node <code>127.0.0.2</code> will be used only after <code>127.0.0.1</code> is tried or unavailable. |
| It can therefore act as a backup for the node <code>127.0.0.1</code>.</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="response-parameters-3"></a>Response Parameters<a class="hash-link" href="#response-parameters-3" title="Direct link to heading">#</a></h3><p>Currently, the response is returned from etcd.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="ssl"></a>SSL<a class="hash-link" href="#ssl" title="Direct link to heading">#</a></h2><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="ssl-api"></a>SSL API<a class="hash-link" href="#ssl-api" title="Direct link to heading">#</a></h3><p>SSL resource request address: /apisix/admin/ssls/{id}</p><p>For notes on ID syntax please refer to: <a href="#quick-note-on-id-syntax">ID Syntax</a></p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-methods-5"></a>Request Methods<a class="hash-link" href="#request-methods-5" title="Direct link to heading">#</a></h3><table><thead><tr><th>Method</th><th>Request URI</th><th>Request Body</th><th>Description</th></tr></thead><tbody><tr><td>GET</td><td>/apisix/admin/ssls</td><td>NULL</td><td>Fetches a list of all configured SSL resources.</td></tr><tr><td>GET</td><td>/apisix/admin/ssls/{id}</td><td>NULL</td><td>Fetch specified resource by id.</td></tr><tr><td>PUT</td><td>/apisix/admin/ssls/{id}</td><td>{...}</td><td>Creates a resource with the specified id.</td></tr><tr><td>POST</td><td>/apisix/admin/ssls</td><td>{...}</td><td>Creates a resource and assigns a random id.</td></tr><tr><td>DELETE</td><td>/apisix/admin/ssls/{id}</td><td>NULL</td><td>Removes the resource with the specified id.</td></tr></tbody></table><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-body-parameters-5"></a>Request Body Parameters<a class="hash-link" href="#request-body-parameters-5" title="Direct link to heading">#</a></h3><table><thead><tr><th>Parameter</th><th>Required</th><th>Type</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>cert</td><td>True</td><td>Certificate</td><td>HTTPS certificate. This field supports saving the value in Secret Manager using the <a href="/docs/apisix/3.12/terminology/secret/">APISIX Secret</a> resource.</td><td></td></tr><tr><td>key</td><td>True</td><td>Private key</td><td>HTTPS private key. This field supports saving the value in Secret Manager using the <a href="/docs/apisix/3.12/terminology/secret/">APISIX Secret</a> resource.</td><td></td></tr><tr><td>certs</td><td>False</td><td>An array of certificates</td><td>Used for configuring multiple certificates for the same domain excluding the one provided in the <code>cert</code> field. This field supports saving the value in Secret Manager using the <a href="/docs/apisix/3.12/terminology/secret/">APISIX Secret</a> resource.</td><td></td></tr><tr><td>keys</td><td>False</td><td>An array of private keys</td><td>Private keys to pair with the <code>certs</code>. This field supports saving the value in Secret Manager using the <a href="/docs/apisix/3.12/terminology/secret/">APISIX Secret</a> resource.</td><td></td></tr><tr><td>client.ca</td><td>False</td><td>Certificate</td><td>Sets the CA certificate that verifies the client. Requires OpenResty 1.19+.</td><td></td></tr><tr><td>client.depth</td><td>False</td><td>Certificate</td><td>Sets the verification depth in client certificate chains. Defaults to 1. Requires OpenResty 1.19+.</td><td></td></tr><tr><td>client.skip_mtls_uri_regex</td><td>False</td><td>An array of regular expressions, in PCRE format</td><td>Used to match URI, if matched, this request bypasses the client certificate checking, i.e. skip the MTLS.</td><td>["/hello[0-9]+", "/foobar"]</td></tr><tr><td>snis</td><td>True, only if <code>type</code> is <code>server</code></td><td>Match Rules</td><td>A non-empty array of HTTPS SNI</td><td></td></tr><tr><td>labels</td><td>False</td><td>Match Rules</td><td>Attributes of the resource specified as key-value pairs.</td><td>{"version":"v2","build":"16","env":"production"}</td></tr><tr><td>type</td><td>False</td><td>Auxiliary</td><td>Identifies the type of certificate, default <code>server</code>.</td><td><code>client</code> Indicates that the certificate is a client certificate, which is used when APISIX accesses the upstream; <code>server</code> Indicates that the certificate is a server-side certificate, which is used by APISIX when verifying client requests.</td></tr><tr><td>status</td><td>False</td><td>Auxiliary</td><td>Enables the current SSL. Set to <code>1</code> (enabled) by default.</td><td><code>1</code> to enable, <code>0</code> to disable</td></tr><tr><td>ssl_protocols</td><td>False</td><td>An array of ssl protocols</td><td>It is used to control the SSL/TLS protocol version used between servers and clients. See <a href="/docs/apisix/3.12/ssl-protocol/">SSL Protocol</a> for more examples.</td><td><code>["TLSv1.1", "TLSv1.2", "TLSv1.3"]</code></td></tr></tbody></table><p>Example Configuration:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"id"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"1"</span><span class="token plain">, </span><span class="token comment" style="color:#999988;font-style:italic"># id</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"cert"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"cert"</span><span class="token plain">, </span><span class="token comment" style="color:#999988;font-style:italic"># Certificate</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"key"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"key"</span><span class="token plain">, </span><span class="token comment" style="color:#999988;font-style:italic"># Private key</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"snis"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"t.com"</span><span class="token punctuation" style="color:#393A34">]</span><span class="token plain"> </span><span class="token comment" style="color:#999988;font-style:italic"># https SNI</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>See <a href="/docs/apisix/3.12/certificate/">Certificate</a> for more examples.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="global-rule"></a>Global Rule<a class="hash-link" href="#global-rule" title="Direct link to heading">#</a></h2><p>Sets Plugins which run globally. i.e these Plugins will be run before any Route/Service level Plugins.</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="global-rule-api"></a>Global Rule API<a class="hash-link" href="#global-rule-api" title="Direct link to heading">#</a></h3><p>Global Rule resource request address: /apisix/admin/global_rules/{id}</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-methods-6"></a>Request Methods<a class="hash-link" href="#request-methods-6" title="Direct link to heading">#</a></h3><table><thead><tr><th>Method</th><th>Request URI</th><th>Request Body</th><th>Description</th></tr></thead><tbody><tr><td>GET</td><td>/apisix/admin/global_rules</td><td>NULL</td><td>Fetches a list of all Global Rules.</td></tr><tr><td>GET</td><td>/apisix/admin/global_rules/{id}</td><td>NULL</td><td>Fetches specified Global Rule by id.</td></tr><tr><td>PUT</td><td>/apisix/admin/global_rules/{id}</td><td>{...}</td><td>Creates a Global Rule with the specified id.</td></tr><tr><td>DELETE</td><td>/apisix/admin/global_rules/{id}</td><td>NULL</td><td>Removes the Global Rule with the specified id.</td></tr><tr><td>PATCH</td><td>/apisix/admin/global_rules/{id}</td><td>{...}</td><td>Updates the selected attributes of the specified, existing Global Rule. To delete an attribute, set value of attribute set to null.</td></tr><tr><td>PATCH</td><td>/apisix/admin/global_rules/{id}/{path}</td><td>{...}</td><td>Updates the attribute specified in the path. The values of other attributes remain unchanged.</td></tr></tbody></table><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-body-parameters-6"></a>Request Body Parameters<a class="hash-link" href="#request-body-parameters-6" title="Direct link to heading">#</a></h3><table><thead><tr><th>Parameter</th><th>Required</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>plugins</td><td>True</td><td>Plugins that are executed during the request/response cycle. See <a href="/docs/apisix/3.12/terminology/plugin/">Plugin</a> for more.</td><td></td></tr></tbody></table><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="consumer-group"></a>Consumer group<a class="hash-link" href="#consumer-group" title="Direct link to heading">#</a></h2><p>Group of Plugins which can be reused across Consumers.</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="consumer-group-api"></a>Consumer group API<a class="hash-link" href="#consumer-group-api" title="Direct link to heading">#</a></h3><p>Consumer group resource request address: /apisix/admin/consumer_groups/{id}</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-methods-7"></a>Request Methods<a class="hash-link" href="#request-methods-7" title="Direct link to heading">#</a></h3><table><thead><tr><th>Method</th><th>Request URI</th><th>Request Body</th><th>Description</th></tr></thead><tbody><tr><td>GET</td><td>/apisix/admin/consumer_groups</td><td>NULL</td><td>Fetches a list of all Consumer groups.</td></tr><tr><td>GET</td><td>/apisix/admin/consumer_groups/{id}</td><td>NULL</td><td>Fetches specified Consumer group by id.</td></tr><tr><td>PUT</td><td>/apisix/admin/consumer_groups/{id}</td><td>{...}</td><td>Creates a new Consumer group with the specified id.</td></tr><tr><td>DELETE</td><td>/apisix/admin/consumer_groups/{id}</td><td>NULL</td><td>Removes the Consumer group with the specified id.</td></tr><tr><td>PATCH</td><td>/apisix/admin/consumer_groups/{id}</td><td>{...}</td><td>Updates the selected attributes of the specified, existing Consumer group. To delete an attribute, set value of attribute set to null.</td></tr><tr><td>PATCH</td><td>/apisix/admin/consumer_groups/{id}/{path}</td><td>{...}</td><td>Updates the attribute specified in the path. The values of other attributes remain unchanged.</td></tr></tbody></table><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-body-parameters-7"></a>Request Body Parameters<a class="hash-link" href="#request-body-parameters-7" title="Direct link to heading">#</a></h3><table><thead><tr><th>Parameter</th><th>Required</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>plugins</td><td>True</td><td>Plugins that are executed during the request/response cycle. See <a href="/docs/apisix/3.12/terminology/plugin/">Plugin</a> for more.</td><td></td></tr><tr><td>desc</td><td>False</td><td>Description of usage scenarios.</td><td>customer xxxx</td></tr><tr><td>labels</td><td>False</td><td>Attributes of the Consumer group specified as key-value pairs.</td><td>{"version":"v2","build":"16","env":"production"}</td></tr></tbody></table><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="plugin-config"></a>Plugin config<a class="hash-link" href="#plugin-config" title="Direct link to heading">#</a></h2><p>Group of Plugins which can be reused across Routes.</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="plugin-config-api"></a>Plugin Config API<a class="hash-link" href="#plugin-config-api" title="Direct link to heading">#</a></h3><p>Plugin Config resource request address: /apisix/admin/plugin_configs/{id}</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-methods-8"></a>Request Methods<a class="hash-link" href="#request-methods-8" title="Direct link to heading">#</a></h3><table><thead><tr><th>Method</th><th>Request URI</th><th>Request Body</th><th>Description</th></tr></thead><tbody><tr><td>GET</td><td>/apisix/admin/plugin_configs</td><td>NULL</td><td>Fetches a list of all Plugin configs.</td></tr><tr><td>GET</td><td>/apisix/admin/plugin_configs/{id}</td><td>NULL</td><td>Fetches specified Plugin config by id.</td></tr><tr><td>PUT</td><td>/apisix/admin/plugin_configs/{id}</td><td>{...}</td><td>Creates a new Plugin config with the specified id.</td></tr><tr><td>DELETE</td><td>/apisix/admin/plugin_configs/{id}</td><td>NULL</td><td>Removes the Plugin config with the specified id.</td></tr><tr><td>PATCH</td><td>/apisix/admin/plugin_configs/{id}</td><td>{...}</td><td>Updates the selected attributes of the specified, existing Plugin config. To delete an attribute, set value of attribute set to null.</td></tr><tr><td>PATCH</td><td>/apisix/admin/plugin_configs/{id}/{path}</td><td>{...}</td><td>Updates the attribute specified in the path. The values of other attributes remain unchanged.</td></tr></tbody></table><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-body-parameters-8"></a>Request Body Parameters<a class="hash-link" href="#request-body-parameters-8" title="Direct link to heading">#</a></h3><table><thead><tr><th>Parameter</th><th>Required</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>plugins</td><td>True</td><td>Plugins that are executed during the request/response cycle. See <a href="/docs/apisix/3.12/terminology/plugin/">Plugin</a> for more.</td><td></td></tr><tr><td>desc</td><td>False</td><td>Description of usage scenarios.</td><td>customer xxxx</td></tr><tr><td>labels</td><td>False</td><td>Attributes of the Plugin config specified as key-value pairs.</td><td>{"version":"v2","build":"16","env":"production"}</td></tr></tbody></table><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="plugin-metadata"></a>Plugin Metadata<a class="hash-link" href="#plugin-metadata" title="Direct link to heading">#</a></h2><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="plugin-metadata-api"></a>Plugin Metadata API<a class="hash-link" href="#plugin-metadata-api" title="Direct link to heading">#</a></h3><p>Plugin Metadata resource request address: /apisix/admin/plugin_metadata/{plugin_name}</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-methods-9"></a>Request Methods<a class="hash-link" href="#request-methods-9" title="Direct link to heading">#</a></h3><table><thead><tr><th>Method</th><th>Request URI</th><th>Request Body</th><th>Description</th></tr></thead><tbody><tr><td>GET</td><td>/apisix/admin/plugin_metadata/{plugin_name}</td><td>NULL</td><td>Fetches the metadata of the specified Plugin by <code>plugin_name</code>.</td></tr><tr><td>PUT</td><td>/apisix/admin/plugin_metadata/{plugin_name}</td><td>{...}</td><td>Creates metadata for the Plugin specified by the <code>plugin_name</code>.</td></tr><tr><td>DELETE</td><td>/apisix/admin/plugin_metadata/{plugin_name}</td><td>NULL</td><td>Removes metadata for the Plugin specified by the <code>plugin_name</code>.</td></tr></tbody></table><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-body-parameters-9"></a>Request Body Parameters<a class="hash-link" href="#request-body-parameters-9" title="Direct link to heading">#</a></h3><p>A JSON object defined according to the <code>metadata_schema</code> of the Plugin ({plugin_name}).</p><p>Example Configuration:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/plugin_metadata/example-plugin </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -i -X PUT -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "skey": "val",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "ikey": 1</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">201</span><span class="token plain"> Created</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">Date: Thu, </span><span class="token number" style="color:#36acaa">26</span><span class="token plain"> Dec </span><span class="token number" style="color:#36acaa">2019</span><span class="token plain"> 04:19:34 GMT</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">Content-Type: text/plain</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="plugin"></a>Plugin<a class="hash-link" href="#plugin" title="Direct link to heading">#</a></h2><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="plugin-api"></a>Plugin API<a class="hash-link" href="#plugin-api" title="Direct link to heading">#</a></h3><p>Plugin resource request address: /apisix/admin/plugins/{plugin_name}</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-methods-10"></a>Request Methods<a class="hash-link" href="#request-methods-10" title="Direct link to heading">#</a></h3><table><thead><tr><th>Method</th><th>Request URI</th><th>Request Body</th><th>Description</th></tr></thead><tbody><tr><td>GET</td><td>/apisix/admin/plugins/list</td><td>NULL</td><td>Fetches a list of all Plugins.</td></tr><tr><td>GET</td><td>/apisix/admin/plugins/{plugin_name}</td><td>NULL</td><td>Fetches the specified Plugin by <code>plugin_name</code>.</td></tr><tr><td>GET</td><td>/apisix/admin/plugins?all=true</td><td>NULL</td><td>Get all properties of all plugins.</td></tr><tr><td>GET</td><td>/apisix/admin/plugins?all=true&subsystem=stream</td><td>NULL</td><td>Gets properties of all Stream plugins.</td></tr><tr><td>GET</td><td>/apisix/admin/plugins?all=true&subsystem=http</td><td>NULL</td><td>Gets properties of all HTTP plugins.</td></tr><tr><td>PUT</td><td>/apisix/admin/plugins/reload</td><td>NULL</td><td>Reloads the plugin according to the changes made in code</td></tr><tr><td>GET</td><td>apisix/admin/plugins/{plugin_name}?subsystem=stream</td><td>NULL</td><td>Gets properties of a specified plugin if it is supported in Stream/L4 subsystem.</td></tr><tr><td>GET</td><td>apisix/admin/plugins/{plugin_name}?subsystem=http</td><td>NULL</td><td>Gets properties of a specified plugin if it is supported in HTTP/L7 subsystem.</td></tr></tbody></table><div class="admonition admonition-caution alert alert--warning"><div class="admonition-heading"><h5><span class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"></path></svg></span>caution</h5></div><div class="admonition-content"><p>The interface of getting properties of all plugins via <code>/apisix/admin/plugins?all=true</code> will be deprecated soon.</p></div></div><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-body-parameters-10"></a>Request Body Parameters<a class="hash-link" href="#request-body-parameters-10" title="Direct link to heading">#</a></h3><p>The Plugin ({plugin_name}) of the data structure.</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-arguments"></a>Request Arguments<a class="hash-link" href="#request-arguments" title="Direct link to heading">#</a></h3><table><thead><tr><th>Name</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td>subsystem</td><td>The subsystem of the Plugins.</td><td>http</td></tr></tbody></table><p>The plugin can be filtered on subsystem so that the ({plugin_name}) is searched in the subsystem passed through query params.</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="example-api-usage-5"></a>Example API usage:<a class="hash-link" href="#example-api-usage-5" title="Direct link to heading">#</a></h3><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"http://127.0.0.1:9180/apisix/admin/plugins/list"</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H </span><span class="token string" style="color:#e3116c">'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"zipkin"</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"request-id"</span><span class="token plain">,</span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><span class="token punctuation" style="color:#393A34">]</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"http://127.0.0.1:9180/apisix/admin/plugins/key-auth?subsystem=http"</span><span class="token plain"> -H </span><span class="token string" style="color:#e3116c">'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 json"><pre tabindex="0" class="prism-code language-json codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token property" style="color:#36acaa">"$comment"</span><span class="token operator" style="color:#393A34">:</span><span class="token string" style="color:#e3116c">"this is a mark for our injected plugin schema"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token property" style="color:#36acaa">"properties"</span><span class="token operator" style="color:#393A34">:</span><span class="token punctuation" style="color:#393A34">{</span><span class="token property" style="color:#36acaa">"header"</span><span class="token operator" style="color:#393A34">:</span><span class="token punctuation" style="color:#393A34">{</span><span class="token property" style="color:#36acaa">"default"</span><span class="token operator" style="color:#393A34">:</span><span class="token string" style="color:#e3116c">"apikey"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token property" style="color:#36acaa">"type"</span><span class="token operator" style="color:#393A34">:</span><span class="token string" style="color:#e3116c">"string"</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token property" style="color:#36acaa">"hide_credentials"</span><span class="token operator" style="color:#393A34">:</span><span class="token punctuation" style="color:#393A34">{</span><span class="token property" style="color:#36acaa">"default"</span><span class="token operator" style="color:#393A34">:</span><span class="token boolean" style="color:#36acaa">false</span><span class="token punctuation" style="color:#393A34">,</span><span class="token property" style="color:#36acaa">"type"</span><span class="token operator" style="color:#393A34">:</span><span class="token string" style="color:#e3116c">"boolean"</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token property" style="color:#36acaa">"_meta"</span><span class="token operator" style="color:#393A34">:</span><span class="token punctuation" style="color:#393A34">{</span><span class="token property" style="color:#36acaa">"properties"</span><span class="token operator" style="color:#393A34">:</span><span class="token punctuation" style="color:#393A34">{</span><span class="token property" style="color:#36acaa">"filter"</span><span class="token operator" style="color:#393A34">:</span><span class="token punctuation" style="color:#393A34">{</span><span class="token property" style="color:#36acaa">"type"</span><span class="token operator" style="color:#393A34">:</span><span class="token string" style="color:#e3116c">"array"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token property" style="color:#36acaa">"description"</span><span class="token operator" style="color:#393A34">:</span><span class="token string" style="color:#e3116c">"filter determines whether the plugin needs to be executed at runtime"</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token property" style="color:#36acaa">"disable"</span><span class="token operator" style="color:#393A34">:</span><span class="token punctuation" style="color:#393A34">{</span><span class="token property" style="color:#36acaa">"type"</span><span class="token operator" style="color:#393A34">:</span><span class="token string" style="color:#e3116c">"boolean"</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token property" style="color:#36acaa">"error_response"</span><span class="token operator" style="color:#393A34">:</span><span class="token punctuation" style="color:#393A34">{</span><span class="token property" style="color:#36acaa">"oneOf"</span><span class="token operator" style="color:#393A34">:</span><span class="token punctuation" style="color:#393A34">[</span><span class="token punctuation" style="color:#393A34">{</span><span class="token property" style="color:#36acaa">"type"</span><span class="token operator" style="color:#393A34">:</span><span class="token string" style="color:#e3116c">"string"</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token punctuation" style="color:#393A34">{</span><span class="token property" style="color:#36acaa">"type"</span><span class="token operator" style="color:#393A34">:</span><span class="token string" style="color:#e3116c">"object"</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">]</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token property" style="color:#36acaa">"priority"</span><span class="token operator" style="color:#393A34">:</span><span class="token punctuation" style="color:#393A34">{</span><span class="token property" style="color:#36acaa">"type"</span><span class="token operator" style="color:#393A34">:</span><span class="token string" style="color:#e3116c">"integer"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token property" style="color:#36acaa">"description"</span><span class="token operator" style="color:#393A34">:</span><span class="token string" style="color:#e3116c">"priority of plugins by customized order"</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token property" style="color:#36acaa">"type"</span><span class="token operator" style="color:#393A34">:</span><span class="token string" style="color:#e3116c">"object"</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token property" style="color:#36acaa">"query"</span><span class="token operator" style="color:#393A34">:</span><span class="token punctuation" style="color:#393A34">{</span><span class="token property" style="color:#36acaa">"default"</span><span class="token operator" style="color:#393A34">:</span><span class="token string" style="color:#e3116c">"apikey"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token property" style="color:#36acaa">"type"</span><span class="token operator" style="color:#393A34">:</span><span class="token string" style="color:#e3116c">"string"</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token property" style="color:#36acaa">"type"</span><span class="token operator" style="color:#393A34">:</span><span class="token string" style="color:#e3116c">"object"</span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="admonition admonition-tip alert alert--success"><div class="admonition-heading"><h5><span class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" width="12" height="16" viewBox="0 0 12 16"><path fill-rule="evenodd" d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"></path></svg></span>tip</h5></div><div class="admonition-content"><p>You can use the <code>/apisix/admin/plugins?all=true</code> API to get all properties of all plugins. This API will be deprecated soon.</p></div></div><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="stream-route"></a>Stream Route<a class="hash-link" href="#stream-route" title="Direct link to heading">#</a></h2><p>Route used in the <a href="/docs/apisix/3.12/stream-proxy/">Stream Proxy</a>.</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="stream-route-api"></a>Stream Route API<a class="hash-link" href="#stream-route-api" title="Direct link to heading">#</a></h3><p>Stream Route resource request address: /apisix/admin/stream_routes/{id}</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-methods-11"></a>Request Methods<a class="hash-link" href="#request-methods-11" title="Direct link to heading">#</a></h3><table><thead><tr><th>Method</th><th>Request URI</th><th>Request Body</th><th>Description</th></tr></thead><tbody><tr><td>GET</td><td>/apisix/admin/stream_routes</td><td>NULL</td><td>Fetches a list of all configured Stream Routes.</td></tr><tr><td>GET</td><td>/apisix/admin/stream_routes/{id}</td><td>NULL</td><td>Fetches specified Stream Route by id.</td></tr><tr><td>PUT</td><td>/apisix/admin/stream_routes/{id}</td><td>{...}</td><td>Creates a Stream Route with the specified id.</td></tr><tr><td>POST</td><td>/apisix/admin/stream_routes</td><td>{...}</td><td>Creates a Stream Route and assigns a random id.</td></tr><tr><td>DELETE</td><td>/apisix/admin/stream_routes/{id}</td><td>NULL</td><td>Removes the Stream Route with the specified id.</td></tr></tbody></table><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-body-parameters-11"></a>Request Body Parameters<a class="hash-link" href="#request-body-parameters-11" title="Direct link to heading">#</a></h3><table><thead><tr><th>Parameter</th><th>Required</th><th>Type</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>upstream</td><td>False</td><td>Upstream</td><td>Configuration of the <a href="/docs/apisix/3.12/terminology/upstream/">Upstream</a>.</td><td></td></tr><tr><td>upstream_id</td><td>False</td><td>Upstream</td><td>Id of the <a href="/docs/apisix/3.12/terminology/upstream/">Upstream</a> service.</td><td></td></tr><tr><td>service_id</td><td>False</td><td>String</td><td>Id of the <a href="/docs/apisix/3.12/terminology/service/">Service</a> service.</td><td></td></tr><tr><td>remote_addr</td><td>False</td><td>IPv4, IPv4 CIDR, IPv6</td><td>Filters Upstream forwards by matching with client IP.</td><td>"127.0.0.1" or "127.0.0.1/32" or "::1"</td></tr><tr><td>server_addr</td><td>False</td><td>IPv4, IPv4 CIDR, IPv6</td><td>Filters Upstream forwards by matching with APISIX Server IP.</td><td>"127.0.0.1" or "127.0.0.1/32" or "::1"</td></tr><tr><td>server_port</td><td>False</td><td>Integer</td><td>Filters Upstream forwards by matching with APISIX Server port.</td><td>9090</td></tr><tr><td>sni</td><td>False</td><td>Host</td><td>Server Name Indication.</td><td>"test.com"</td></tr><tr><td>protocol.name</td><td>False</td><td>String</td><td>Name of the protocol proxyed by xRPC framework.</td><td>"redis"</td></tr><tr><td>protocol.conf</td><td>False</td><td>Configuration</td><td>Protocol-specific configuration.</td><td></td></tr></tbody></table><p>To learn more about filtering in stream proxies, check <a href="/docs/apisix/3.12/stream-proxy/#more-route-match-options">this</a> document.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="secret"></a>Secret<a class="hash-link" href="#secret" title="Direct link to heading">#</a></h2><p>Secret means <code>Secrets Management</code>, which could use any secret manager supported, e.g. <code>vault</code>.</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="secret-api"></a>Secret API<a class="hash-link" href="#secret-api" title="Direct link to heading">#</a></h3><p>Secret resource request address: /apisix/admin/secrets/{secretmanager}/{id}</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-methods-12"></a>Request Methods<a class="hash-link" href="#request-methods-12" title="Direct link to heading">#</a></h3><table><thead><tr><th>Method</th><th>Request URI</th><th>Request Body</th><th>Description</th></tr></thead><tbody><tr><td>GET</td><td>/apisix/admin/secrets</td><td>NULL</td><td>Fetches a list of all secrets.</td></tr><tr><td>GET</td><td>/apisix/admin/secrets/{manager}/{id}</td><td>NULL</td><td>Fetches specified secrets by id.</td></tr><tr><td>PUT</td><td>/apisix/admin/secrets/{manager}</td><td>{...}</td><td>Create new secrets configuration.</td></tr><tr><td>DELETE</td><td>/apisix/admin/secrets/{manager}/{id}</td><td>NULL</td><td>Removes the secrets with the specified id.</td></tr><tr><td>PATCH</td><td>/apisix/admin/secrets/{manager}/{id}</td><td>{...}</td><td>Updates the selected attributes of the specified, existing secrets. To delete an attribute, set value of attribute set to null.</td></tr><tr><td>PATCH</td><td>/apisix/admin/secrets/{manager}/{id}/{path}</td><td>{...}</td><td>Updates the attribute specified in the path. The values of other attributes remain unchanged.</td></tr></tbody></table><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-body-parameters-12"></a>Request Body Parameters<a class="hash-link" href="#request-body-parameters-12" title="Direct link to heading">#</a></h3><h4><a aria-hidden="true" tabindex="-1" class="anchor anchor__h4 anchorWithHideOnScrollNavbar_3ly5" id="when-secret-manager-is-vault"></a>When Secret Manager is Vault<a class="hash-link" href="#when-secret-manager-is-vault" title="Direct link to heading">#</a></h4><table><thead><tr><th>Parameter</th><th>Required</th><th>Type</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>uri</td><td>True</td><td>URI</td><td>URI of the vault server.</td><td></td></tr><tr><td>prefix</td><td>True</td><td>string</td><td>key prefix</td><td></td></tr><tr><td>token</td><td>True</td><td>string</td><td>vault token.</td><td></td></tr><tr><td>namespace</td><td>False</td><td>string</td><td>Vault namespace, no default value</td><td><code>admin</code></td></tr></tbody></table><p>Example Configuration:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"uri"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"https://localhost/vault"</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"prefix"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"/apisix/kv"</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"token"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"343effad"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>Example API usage:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> -i http://127.0.0.1:9180/apisix/admin/secrets/vault/test2 </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PUT -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "uri": "http://xxx/get",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "prefix" : "apisix",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "token" : "apisix"</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">200</span><span class="token plain"> OK</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"key"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"\/apisix\/secrets\/vault\/test2"</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"value"</span><span class="token plain">:</span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"id"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"vault\/test2"</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"token"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"apisix"</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"prefix"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"apisix"</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"update_time"</span><span class="token plain">:1669625828,</span><span class="token string" style="color:#e3116c">"create_time"</span><span class="token plain">:1669625828,</span><span class="token string" style="color:#e3116c">"uri"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"http:\/\/xxx\/get"</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><h4><a aria-hidden="true" tabindex="-1" class="anchor anchor__h4 anchorWithHideOnScrollNavbar_3ly5" id="when-secret-manager-is-aws"></a>When Secret Manager is AWS<a class="hash-link" href="#when-secret-manager-is-aws" title="Direct link to heading">#</a></h4><table><thead><tr><th>Parameter</th><th>Required</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>access_key_id</td><td>True</td><td>string</td><td>AWS Access Key ID</td></tr><tr><td>secret_access_key</td><td>True</td><td>string</td><td>AWS Secret Access Key</td></tr><tr><td>session_token</td><td>False</td><td>string</td><td>Temporary access credential information</td></tr><tr><td>region</td><td>False</td><td>string</td><td>AWS Region</td></tr><tr><td>endpoint_url</td><td>False</td><td>URI</td><td>AWS Secret Manager URL</td></tr></tbody></table><p>Example Configuration:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 json"><pre tabindex="0" class="prism-code language-json codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"endpoint_url"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"http://127.0.0.1:4566"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"region"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"us-east-1"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"access_key_id"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"access"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"secret_access_key"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"secret"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"session_token"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"token"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>Example API usage:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> -i http://127.0.0.1:9180/apisix/admin/secrets/aws/test3 </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PUT -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "endpoint_url": "http://127.0.0.1:4566",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "region": "us-east-1",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "access_key_id": "access",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "secret_access_key": "secret",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "session_token": "token"</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">200</span><span class="token plain"> OK</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"value"</span><span class="token plain">:</span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"create_time"</span><span class="token plain">:1726069970,</span><span class="token string" style="color:#e3116c">"endpoint_url"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"http://127.0.0.1:4566"</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"region"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"us-east-1"</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"access_key_id"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"access"</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"secret_access_key"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"secret"</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"id"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"aws/test3"</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"update_time"</span><span class="token plain">:1726069970,</span><span class="token string" style="color:#e3116c">"session_token"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"token"</span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"key"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"/apisix/secrets/aws/test3"</span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><h4><a aria-hidden="true" tabindex="-1" class="anchor anchor__h4 anchorWithHideOnScrollNavbar_3ly5" id="when-secret-manager-is-gcp"></a>When Secret Manager is GCP<a class="hash-link" href="#when-secret-manager-is-gcp" title="Direct link to heading">#</a></h4><table><thead><tr><th>Parameter</th><th>Required</th><th>Type</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>auth_config</td><td>True</td><td>object</td><td>Either <code>auth_config</code> or <code>auth_file</code> must be provided.</td><td></td></tr><tr><td>auth_config.client_email</td><td>True</td><td>string</td><td>Email address of the Google Cloud service account.</td><td></td></tr><tr><td>auth_config.private_key</td><td>True</td><td>string</td><td>Private key of the Google Cloud service account.</td><td></td></tr><tr><td>auth_config.project_id</td><td>True</td><td>string</td><td>Project ID in the Google Cloud service account.</td><td></td></tr><tr><td>auth_config.token_uri</td><td>False</td><td>string</td><td>Token URI of the Google Cloud service account.</td><td><a href="https://oauth2.googleapis.com/token" target="_blank" rel="noopener noreferrer">https://oauth2.googleapis.com/token</a></td></tr><tr><td>auth_config.entries_uri</td><td>False</td><td>string</td><td>The API access endpoint for the Google Secrets Manager.</td><td><a href="https://secretmanager.googleapis.com/v1" target="_blank" rel="noopener noreferrer">https://secretmanager.googleapis.com/v1</a></td></tr><tr><td>auth_config.scope</td><td>False</td><td>string</td><td>Access scopes of the Google Cloud service account. See <a href="https://developers.google.com/identity/protocols/oauth2/scopes" target="_blank" rel="noopener noreferrer">OAuth 2.0 Scopes for Google APIs</a></td><td><a href="https://www.googleapis.com/auth/cloud-platform" target="_blank" rel="noopener noreferrer">https://www.googleapis.com/auth/cloud-platform</a></td></tr><tr><td>auth_file</td><td>True</td><td>string</td><td>Path to the Google Cloud service account authentication JSON file. Either <code>auth_config</code> or <code>auth_file</code> must be provided.</td><td></td></tr><tr><td>ssl_verify</td><td>False</td><td>boolean</td><td>When set to <code>true</code>, enables SSL verification as mentioned in <a href="https://github.com/openresty/lua-nginx-module#tcpsocksslhandshake" target="_blank" rel="noopener noreferrer">OpenResty docs</a>.</td><td>true</td></tr></tbody></table><p>Example Configuration:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 json"><pre tabindex="0" class="prism-code language-json codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"auth_config"</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"client_email"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"email@apisix.iam.gserviceaccount.com"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"private_key"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"private_key"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"project_id"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"apisix-project"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"token_uri"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"https://oauth2.googleapis.com/token"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"entries_uri"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"https://secretmanager.googleapis.com/v1"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"scope"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"https://www.googleapis.com/auth/cloud-platform"</span><span class="token punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>Example API usage:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> -i http://127.0.0.1:9180/apisix/admin/secrets/gcp/test4 </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PUT -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "auth_config" : {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "client_email": "email@apisix.iam.gserviceaccount.com",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "private_key": "private_key",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "project_id": "apisix-project",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "token_uri": "https://oauth2.googleapis.com/token",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "entries_uri": "https://secretmanager.googleapis.com/v1",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "scope": ["https://www.googleapis.com/auth/cloud-platform"]</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">200</span><span class="token plain"> OK</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"value"</span><span class="token plain">:</span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"id"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"gcp/test4"</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"ssl_verify"</span><span class="token plain">:true,</span><span class="token string" style="color:#e3116c">"auth_config"</span><span class="token plain">:</span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"token_uri"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"https://oauth2.googleapis.com/token"</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"scope"</span><span class="token plain">:</span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"https://www.googleapis.com/auth/cloud-platform"</span><span class="token punctuation" style="color:#393A34">]</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"entries_uri"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"https://secretmanager.googleapis.com/v1"</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"client_email"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"email@apisix.iam.gserviceaccount.com"</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"private_key"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"private_key"</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"project_id"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"apisix-project"</span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"create_time"</span><span class="token plain">:1726070161,</span><span class="token string" style="color:#e3116c">"update_time"</span><span class="token plain">:1726070161</span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain">,</span><span class="token string" style="color:#e3116c">"key"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"/apisix/secrets/gcp/test4"</span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="response-parameters-4"></a>Response Parameters<a class="hash-link" href="#response-parameters-4" title="Direct link to heading">#</a></h3><p>Currently, the response is returned from etcd.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="proto"></a>Proto<a class="hash-link" href="#proto" title="Direct link to heading">#</a></h2><p>Proto is used to store protocol buffers so that APISIX can communicate in gRPC.</p><p>See <a href="/docs/apisix/3.12/plugins/grpc-transcode/#enabling-the-plugin">grpc-transcode plugin</a> doc for more examples.</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="proto-api"></a>Proto API<a class="hash-link" href="#proto-api" title="Direct link to heading">#</a></h3><p>Proto resource request address: /apisix/admin/protos/{id}</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-methods-13"></a>Request Methods<a class="hash-link" href="#request-methods-13" title="Direct link to heading">#</a></h3><table><thead><tr><th>Method</th><th>Request URI</th><th>Request Body</th><th>Description</th></tr></thead><tbody><tr><td>GET</td><td>/apisix/admin/protos</td><td>NULL</td><td>List all Protos.</td></tr><tr><td>GET</td><td>/apisix/admin/protos/{id}</td><td>NULL</td><td>Get a Proto by id.</td></tr><tr><td>PUT</td><td>/apisix/admin/protos/{id}</td><td>{...}</td><td>Create or update a Proto with the given id.</td></tr><tr><td>POST</td><td>/apisix/admin/protos</td><td>{...}</td><td>Create a Proto with a random id.</td></tr><tr><td>DELETE</td><td>/apisix/admin/protos/{id}</td><td>NULL</td><td>Delete Proto by id.</td></tr></tbody></table><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-body-parameters-13"></a>Request Body Parameters<a class="hash-link" href="#request-body-parameters-13" title="Direct link to heading">#</a></h3><table><thead><tr><th>Parameter</th><th>Required</th><th>Type</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>content</td><td>True</td><td>String</td><td>content of <code>.proto</code> or <code>.pb</code> files</td><td>See <a href="/docs/apisix/3.12/plugins/grpc-transcode/#enabling-the-plugin">here</a></td></tr></tbody></table><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="schema-validation"></a>Schema validation<a class="hash-link" href="#schema-validation" title="Direct link to heading">#</a></h2><p>Check the validity of a configuration against its entity schema. This allows you to test your input before submitting a request to the entity endpoints of the Admin API.</p><p>Note that this only performs the schema validation checks, checking that the input configuration is well-formed. Requests to the entity endpoint using the given configuration may still fail due to other reasons, such as invalid foreign key relationships or uniqueness check failures against the contents of the data store.</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="schema-validation-1"></a>Schema validation<a class="hash-link" href="#schema-validation-1" title="Direct link to heading">#</a></h3><p>Schema validation request address: /apisix/admin/schema/validate/{resource}</p><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-methods-14"></a>Request Methods<a class="hash-link" href="#request-methods-14" title="Direct link to heading">#</a></h3><table><thead><tr><th>Method</th><th>Request URI</th><th>Request Body</th><th>Description</th></tr></thead><tbody><tr><td>POST</td><td>/apisix/admin/schema/validate/{resource}</td><td>{..resource conf..}</td><td>Validate the resource configuration against corresponding schema.</td></tr></tbody></table><h3><a aria-hidden="true" tabindex="-1" class="anchor anchor__h3 anchorWithHideOnScrollNavbar_3ly5" id="request-body-parameters-14"></a>Request Body Parameters<a class="hash-link" href="#request-body-parameters-14" title="Direct link to heading">#</a></h3><ul><li>200: validate ok.</li><li>400: validate failed, with error as response body in JSON format.</li></ul><p>Example:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 bash"><pre tabindex="0" class="prism-code language-bash codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/schema/validate/routes </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> -H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X POST -i -d </span><span class="token string" style="color:#e3116c">'{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "uri": 1980,</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "upstream": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "scheme": "https",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "type": "roundrobin",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "nodes": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "nghttp2.org": 1</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">400</span><span class="token plain"> Bad Request</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">Date: Mon, </span><span class="token number" style="color:#36acaa">21</span><span class="token plain"> Aug </span><span class="token number" style="color:#36acaa">2023</span><span class="token plain"> 07:37:13 GMT</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">Content-Type: application/json</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">Transfer-Encoding: chunked</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">Connection: keep-alive</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">Server: APISIX/3.4.0</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">Access-Control-Allow-Origin: *</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">Access-Control-Allow-Credentials: </span><span class="token boolean" style="color:#36acaa">true</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">Access-Control-Expose-Headers: *</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">Access-Control-Max-Age: </span><span class="token number" style="color:#36acaa">3600</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"error_msg"</span><span class="token builtin class-name">:</span><span class="token string" style="color:#e3116c">"property </span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c">uri</span><span class="token string entity" style="color:#36acaa">\"</span><span class="token string" style="color:#e3116c"> validation failed: wrong type: expected string, got number"</span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div></div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="theme-doc-footer-edit-meta-row row"><div class="col"><a href="/edit#https://github.com/apache/apisix/edit/release/3.12/docs/en/latest/admin-api.md" target="_blank" rel="noreferrer noopener" class="theme-edit-this-page"><svg fill="currentColor" height="20" width="20" viewBox="0 0 40 40" class="iconEdit_mS5F" aria-hidden="true"><g><path d="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"></path></g></svg>Edit this page</a></div><div class="col lastUpdated_mt2f"></div></div></footer></article><nav class="pagination-nav docusaurus-mt-lg" aria-label="Docs pages navigation"><div class="pagination-nav__item"><a class="pagination-nav__link" href="/docs/apisix/3.12/plugins/http-dubbo/"><div class="pagination-nav__sublabel">Previous</div><div class="pagination-nav__label">« http-dubbo</div></a></div><div class="pagination-nav__item pagination-nav__item--next"><a class="pagination-nav__link" href="/docs/apisix/3.12/control-api/"><div class="pagination-nav__sublabel">Next</div><div class="pagination-nav__label">Control API »</div></a></div></nav></div></div><div class="col col--3"><div class="tableOfContents_vrFS thin-scrollbar"><ul class="table-of-contents table-of-contents__left-border"><li><a href="#description" class="table-of-contents__link">Description</a></li><li><a href="#configuration" class="table-of-contents__link">Configuration</a><ul><li><a href="#using-environment-variables" class="table-of-contents__link">Using environment variables</a></li><li><a href="#force-delete" class="table-of-contents__link">Force Delete</a></li></ul></li><li><a href="#v3-new-feature" class="table-of-contents__link">V3 new feature</a><ul><li><a href="#support-new-response-body-format" class="table-of-contents__link">Support new response body format</a></li><li><a href="#support-paging-query" class="table-of-contents__link">Support paging query</a></li><li><a href="#support-filtering-query" class="table-of-contents__link">Support filtering query</a></li></ul></li><li><a href="#route" class="table-of-contents__link">Route</a><ul><li><a href="#route-api" class="table-of-contents__link">Route API</a></li><li><a href="#quick-note-on-id-syntax" class="table-of-contents__link">Quick Note on ID Syntax</a></li><li><a href="#request-methods" class="table-of-contents__link">Request Methods</a></li><li><a href="#uri-request-parameters" class="table-of-contents__link">URI Request Parameters</a></li><li><a href="#request-body-parameters" class="table-of-contents__link">Request Body Parameters</a></li><li><a href="#example-api-usage" class="table-of-contents__link">Example API usage</a></li><li><a href="#response-parameters" class="table-of-contents__link">Response Parameters</a></li></ul></li><li><a href="#service" class="table-of-contents__link">Service</a><ul><li><a href="#service-api" class="table-of-contents__link">Service API</a></li><li><a href="#request-methods-1" class="table-of-contents__link">Request Methods</a></li><li><a href="#request-body-parameters-1" class="table-of-contents__link">Request Body Parameters</a></li><li><a href="#example-api-usage-1" class="table-of-contents__link">Example API usage</a></li><li><a href="#response-parameters-1" class="table-of-contents__link">Response Parameters</a></li></ul></li><li><a href="#consumer" class="table-of-contents__link">Consumer</a><ul><li><a href="#consumer-api" class="table-of-contents__link">Consumer API</a></li><li><a href="#request-methods-2" class="table-of-contents__link">Request Methods</a></li><li><a href="#request-body-parameters-2" class="table-of-contents__link">Request Body Parameters</a></li><li><a href="#example-api-usage-2" class="table-of-contents__link">Example API usage</a></li><li><a href="#response-parameters-2" class="table-of-contents__link">Response Parameters</a></li></ul></li><li><a href="#credential" class="table-of-contents__link">Credential</a><ul><li><a href="#credential-api" class="table-of-contents__link">Credential API</a></li><li><a href="#request-methods-3" class="table-of-contents__link">Request Methods</a></li><li><a href="#request-body-parameters-3" class="table-of-contents__link">Request Body Parameters</a></li><li><a href="#example-api-usage-3" class="table-of-contents__link">Example API usage</a></li></ul></li><li><a href="#upstream" class="table-of-contents__link">Upstream</a><ul><li><a href="#upstream-api" class="table-of-contents__link">Upstream API</a></li><li><a href="#request-methods-4" class="table-of-contents__link">Request Methods</a></li><li><a href="#request-body-parameters-4" class="table-of-contents__link">Request Body Parameters</a></li><li><a href="#example-api-usage-4" class="table-of-contents__link">Example API usage</a></li><li><a href="#response-parameters-3" class="table-of-contents__link">Response Parameters</a></li></ul></li><li><a href="#ssl" class="table-of-contents__link">SSL</a><ul><li><a href="#ssl-api" class="table-of-contents__link">SSL API</a></li><li><a href="#request-methods-5" class="table-of-contents__link">Request Methods</a></li><li><a href="#request-body-parameters-5" class="table-of-contents__link">Request Body Parameters</a></li></ul></li><li><a href="#global-rule" class="table-of-contents__link">Global Rule</a><ul><li><a href="#global-rule-api" class="table-of-contents__link">Global Rule API</a></li><li><a href="#request-methods-6" class="table-of-contents__link">Request Methods</a></li><li><a href="#request-body-parameters-6" class="table-of-contents__link">Request Body Parameters</a></li></ul></li><li><a href="#consumer-group" class="table-of-contents__link">Consumer group</a><ul><li><a href="#consumer-group-api" class="table-of-contents__link">Consumer group API</a></li><li><a href="#request-methods-7" class="table-of-contents__link">Request Methods</a></li><li><a href="#request-body-parameters-7" class="table-of-contents__link">Request Body Parameters</a></li></ul></li><li><a href="#plugin-config" class="table-of-contents__link">Plugin config</a><ul><li><a href="#plugin-config-api" class="table-of-contents__link">Plugin Config API</a></li><li><a href="#request-methods-8" class="table-of-contents__link">Request Methods</a></li><li><a href="#request-body-parameters-8" class="table-of-contents__link">Request Body Parameters</a></li></ul></li><li><a href="#plugin-metadata" class="table-of-contents__link">Plugin Metadata</a><ul><li><a href="#plugin-metadata-api" class="table-of-contents__link">Plugin Metadata API</a></li><li><a href="#request-methods-9" class="table-of-contents__link">Request Methods</a></li><li><a href="#request-body-parameters-9" class="table-of-contents__link">Request Body Parameters</a></li></ul></li><li><a href="#plugin" class="table-of-contents__link">Plugin</a><ul><li><a href="#plugin-api" class="table-of-contents__link">Plugin API</a></li><li><a href="#request-methods-10" class="table-of-contents__link">Request Methods</a></li><li><a href="#request-body-parameters-10" class="table-of-contents__link">Request Body Parameters</a></li><li><a href="#request-arguments" class="table-of-contents__link">Request Arguments</a></li><li><a href="#example-api-usage-5" class="table-of-contents__link">Example API usage:</a></li></ul></li><li><a href="#stream-route" class="table-of-contents__link">Stream Route</a><ul><li><a href="#stream-route-api" class="table-of-contents__link">Stream Route API</a></li><li><a href="#request-methods-11" class="table-of-contents__link">Request Methods</a></li><li><a href="#request-body-parameters-11" class="table-of-contents__link">Request Body Parameters</a></li></ul></li><li><a href="#secret" class="table-of-contents__link">Secret</a><ul><li><a href="#secret-api" class="table-of-contents__link">Secret API</a></li><li><a href="#request-methods-12" class="table-of-contents__link">Request Methods</a></li><li><a href="#request-body-parameters-12" class="table-of-contents__link">Request Body Parameters</a></li><li><a href="#response-parameters-4" class="table-of-contents__link">Response Parameters</a></li></ul></li><li><a href="#proto" class="table-of-contents__link">Proto</a><ul><li><a href="#proto-api" class="table-of-contents__link">Proto API</a></li><li><a href="#request-methods-13" class="table-of-contents__link">Request Methods</a></li><li><a href="#request-body-parameters-13" class="table-of-contents__link">Request Body Parameters</a></li></ul></li><li><a href="#schema-validation" class="table-of-contents__link">Schema validation</a><ul><li><a href="#schema-validation-1" class="table-of-contents__link">Schema validation</a></li><li><a href="#request-methods-14" class="table-of-contents__link">Request Methods</a></li><li><a href="#request-body-parameters-14" class="table-of-contents__link">Request Body Parameters</a></li></ul></li></ul></div></div></div></div></main></div></div><footer class="container_MP5Z"><div class="linksRow_iwpv"><div class="linksCol_a1ec"><div>ASF</div><ul><li class="footer__item"><a href="https://www.apache.org/" target="_blank" rel="noopener noreferrer"><span></span><span>Foundation</span></a></li><li class="footer__item"><a href="https://www.apache.org/licenses/" target="_blank" rel="noopener noreferrer"><span></span><span>License</span></a></li><li class="footer__item"><a href="https://www.apache.org/events/" target="_blank" rel="noopener noreferrer"><span></span><span>Events</span></a></li><li class="footer__item"><a href="https://www.apache.org/security/" target="_blank" rel="noopener noreferrer"><span></span><span>Security</span></a></li><li class="footer__item"><a href="https://www.apache.org/foundation/sponsorship.html" target="_blank" rel="noopener noreferrer"><span></span><span>Sponsorship</span></a></li><li class="footer__item"><a href="https://www.apache.org/foundation/thanks.html" target="_blank" rel="noopener noreferrer"><span></span><span>Thanks</span></a></li></ul></div><div class="linksCol_a1ec"><div>Community</div><ul><li class="footer__item"><a href="https://github.com/apache/apisix/issues" target="_blank" rel="noopener noreferrer"><span></span><span>GitHub</span></a></li><li class="footer__item"><a href="/docs/general/join/"><span></span><span>Slack</span></a></li><li class="footer__item"><a href="https://twitter.com/ApacheAPISIX" target="_blank" rel="noopener noreferrer"><span></span><span>Twitter</span></a></li><li class="footer__item"><a href="https://www.youtube.com/channel/UCgPD18cMhOg5rmPVnQhAC8g" target="_blank" rel="noopener noreferrer"><span></span><span>YouTube</span></a></li></ul></div><div class="linksCol_a1ec"><div>More</div><ul><li class="footer__item"><a target="_parent" href="/blog/"><span></span><span>Blog</span></a></li><li class="footer__item"><a target="_parent" href="/showcase/"><span></span><span>Showcase</span></a></li><li class="footer__item"><a target="_parent" href="/plugins/"><span></span><span>Plugin Hub</span></a></li><li class="footer__item"><a href="https://github.com/apache/apisix/milestones" target="_parent" rel="noopener noreferrer"><span></span><span>Roadmap</span></a></li></ul></div></div><div class="copyright_ZfFh"><a href="https://www.apache.org/" target="_blank" rel="noopener noreferrer"><span style="display:inline-block;width:231.25px;height:40px"></span></a><div>Copyright © 2019-2025 The Apache Software Foundation. Apache APISIX, APISIX®, Apache, the Apache feather logo, and the Apache APISIX project logo are either registered trademarks or trademarks of the Apache Software Foundation.</div></div></footer></div> |
| <script src="https://apisix-website-static.apiseven.com/assets/js/runtime~main.4fb0d5b2.js"></script> |
| <script src="https://apisix-website-static.apiseven.com/assets/js/main.bee0d8fc.js"></script> |
| </body> |
| </html> |
