Generic REST access. Any GitHub REST path is reachable through get/3,
post/3, patch/3, put/3, and delete/3.
Every call returns {:ok, body, meta} on a 2xx or {:error, reason} otherwise,
where reason is a GhEx.Error for an API error response or a Req exception for
a transport failure. meta is a GhEx.REST.Meta struct carrying the status,
response headers, parsed pagination links, and rate-limit snapshot.
Options
Per-call options are passed through to Req, so the useful ones are:
:params- query string parameters, e.g.params: [state: "open", per_page: 100]:json- a body to JSON-encode forpost/patch/put
Examples
GhEx.REST.get(client, "/repos/elixir-lang/elixir")
GhEx.REST.get(client, "/repos/o/r/issues", params: [state: "open"])
GhEx.REST.post(client, "/repos/o/r/issues", json: %{title: "Bug", body: "..."})Summary
Functions
Issues a DELETE.
Issues a GET.
Issues a PATCH.
Issues a POST.
Issues a PUT.
Runs a request and returns the raw Req.Response, without normalizing it.
Auto-paginates a list endpoint into a lazy Stream of individual items.
Types
@type meta() :: GhEx.REST.Meta.t()
@type result() :: {:ok, term(), meta()} | {:error, GhEx.Error.t() | Exception.t()}
Functions
@spec delete(GhEx.Client.t(), String.t(), keyword()) :: result()
Issues a DELETE.
@spec get(GhEx.Client.t(), String.t(), keyword()) :: result()
Issues a GET.
@spec patch(GhEx.Client.t(), String.t(), keyword()) :: result()
Issues a PATCH.
@spec post(GhEx.Client.t(), String.t(), keyword()) :: result()
Issues a POST.
@spec put(GhEx.Client.t(), String.t(), keyword()) :: result()
Issues a PUT.
@spec raw(GhEx.Client.t(), atom(), String.t(), keyword()) :: {:ok, Req.Response.t()} | {:error, term()}
Runs a request and returns the raw Req.Response, without normalizing it.
Unlike the verb functions, a non-2xx response comes back as
{:ok, %Req.Response{}} (inspect resp.status yourself) rather than
{:error, _}. Useful when a 404 means "absent" rather than an error, or when
you need the raw status, headers, or body, or custom decoding. Auth resolution
can still fail, returning {:error, reason}. Compose with
GhEx.Pagination.links/1 and GhEx.RateLimit.from_response/1 for links or a
rate-limit snapshot.
@spec stream(GhEx.Client.t(), String.t(), keyword()) :: Enumerable.t()
Auto-paginates a list endpoint into a lazy Stream of individual items.
Follows the Link: rel="next" header until GitHub stops handing one back.
The first page's :params are applied once; subsequent pages use the exact
next URL GitHub returns, so cursors are never double-applied. A failed page
raises GhEx.Error.
client
|> GhEx.REST.stream("/repos/elixir-lang/elixir/issues", params: [state: "all", per_page: 100])
|> Stream.map(& &1["number"])
|> Enum.take(250)