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