Next: , Up: API   [Contents]


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.

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.


Next: , Up: API   [Contents]