github.com/smintz/nomad@v0.8.3/website/source/api/index.html.md (about)

     1  ---
     2  layout: api
     3  page_title: HTTP API
     4  sidebar_current: 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 & 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  ```text
    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  [![Nomad Data Model](/assets/images/nomad-data-model.png)](/assets/images/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. Nodes are the servers in the clusters that tasks can be
    63  scheduled on. The mapping of tasks in a job to nodes is done using allocations.
    64  An allocation is used to declare that a set of tasks in a job should be run on a
    65  particular node. Scheduling is the process of determining the appropriate
    66  allocations and is done as part of an evaluation. Deployments are objects to
    67  track a rolling update of allocations between two versions of a job.
    68  
    69  The API is modeled closely on the underlying data model. Use the links to the
    70  left for documentation about specific endpoints. There are also "Agent" APIs
    71  which interact with a specific agent and not the broader cluster used for
    72  administration.
    73  
    74  ## ACLs
    75  
    76  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.
    77  
    78  For more details about ACLs, please see the [ACL Guide](/guides/acl.html).
    79  
    80  ## Authentication
    81  
    82  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.
    83  
    84  Here is an example using curl:
    85  
    86  ```text
    87  $ curl \
    88      --header "X-Nomad-Token: aa534e09-6a07-0a45-2295-a7f77063d429" \
    89      https://localhost:4646/v1/jobs
    90  ```
    91  
    92  ## Blocking Queries
    93  
    94  Many endpoints in Nomad support a feature known as "blocking queries". A
    95  blocking query is used to wait for a potential change using long polling. Not
    96  all endpoints support blocking, but each endpoint uniquely documents its support
    97  for blocking queries in the documentation.
    98  
    99  Endpoints that support blocking queries return an HTTP header named
   100  `X-Nomad-Index`. This is a unique identifier representing the current state of
   101  the requested resource.
   102  
   103  On subsequent requests for this resource, the client can set the `index` query
   104  string parameter to the value of `X-Nomad-Index`, indicating that the client
   105  wishes to wait for any changes subsequent to that index.
   106  
   107  When this is provided, the HTTP request will "hang" until a change in the system
   108  occurs, or the maximum timeout is reached. A critical note is that the return of
   109  a blocking request is **no guarantee** of a change. It is possible that the
   110  timeout was reached or that there was an idempotent write that does not affect
   111  the result of the query.
   112  
   113  In addition to `index`, endpoints that support blocking will also honor a `wait`
   114  parameter specifying a maximum duration for the blocking request. This is
   115  limited to 10 minutes. If not set, the wait time defaults to 5 minutes. This
   116  value can be specified in the form of "10s" or "5m" (i.e., 10 seconds or 5
   117  minutes, respectively). A small random amount of additional wait time is added
   118  to the supplied maximum `wait` time to spread out the wake up time of any
   119  concurrent requests. This adds up to `wait / 16` additional time to the maximum
   120  duration.
   121  
   122  ## Consistency Modes
   123  
   124  Most of the read query endpoints support multiple levels of consistency. Since
   125  no policy will suit all clients' needs, these consistency modes allow the user
   126  to have the ultimate say in how to balance the trade-offs inherent in a
   127  distributed system.
   128  
   129  The two read modes are:
   130  
   131  - `default` - If not specified, the default is strongly consistent in almost all
   132    cases. However, there is a small window in which a new leader may be elected
   133    during which the old leader may service stale values. The trade-off is fast
   134    reads but potentially stale values. The condition resulting in stale reads is
   135    hard to trigger, and most clients should not need to worry about this case.
   136    Also, note that this race condition only applies to reads, not writes.
   137  
   138  - `stale` - This mode allows any server to service the read regardless of
   139    whether it is the leader. This means reads can be arbitrarily stale; however,
   140    results are generally consistent to within 50 milliseconds of the leader. The
   141    trade-off is very fast and scalable reads with a higher likelihood of stale
   142    values. Since this mode allows reads without a leader, a cluster that is
   143    unavailable will still be able to respond to queries.
   144  
   145  To switch these modes, use the `stale` query parameter on requests.
   146  
   147  To support bounding the acceptable staleness of data, responses provide the
   148  `X-Nomad-LastContact` header containing the time in milliseconds that a server
   149  was last contacted by the leader node. The `X-Nomad-KnownLeader` header also
   150  indicates if there is a known leader. These can be used by clients to gauge the
   151  staleness of a result and take appropriate action.
   152  
   153  ## Cross-Region Requests
   154  
   155  By default, any request to the HTTP API will default to the region on which the
   156  machine is servicing the request. If the agent runs in "region1", the request
   157  will query the region "region1". A target region can be explicitly request using
   158  the `?region` query parameter. The request will be transparently forwarded and
   159  serviced by a server in the requested region.
   160  
   161  ## Compressed Responses
   162  
   163  The HTTP API will gzip the response if the HTTP request denotes that the client
   164  accepts gzip compression. This is achieved by passing the accept encoding:
   165  
   166  ```
   167  $ curl \
   168      --header "Accept-Encoding: gzip" \
   169      https://localhost:4646/v1/...
   170  ```
   171  
   172  ## Formatted JSON Output
   173  
   174  By default, the output of all HTTP API requests is minimized JSON. If the client
   175  passes `pretty` on the query string, formatted JSON will be returned.
   176  
   177  In general, clients should prefer a client-side parser like `jq` instead of
   178  server-formatted data. Asking the server to format the data takes away
   179  processing cycles from more important tasks.
   180  
   181  ```
   182  $ curl https://localhost:4646/v1/page?pretty
   183  ```
   184  
   185  ## HTTP Methods
   186  
   187  Nomad's API aims to be RESTful, although there are some exceptions. The API
   188  responds to the standard HTTP verbs GET, PUT, and DELETE. Each API method will
   189  clearly document the verb(s) it responds to and the generated response. The same
   190  path with different verbs may trigger different behavior. For example:
   191  
   192  ```text
   193  PUT /v1/jobs
   194  GET /v1/jobs
   195  ```
   196  
   197  Even though these share a path, the `PUT` operation creates a new job whereas
   198  the `GET` operation reads all jobs.