github.com/Ilhicas/nomad@v1.0.4-0.20210304152020-e86851182bc3/website/content/api-docs/namespaces.mdx (about)

     1  ---
     2  layout: api
     3  page_title: Namespace - HTTP API
     4  sidebar_title: Namespaces
     5  description: The /namespace endpoints are used to query for and interact with namespaces.
     6  ---
     7  
     8  # Namespace HTTP API
     9  
    10  The `/namespace` endpoints are used to query for and interact with namespaces.
    11  
    12  ~> Prior to Nomad 1.0 Namespaces were an Enterprise-only feature.
    13  
    14  ## List Namespaces
    15  
    16  This endpoint lists all namespaces.
    17  
    18  | Method | Path             | Produces           |
    19  | ------ | ---------------- | ------------------ |
    20  | `GET`  | `/v1/namespaces` | `application/json` |
    21  
    22  The table below shows this endpoint's support for
    23  [blocking queries](/api-docs#blocking-queries) and
    24  [required ACLs](/api-docs#acls).
    25  
    26  | Blocking Queries | ACL Required                                                               |
    27  | ---------------- | -------------------------------------------------------------------------- |
    28  | `YES`            | `namespace:*`<br />Any capability on the namespace authorizes the endpoint |
    29  
    30  ### Parameters
    31  
    32  - `prefix` `(string: "")`- Specifies a string to filter namespaces on based on
    33    an index prefix. This is specified as a query string parameter.
    34  
    35  ### Sample Request
    36  
    37  ```shell-session
    38  $ curl \
    39      https://localhost:4646/v1/namespaces
    40  ```
    41  
    42  ```shell-session
    43  $ curl \
    44      https://localhost:4646/v1/namespaces?prefix=prod
    45  ```
    46  
    47  ### Sample Response
    48  
    49  ```json
    50  [
    51    {
    52      "CreateIndex": 31,
    53      "Description": "Production API Servers",
    54      "ModifyIndex": 31,
    55      "Name": "api-prod",
    56      "Quota": ""
    57    },
    58    {
    59      "CreateIndex": 5,
    60      "Description": "Default shared namespace",
    61      "ModifyIndex": 5,
    62      "Name": "default",
    63      "Quota": ""
    64    }
    65  ]
    66  ```
    67  
    68  ## Read Namespace
    69  
    70  This endpoint reads information about a specific namespace.
    71  
    72  | Method | Path                       | Produces           |
    73  | ------ | -------------------------- | ------------------ |
    74  | `GET`  | `/v1/namespace/:namespace` | `application/json` |
    75  
    76  The table below shows this endpoint's support for
    77  [blocking queries](/api-docs#blocking-queries) and
    78  [required ACLs](/api-docs#acls).
    79  
    80  | Blocking Queries | ACL Required                                                               |
    81  | ---------------- | -------------------------------------------------------------------------- |
    82  | `YES`            | `namespace:*`<br />Any capability on the namespace authorizes the endpoint |
    83  
    84  ### Parameters
    85  
    86  - `:namespace` `(string: <required>)`- Specifies the namespace to query.
    87  
    88  ### Sample Request
    89  
    90  ```shell-session
    91  $ curl \
    92      https://localhost:4646/v1/namespace/api-prod
    93  ```
    94  
    95  ### Sample Response
    96  
    97  ```json
    98  {
    99    "CreateIndex": 31,
   100    "Description": "Production API Servers",
   101    "Quota": "",
   102    "Hash": "N8WvePwqkp6J354eLJMKyhvsFdPELAos0VuBfMoVKoU=",
   103    "ModifyIndex": 31,
   104    "Name": "api-prod"
   105  }
   106  ```
   107  
   108  ## Create or Update Namespace
   109  
   110  This endpoint is used to create or update a namespace.
   111  
   112  | Method | Path                                              | Produces           |
   113  | ------ | ------------------------------------------------- | ------------------ |
   114  | `POST` | `/v1/namespace/:namespace` <br /> `/v1/namespace` | `application/json` |
   115  
   116  The table below shows this endpoint's support for
   117  [blocking queries](/api-docs#blocking-queries) and
   118  [required ACLs](/api-docs#acls).
   119  
   120  | Blocking Queries | ACL Required |
   121  | ---------------- | ------------ |
   122  | `NO`             | `management` |
   123  
   124  ### Parameters
   125  
   126  - `Name` `(string: <required>)`- Specifies the namespace to create or
   127    update.
   128  
   129  - `Description` `(string: "")` - Specifies an optional human-readable
   130    description of the namespace.
   131  
   132  - `Quota` `(string: "")` - Specifies an quota to attach to the namespace.
   133  
   134  ### Sample Payload
   135  
   136  ```javascript
   137  {
   138    "Name": "api-prod",
   139    "Description": "Production API Servers",
   140    "Quota": "prod-quota"
   141  }
   142  ```
   143  
   144  ### Sample Request
   145  
   146  ```shell-session
   147  $ curl \
   148      --request POST \
   149      --data @namespace.json \
   150      https://localhost:4646/v1/namespace/api-prod
   151  ```
   152  
   153  ```shell-session
   154  $ curl \
   155      --request POST \
   156      --data @namespace.json \
   157      https://localhost:4646/v1/namespace
   158  ```
   159  
   160  ## Delete Namespace
   161  
   162  This endpoint is used to delete a namespace.
   163  
   164  | Method   | Path                       | Produces           |
   165  | -------- | -------------------------- | ------------------ |
   166  | `DELETE` | `/v1/namespace/:namespace` | `application/json` |
   167  
   168  The table below shows this endpoint's support for
   169  [blocking queries](/api-docs#blocking-queries) and
   170  [required ACLs](/api-docs#acls).
   171  
   172  | Blocking Queries | ACL Required |
   173  | ---------------- | ------------ |
   174  | `NO`             | `management` |
   175  
   176  ### Parameters
   177  
   178  - `:namespace` `(string: <required>)`- Specifies the namespace to delete.
   179  
   180  ### Sample Request
   181  
   182  ```shell-session
   183  $ curl \
   184      --request DELETE \
   185      https://localhost:4646/v1/namespace/api-prod
   186  ```