5.1 Making Requests

Function: ghub-request method resource &optional params &key query payload headers unpaginate noerror reader username auth host callback errorback url value error extra method*

This function makes a request for RESOURCE using METHOD. PARAMS, QUERY, PAYLOAD and/or HEADERS are alists holding additional request data. The response body is returned and the response headers are stored in the variable ghub-response-headers.

• METHOD is the HTTP method, given as a string.
• RESOURCE is the resource to access, given as a string beginning with a slash.
• PARAMS, QUERY, PAYLOAD and HEADERS are alists and are used to specify request data. All these arguments are alists that resemble the JSON expected and returned by the Github API. The keys are symbols and the values stored in the cdr (not the cadr) can be strings, integers, or lists of strings and integers.

  The Github API documentation is vague on how data has to be transmitted and for a particular resource usually just talks about "parameters". Generally speaking when the METHOD is "HEAD" or "GET", then they have to be transmitted as a query, otherwise as a payload.

  • Use PARAMS to automatically transmit like QUERY or PAYLOAD would depending on METHOD.
  • Use QUERY to explicitly transmit data as a query.
  • Use PAYLOAD to explicitly transmit data as a payload. Instead of an alist, PAYLOAD may also be a string, in which case it gets encoded as UTF-8 but is otherwise transmitted as-is.
  • Use HEADERS for those rare resources that require that the data is transmitted as headers instead of as a query or payload. When that is the case, then the Github API documentation usually mentions it explicitly.
• If SILENT is non-nil, then progress reports and the like are not messaged.
• If UNPAGINATE is t, then this function makes as many requests as necessary to get all values. If UNPAGINATE is a natural number, then it gets at most that many pages. For any other non-nil value it raises an error.
• If NOERROR is non-nil, then no error is raised if the request fails and nil is returned instead. If NOERROR is return, then the error payload is returned instead of nil.
• If READER is non-nil, then it is used to read and return from the response buffer. The default is ghub--read-json-payload. For the very few resources that do not return JSON, you might want to use ghub--decode-payload.
• If USERNAME is non-nil, then the request is made on behalf of that user. It is better to specify the user using the Git variable github.user for "api.github.com", or github.HOST.user if connecting to a Github Enterprise instance.
• Each package that uses Ghub should use its own token. If AUTH is nil or unspecified, then the generic ghub token is used instead. This is only acceptable for personal utilities. A package that is distributed to other users should always use this argument to identify itself, using a symbol matching its name.

  Package authors who find this inconvenient should write a wrapper around this function and possibly for the method-specific functions as well.

  Beside nil, some other symbols have a special meaning too. none means to make an unauthorized request. basic means to make a password based request. If the value is a string, then it is assumed to be a valid token. basic and an explicit token string are only intended for internal and debugging uses.

  If AUTH is a package symbol, then the scopes are specified using the variable AUTH-github-token-scopes. It is an error if that is not specified. See ghub-github-token-scopes for an example.

• If HOST is non-nil, then connect to that Github instance. This defaults to "api.github.com". When a repository is connected to a Github Enterprise instance, then it is better to specify that using the Git variable github.host instead of using this argument.
• If FORGE is gitlab, then connect to Gitlab.com or, depending on HOST, to another Gitlab instance. This is only intended for internal use. Instead of using this argument you should use function glab-request and other glab-* functions.
• If CALLBACK and/or ERRORBACK is non-nil, then this function makes one or more asynchronous requests and calls CALLBACK or ERRORBACK when finished. If no error occurred, then it calls CALLBACK, unless that is nil.

  If an error occurred, then it calls ERRORBACK, or if that is nil, then CALLBACK. ERRORBACK can also be t, in which case it signals instead. NOERROR is ignored for all asynchronous requests.

  Both callbacks are called with four arguments.

  • For CALLBACK, the combined value of the retrieved pages. For ERRORBACK, the error that occurred when retrieving the last page.
  • The headers of the last page as an alist.
  • Status information provided by url-retrieve. Its :error property holds the same information as the first argument to ERRORBACK.
  • A ghub--req struct, which can be passed to ghub-continue (which see) to retrieve the next page, if any.

Function: ghub-continue args

If there is a next page, then this function retrieves that.

This function is only intended to be called from callbacks. If there is a next page, then that is retrieved and the buffer that the result will be loaded into is returned, or t if the process has already completed. If there is no next page, then return nil.

Callbacks are called with four arguments (see ghub-request). The forth argument is a ghub--req struct, intended to be passed to this function. A callback may use the struct’s extra slot to pass additional information to the callback that will be called after the next request. Use the function ghub-req-extra to get and set the value of that slot.

