github.com/dkerwin/nomad@v0.3.3-0.20160525181927-74554135514b/website/source/docs/http/index.html.md (about)

     1  ---
     2  layout: "http"
     3  page_title: "HTTP API"
     4  sidebar_current: "docs-http-overview"
     5  description: |-
     6    Nomad has an HTTP API that can be used to programmatically use Nomad.
     7  ---
     8  
     9  # HTTP API
    10  
    11  The Nomad HTTP API is the primary interface to using Nomad, and is used
    12  to query the current state of the system as well as to modify it.
    13  The Nomad CLI makes use of the Go HTTP client and invokes the HTTP API.
    14  
    15  All API routes are prefixed with `/v1/`. This documentation is only for the v1 API.
    16  
    17  ## Data Model and API Layout
    18  
    19  There are four primary "nouns" in Nomad, these are jobs, nodes, allocations, and evaluations:
    20  
    21  [![Nomad Data Model](/assets/images/nomad-data-model.png)](/assets/images/nomad-data-model.png)
    22  
    23  Jobs are submitted by users and represent a _desired state_. A job is a declarative description
    24  of tasks to run which are bounded by constraints and require resources. Nodes are the servers
    25  in the clusters that tasks can be scheduled on. The mapping of tasks in a job to nodes is done
    26  using allocations. An allocation is used to declare that a set of tasks in a job should be run
    27  on a particular node. Scheduling is the process of determining the appropriate allocations and
    28  is done as part of an evaluation.
    29  
    30  The API is modeled closely on the underlying data model. Use the links to the left for
    31  documentation about specific endpoints. There are also "Agent" APIs which interact with
    32  a specific agent and not the broader cluster used for administration.
    33  
    34  <a name="blocking-queries"></a>
    35  ## Blocking Queries
    36  
    37  Certain endpoints support a feature called a "blocking query." A blocking query
    38  is used to wait for a potential change using long polling.
    39  
    40  Not all endpoints support blocking, but those that do are clearly designated in
    41  the documentation. Any endpoint that supports blocking will set the HTTP header
    42  `X-Nomad-Index`, a unique identifier representing the current state of the
    43  requested resource. On subsequent requests for this resource, the client can set
    44  the `index` query string parameter to the value of `X-Nomad-Index`, indicating
    45  that the client wishes to wait for any changes subsequent to that index.
    46  
    47  In addition to `index`, endpoints that support blocking will also honor a `wait`
    48  parameter specifying a maximum duration for the blocking request. This is limited to
    49  10 minutes. If not set, the wait time defaults to 5 minutes. This value can be specified
    50  in the form of "10s" or "5m" (i.e., 10 seconds or 5 minutes, respectively).
    51  
    52  A critical note is that the return of a blocking request is **no guarantee** of a change. It
    53  is possible that the timeout was reached or that there was an idempotent write that does
    54  not affect the result of the query.
    55  
    56  ## Consistency Modes
    57  
    58  Most of the read query endpoints support multiple levels of consistency. Since no policy will
    59  suit all clients' needs, these consistency modes allow the user to have the ultimate say in
    60  how to balance the trade-offs inherent in a distributed system.
    61  
    62  The two read modes are:
    63  
    64  * default - If not specified, the default is strongly consistent in almost all cases. However,
    65    there is a small window in which a new leader may be elected during which the old leader may
    66    service stale values. The trade-off is fast reads but potentially stale values. The condition
    67    resulting in stale reads is hard to trigger, and most clients should not need to worry about
    68    this case.  Also, note that this race condition only applies to reads, not writes.
    69  
    70  * stale - This mode allows any server to service the read regardless of whether
    71    it is the leader. This means reads can be arbitrarily stale; however, results are generally
    72    consistent to within 50 milliseconds of the leader. The trade-off is very fast and
    73    scalable reads with a higher likelihood of stale values. Since this mode allows reads without
    74    a leader, a cluster that is unavailable will still be able to respond to queries.
    75  
    76  To switch these modes, use the `stale` query parameter on request.
    77  
    78  To support bounding the acceptable staleness of data, responses provide the `X-Nomad-LastContact`
    79  header containing the time in milliseconds that a server was last contacted by the leader node.
    80  The `X-Nomad-KnownLeader` header also indicates if there is a known leader. These can be used
    81  by clients to gauge the staleness of a result and take appropriate action.
    82  
    83  ## Cross-Region Requests
    84  
    85  By default any request to the HTTP API is assumed to pertain to the region of the machine
    86  servicing the request. A target region can be explicitly specified with the `region` query
    87  parameter. The request will be transparently forwarded and serviced by a server in the
    88  appropriate region.
    89  
    90  ## Compressed Responses
    91  
    92  The HTTP API will gzip the response if the HTTP request denotes that the client accepts
    93  gzip compression. This is achieved via the standard, `Accept-Encoding: gzip`
    94  
    95  ## Formatted JSON Output
    96  
    97  By default, the output of all HTTP API requests is minimized JSON.  If the client passes `pretty`
    98  on the query string, formatted JSON will be returned.