github.com/Ilhicas/nomad@v1.0.4-0.20210304152020-e86851182bc3/website/content/api-docs/index.mdx (about) 1 --- 2 layout: api 3 page_title: HTTP API 4 sidebar_title: HTTP API Overview 5 description: |- 6 Nomad exposes a RESTful HTTP API to control almost every aspect of the 7 Nomad agent. 8 --- 9 10 # HTTP API 11 12 The main interface to Nomad is a RESTful HTTP API. The API can query the current 13 state of the system as well as modify the state of the system. The Nomad CLI 14 actually invokes Nomad's HTTP for many commands. 15 16 ## Version Prefix 17 18 All API routes are prefixed with `/v1/`. 19 20 This documentation is only for the v1 API. 21 22 ~> **Backwards compatibility:** At the current version, Nomad does not yet 23 promise backwards compatibility even with the v1 prefix. We'll remove this 24 warning when this policy changes. We expect to reach API stability by Nomad 25 1.0. 26 27 ## Addressing and Ports 28 29 Nomad binds to a specific set of addresses and ports. The HTTP API is served via 30 the `http` address and port. This `address:port` must be accessible locally. If 31 you bind to `127.0.0.1:4646`, the API is only available _from that host_. If you 32 bind to a private internal IP, the API will be available from within that 33 network. If you bind to a public IP, the API will be available from the public 34 Internet (not recommended). 35 36 The default port for the Nomad HTTP API is `4646`. This can be overridden via 37 the Nomad configuration block. Here is an example curl request to query a Nomad 38 server with the default configuration: 39 40 ```shell-session 41 $ curl http://127.0.0.1:4646/v1/agent/members 42 ``` 43 44 The conventions used in the API documentation do not list a port and use the 45 standard URL `localhost:4646`. Be sure to replace this with your Nomad agent URL 46 when using the examples. 47 48 ## Data Model and Layout 49 50 There are five primary nouns in Nomad: 51 52 - jobs 53 - nodes 54 - allocations 55 - deployments 56 - evaluations 57 58 [](/img/nomad-data-model.png) 59 60 Jobs are submitted by users and represent a _desired state_. A job is a 61 declarative description of tasks to run which are bounded by constraints and 62 require resources. Jobs can also have affinities which are used to express placement 63 preferences. Nodes are the servers in the clusters that tasks can be 64 scheduled on. The mapping of tasks in a job to nodes is done using allocations. 65 An allocation is used to declare that a set of tasks in a job should be run on a 66 particular node. Scheduling is the process of determining the appropriate 67 allocations and is done as part of an evaluation. Deployments are objects to 68 track a rolling update of allocations between two versions of a job. 69 70 The API is modeled closely on the underlying data model. Use the links to the 71 left for documentation about specific endpoints. There are also "Agent" APIs 72 which interact with a specific agent and not the broader cluster used for 73 administration. 74 75 ## ACLs 76 77 Several endpoints in Nomad use or require ACL tokens to operate. The token are used to authenticate the request and determine if the request is allowed based on the associated authorizations. Tokens are specified per-request by using the `X-Nomad-Token` request header set to the `SecretID` of an ACL Token. 78 79 For more details about ACLs, please see the [ACL Guide](https://learn.hashicorp.com/collections/nomad/access-control). 80 81 ## Authentication 82 83 When ACLs are enabled, a Nomad token should be provided to API requests using the `X-Nomad-Token` header. When using authentication, clients should communicate via TLS. 84 85 Here is an example using curl: 86 87 ```shell-session 88 $ curl \ 89 --header "X-Nomad-Token: aa534e09-6a07-0a45-2295-a7f77063d429" \ 90 https://localhost:4646/v1/jobs 91 ``` 92 93 ## Namespaces 94 95 Nomad has support for namespaces, which allow jobs and their associated objects 96 to be segmented from each other and other users of the cluster. When using 97 non-default namespace, the API request must pass the target namespace as an API 98 query parameter. Prior to Nomad 1.0 namespaces were Enterprise-only. 99 100 Here is an example using curl: 101 102 ```shell-session 103 $ curl \ 104 https://localhost:4646/v1/jobs?namespace=qa 105 ``` 106 107 ## Blocking Queries 108 109 Many endpoints in Nomad support a feature known as "blocking queries". A 110 blocking query is used to wait for a potential change using long polling. Not 111 all endpoints support blocking, but each endpoint uniquely documents its support 112 for blocking queries in the documentation. 113 114 Endpoints that support blocking queries return an HTTP header named 115 `X-Nomad-Index`. This is a unique identifier representing the current state of 116 the requested resource. On a new Nomad cluster the value of this index starts at 1. 117 118 On subsequent requests for this resource, the client can set the `index` query 119 string parameter to the value of `X-Nomad-Index`, indicating that the client 120 wishes to wait for any changes subsequent to that index. 121 122 When this is provided, the HTTP request will "hang" until a change in the system 123 occurs, or the maximum timeout is reached. A critical note is that the return of 124 a blocking request is **no guarantee** of a change. It is possible that the 125 timeout was reached or that there was an idempotent write that does not affect 126 the result of the query. 127 128 In addition to `index`, endpoints that support blocking will also honor a `wait` 129 parameter specifying a maximum duration for the blocking request. This is 130 limited to 10 minutes. If not set, the wait time defaults to 5 minutes. This 131 value can be specified in the form of "10s" or "5m" (i.e., 10 seconds or 5 132 minutes, respectively). A small random amount of additional wait time is added 133 to the supplied maximum `wait` time to spread out the wake up time of any 134 concurrent requests. This adds up to `wait / 16` additional time to the maximum 135 duration. 136 137 ## Consistency Modes 138 139 Most of the read query endpoints support multiple levels of consistency. Since 140 no policy will suit all clients' needs, these consistency modes allow the user 141 to have the ultimate say in how to balance the trade-offs inherent in a 142 distributed system. 143 144 The two read modes are: 145 146 - `default` - If not specified, the default is strongly consistent in almost all 147 cases. However, there is a small window in which a new leader may be elected 148 during which the old leader may service stale values. The trade-off is fast 149 reads but potentially stale values. The condition resulting in stale reads is 150 hard to trigger, and most clients should not need to worry about this case. 151 Also, note that this race condition only applies to reads, not writes. 152 153 - `stale` - This mode allows any server to service the read regardless of 154 whether it is the leader. This means reads can be arbitrarily stale; however, 155 results are generally consistent to within 50 milliseconds of the leader. The 156 trade-off is very fast and scalable reads with a higher likelihood of stale 157 values. Since this mode allows reads without a leader, a cluster that is 158 unavailable will still be able to respond to queries. 159 160 To switch these modes, use the `stale` query parameter on requests. 161 162 To support bounding the acceptable staleness of data, responses provide the 163 `X-Nomad-LastContact` header containing the time in milliseconds that a server 164 was last contacted by the leader node. The `X-Nomad-KnownLeader` header also 165 indicates if there is a known leader. These can be used by clients to gauge the 166 staleness of a result and take appropriate action. 167 168 ## Cross-Region Requests 169 170 By default, any request to the HTTP API will default to the region on which the 171 machine is servicing the request. If the agent runs in "region1", the request 172 will query the region "region1". A target region can be explicitly request using 173 the `?region` query parameter. The request will be transparently forwarded and 174 serviced by a server in the requested region. 175 176 ## Compressed Responses 177 178 The HTTP API will gzip the response if the HTTP request denotes that the client 179 accepts gzip compression. This is achieved by passing the accept encoding: 180 181 ```shell-session 182 $ curl \ 183 --header "Accept-Encoding: gzip" \ 184 https://localhost:4646/v1/... 185 ``` 186 187 ## Formatted JSON Output 188 189 By default, the output of all HTTP API requests is minimized JSON. If the client 190 passes `pretty` on the query string, formatted JSON will be returned. 191 192 In general, clients should prefer a client-side parser like `jq` instead of 193 server-formatted data. Asking the server to format the data takes away 194 processing cycles from more important tasks. 195 196 ```shell-session 197 $ curl https://localhost:4646/v1/page?pretty 198 ``` 199 200 ## HTTP Methods 201 202 Nomad's API aims to be RESTful, although there are some exceptions. The API 203 responds to the standard HTTP verbs GET, PUT, and DELETE. Each API method will 204 clearly document the verb(s) it responds to and the generated response. The same 205 path with different verbs may trigger different behavior. For example: 206 207 ```text 208 PUT /v1/jobs 209 GET /v1/jobs 210 ``` 211 212 Even though these share a path, the `PUT` operation creates a new job whereas 213 the `GET` operation reads all jobs. 214 215 ## HTTP Response Codes 216 217 Individual API's will contain further documentation in the case that more 218 specific response codes are returned but all clients should handle the following: 219 220 - 200 and 204 as success codes. 221 - 400 indicates a validation failure and if a parameter is modified in the 222 request, it could potentially succeed. 223 - 403 marks that the client isn't authenticated for the request. 224 - 404 indicates an unknown resource. 225 - 5xx means that the client should not expect the request to succeed if retried.