octokit / go-octokit Goto Github PK

Faraday does it by default. Makes debugging in tests way easier. I don't know whether this belongs in Octokit or Sawyer; @technoweenie?

From net/http docs:

tr := &http.Transport{
    Proxy: # ???
}
client := &http.Client{Transport: tr}
resp, err := client.Get("https://example.com")

1. http://golang.org/pkg/net/http/#ProxyFromEnvironment
2. http://golang.org/pkg/net/http/#Transport

Revisiting this project after a while , now I can't build it:

$ go get -u . 
package github.com/octokit/go-octokit
    imports github.com/fhs/go-netrc/netrc
    imports github.com/jtacoma/uritemplates
    imports github.com/lostisland/go-sawyer
    imports github.com/lostisland/go-sawyer/hypermedia
    imports github.com/lostisland/go-sawyer/mediatype
    imports github.com/lostisland/go-sawyer/mediaheader
    imports github.com/lostisland/go-sawyer/mediaheader
    imports github.com/lostisland/go-sawyer/mediaheader: cannot find package "github.com/lostisland/go-sawyer/mediaheader" in any of:
    /Users/clint/Developer/Cellar/go/1.2.1/libexec/src/pkg/github.com/lostisland/go-sawyer/mediaheader (from $GOROOT)
    /Users/clint/Projects/Go/src/github.com/lostisland/go-sawyer/mediaheader (from $GOPATH)

Ideas on what I'm doing wrong? I tried updating my copy of gopack, but that throws a panic :/

$ ./gp 
/// g o p a c k ///
updating github.com/fhs/go-netrc/netrc
pointing github.com/fhs/go-netrc/netrc at commit 4422b68c9c934b03e8e53ef18c8c8714542def7e
updating github.com/lostisland/go-sawyer
pointing github.com/lostisland/go-sawyer at commit ec1b99a1915d53f09d40d0c87caf60460b7f8728
updating github.com/bmizerany/assert
pointing github.com/bmizerany/assert at commit e17e99893cb6509f428e1728281c2ad60a6b31e3
panic: runtime error: index out of range

goroutine 1 [running]:
runtime.panic(0x137540, 0x2e1c17)
    /Users/clint/Developer/Cellar/go/1.2.1/libexec/src/pkg/runtime/panic.c:266 +0xb6
main.main()
    /Users/clint/Projects/Go/src/github.com/d2fn/gopack/main.go:50 +0x373

This issue is to track missing relations for GitHub API. See this comment for details.