As an example, using ghub-continue in a callback like so:

(ghub-get "/users/tarsius/repos" nil
          :callback (lambda (value _headers _status req)
                      (unless (ghub-continue req)
                        (setq my-value value))))

is equivalent to:

(ghub-get "/users/tarsius/repos" nil
          :unpaginate t
          :callback (lambda (value _headers _status _req)
                      (setq my-value value)))

To demonstrate how to pass information from one callback to the next, here we record when we start fetching each page:

(ghub-get "/users/tarsius/repos" nil
          :extra (list (current-time))
          :callback (lambda (value _headers _status req)
                      (push (current-time) (ghub-req-extra req))
                      (unless (ghub-continue req)
                        (setq my-times (ghub-req-extra req))
                        (setq my-value value))))

Variable: ghub-response-headers

A select few Github API resources respond by transmitting data in the response header instead of in the response body. Because there are so few of these inconsistencies, ghub-request always returns the response body.

To access the response headers use this variable after ghub-request has returned.

Function: ghub-response-link-relations req headers payload

This function returns an alist of the link relations in HEADERS, or if optional HEADERS is nil, then those in ghub-response-headers.

When accessing a Bitbucket instance then the link relations are in PAYLOAD instead of HEADERS, making their API merely RESTish and forcing this function to append those relations to the value of ghub-response-headers, for later use when this function is called with nil for PAYLOAD.

Variable: ghub-override-system-name

If non-nil, the value of this variable is used to override the value returned by system-name for the purpose of identifying the local machine, which is necessary because Ghub uses separate tokens for each machine. Also see Configuration Variables.

Variable: ghub-github-token-scopes

Variable: PACKAGE-github-token-scopes

Such a variable defines the token scopes requested by the respective package PACKAGE given by the first word in the variable name. ghub itself is treated like any other package. Also see Using Ghub in a Package.

Function: ghub-head resource &optional params &key query payload headers unpaginate noerror reader username auth host callback errorback

Function: ghub-get resource &optional params &key query payload headers unpaginate noerror reader username auth host callback errorback

These functions are simple wrappers around ghub-request. Their signature is identical to that of the latter, except that they do not have an argument named METHOD. The HTTP method is instead given by the second word in the function name.

As described in the documentation for ghub-request, it depends on the used method whether the value of the PARAMS argument is used as the query or the payload. For the "HEAD" and "GET" methods it is used as the query.

Function: ghub-put resource &optional params &key query payload headers unpaginate noerror reader username auth host callback errorback

Function: ghub-post resource &optional params &key query payload headers unpaginate noerror reader username auth host callback errorback

Function: ghub-patch resource &optional params &key query payload headers unpaginate noerror reader username auth host callback errorback

Function: ghub-delete resource &optional params &key query payload headers unpaginate noerror reader username auth host callback errorback

These functions are simple wrappers around ghub-request. Their signature is identical to that of the latter, except that they do not have an argument named METHOD. The HTTP method is instead given by the second word in the function name.

As described in the documentation for ghub-request, it depends on the used method whether the value of the PARAMS argument is used as the query or the payload. For the "PUT", "POST", "PATCH" and "DELETE" methods it is used as the payload.

Function: ghub-wait resource &optional duration &key username auth host

Some API requests result in an immediate successful response even when the requested action has not actually been carried out yet. An example is the request for the creation of a new repository, which doesn’t cause the repository to immediately become available. The Github API documentation usually mentions this when describing an affected resource.

If you want to do something with some resource right after making a request for its creation, then you might have to wait for it to actually be created. This function can be used to do so. It repeatedly tries to access the resource until it becomes available or until a timeout is reached. In the latter case it signals ghub-error.

RESOURCE specifies the resource that this function waits for.

DURATION specifies the maximum number of seconds to wait for, defaulting to 64 seconds. Emacs will block during that time, but the user can abort using C-g.

The first attempt is made immediately and will often succeed. If not, then another attempt is made after two seconds, and each subsequent attempt is made after waiting as long as we already waited between all preceding attempts combined.

See ghub-request’s documentation above for information about the other arguments.

Function: ghub-graphql graphql &optional variables &key username auth host callback

This function makes a GraphQL request using GRAPHQL and VARIABLES as inputs. GRAPHQL is a GraphQL string. VARIABLES is a JSON-like alist. The other arguments behave as for ghub-request (which see).

The response is returned as a JSON-like alist. Even if the response contains errors, this function does not raise an error. Cursor-handling is likewise left to the caller.