• https://api.github.com
  • Get a list of users /users{?since}
  • Get pull request /repos/{owner}/{repo}/pulls{/number} (see #17 (comment))

(Related to #119, #31, and maybe #32.)

I'd love to contribute to this project (for the team-related APIs in particular), but it feels like there's a change in the overall design philosophy, and it's not quite elaborated anywhere. In particular, I have questions in a couple of areas:

When/where do specific URLs get used?

There's some inconsistency as to whether URLs should be passed to the "service creator", with One() and All() taking no parameters, or the inverse with no parameters to the service creator, and Hyperlink/param arguments on One() and All(). As a case in point (return values omitted for clarity):

// users...
func (c *Client) Users(url *url.URL) {}  // returns *UsersService
func (u *UsersService) One() {}
func (u *UsersService) All() {}

// repositories
func (c *Client) Repositories() {}   // returns *RepositoriesService
func (r *RepositoriesService) One(uri *Hyperlink, params M) {}
func (r *RepositoriesService) All(uri *Hyperlink, params M) {}

I suspect this simply represents a transition in philosophy: (a) is the service pre-seeded or not, and (b) does it take a URL or Hyperlink/param? Regardless, only one of these patterns should be used, and it ought to be consistent across the package.

Where should multi-resource URLs live? Where should wrapper implementations live?

One of the Team-related APIs is "get a list of team members", which returns a []User. Should the URL live in the users.go file, or in teams.go (which I'm working on)? From the viewpoint of "it returns []User, and is just parameterized URL which eventually gets to Users().All(), you might say it belongs in users.go. But this conflicts with the structure of the GitHub documentation, and of the "natural" feel that it's a Team-related API that "just happens" to return users. If the project is also moving towards a friendlier style of API wrappers (like Teams().GetMembers(nil, M{"id": 123})), then since the wrapper likely lives in the "calling" service, the URL probably should as well.

What about pagination?

Every service seems to have an All() method, but it really only returns one page of results, and doesn't navigate/enumerate the result.NextPage links. I can kind of understand why the methods that take a URL have to be a bit agnostic about this, but it seems like there's a significant use-case for "I want all of the chained repos/users/teams starting from a given URL". In fact, that was my first expectation when I saw the All() methods; it wasn't until I looked at the implementation that I understood they really only return one page of data, not "all" of it. (One might argue that instead of One/All, it should be One/Some/All or One/Page/All where Some() (or Page()) returns a single page of data, and All() accumulates by following the NextPage links.)

A more fluent-style API?

From a programmer-usability standpoint, it seems a little weird to delay knowledge of parameters to the very end of the chain. In the team/members example, if I'm performing several operations on a team, it feels weird to have to remember to pass all of the replacement values at the end. I'd rather be able to do something like:

myTeamId := 123
team := octokit.Teams(myTeamId)
members := team.GetMembers()
managesMyRepo, _ := team.CheckRepository("my-org/my-repo")
if !managesMyRepo {
    team.UpdateRepository("my-org/my-repo", "pull")
}

or even:

success, result := octokit.Teams(123).Repository("my-org/my-repo").Update("pull")

With API wrappers, this is pretty straightforward—GetMembers() and CheckRepository() have a *TeamService as the receiver, and this have access to its properties—but it does impact the way that other values are passed in; perhaps instead of a generic octokit.M, the wrapper functions should take explicit parameters. (I think this makes discoverability much easier for developers new to the API.) Note that the underlying URLs are never passed; they are completely encapsulated by the wrapper methods.

Should this be in CONTRIBUTING.md?

Answers to these questions could live in README.md, but they are really targeted at folks wanting to contribute to the project, so perhaps it makes more sense to add them to CONTRIBUTING.md.

Should I make an entry for this repository on octokit.github.io, or is there a reason it's not on there?

Users should not need to know how go-octokit generates hypermedia urls internally. The fact that people must provide maps with aleatory keys to those methods to call the api is a bad smell. Octokit should provide high level functions to perform every operation. Something like:

client.Repositories().Get("octokit", "go-octokit")
client.Repositories().Fork("octokit", "go-octokit")

And so on.

I'll open a PR soon with a few of those methods, but providing all of them can be a community effort.
Feel free to claim resources that you want to modify yourself commenting in this issue.

TODO:

• Repositories (@calavera)

In Go Modules (GO111MODULE=on), to build octokit become an error.

For example, main.go that is very small Go code below:

package main

import (
    _ "github.com/octokit/go-octokit/octokit"
)

func main() {
}

Then, to build this:

$ GO111MODULE=on go build
go: finding github.com/lostisland/go-sawyer/mediaheader latest
go: finding github.com/lostisland/go-sawyer latest
build lufia.org/test: cannot load github.com/lostisland/go-sawyer/mediaheader: cannot find module providing package github.com/lostisland/go-sawyer/mediaheader

This reason is, because Go Module uses latest tag that is v0.4.0, this is very old broken commit.

I'm trying to hypermediarize the pull request API. But found that in order to provide interfaces like:

client.CreatePullRequest(repo)

I need to go through root -> repository_url -> pulls_url -> POST 4 requets to create a pull request. I'm trying to figure out the best way for hypermedia APIs to work with nested resources. My thoughts are

1. provide a hybrid approach, for nested resources we fall back to manual URL concatenation or
2. root returns all resources' URLs including nested ones, say root -> pulls_url -> POST

@technoweenie @pengwynn How would you guys design it?

First of all, thanks for your interest in GitHub and creating a client library! However, the Octokit name is being used to represent officially supported libraries, so naming this library octokit could mislead users into thinking that it's a project by GitHub.

Would you mind changing the name to something other than Octokit? Thanks!

@pengwynn @jasonrudolph

Hi,

trying to use this for the first time, following the first example:

main.go:

package main

import (
	"fmt"

	"github.com/octokit/go-octokit/octokit"
)

func main() {
	client := octokit.NewClient(nil)

	url, err := octokit.UserURL.Expand(octokit.M{"user": "jingweno"})
	if err != nil {
		// Handle error
	}

	user, result := client.Users(url).One()
	if result.HasError() {
		// Handle error
	}

	fmt.Println(user.ReposURL) // https://api.github.com/users/jingweno/repos
}

Run:

go get github.com/octokit/go-octokit/octokit
github.com/octokit/go-octokit/octokit imports
        github.com/lostisland/go-sawyer/mediaheader: cannot find module providing package github.com/lostisland/go-sawyer/mediaheader

How do I install this module?

• Get a list of users /users{?since}

When you try to create a client to connect to:

github.enterprisecompany.com/api/v3 because of the way the urls are generated it makes requests to
github.enterprisecompany.com/orgs and omits the prefix.

I found the problem here: https://github.com/jingweno/go-sawyer/blob/master/sawyer.go#L51

I guess this happens since it tries to create an absolute url.

I am a 5th year Computer Science student. I completed last summer of code successfully, working in Apache jclouds (a multi-cloud framework). I have experience with REST APIs, and I've been learning Go lately.

I've read the github/gsoc ideas page and this sounds like an exciting project for this summer. I would like some guidance on where to start to get involved and write a proposal for this project.

go-octokit can't get all the issues (included the closed ones), because the All() function doesn't have parameters for the query, Github api's default is to only show the open ones

Reference: #23 (comment)

Getting the following error message on go get

package github.com/lostisland/go-sawyer/mediaheader
    imports github.com/lostisland/go-sawyer/mediaheader
    imports github.com/lostisland/go-sawyer/mediaheader: cannot find package "github.com/lostisland/go-sawyer/mediaheader"

It appears that go-sawyer has changed its structure and the mediaheader folder no longer exists.

I see that a couple of the checkboxes in the TODO section are not checked even though they are implemented. (e.g https://github.com/octokit/go-octokit/blame/master/TODO.md#L82-L87 and https://github.com/octokit/go-octokit/blob/master/octokit/issue_comments.go)

Also, with the discussion on #119 and the PR #120

Are you looking for PRs to close unfinished checks on the TODO with the current API approach or with the new approach? I'd be glad to tackle some of them and I do like the proposal for the new API.

I can't wait to try out go-octokit in gh to make sure I'm building the right thing. Creating an issue here to track to the progress.

Cross reference: owenthereal/gh#92

Hi. I was trying to move off of octokit.rb onto this, but it appears it's very incomplete. I tried to work around it by creating my own client and trying to create requests and do all this and it didn't work due to unexported fields in Request. Obviously I can write the HTTP requests in Go's native net/http package, but it'd be nice to have a package like this that makes things easier.

Is this project still underway?

@pengwynn, I'm curious what your thoughts are on using interfaces for the clients, to make it easier to fake them in unit tests? Currently I have an interface in my service code that proxies to the clients, so I can fake that in my tests. And I can live with that, but I wonder: if the clients themselves had interfaces, would that make life easier for others?