Implemented a program to audit existing APIs

[dhruvsinghal]

@pengwynn Here's a very rough version of the API audit program. Some notes:

• I could not use reflection for getting all the URLs because there is no way to reflect on what is present in a Go package.
• This program uses regexes to extract the URLs declared in the non-test source files. As such it makes a few assumptions about where the files are, where the URL is defined, etc.
• I found a few inconsistencies (as per my judgement) in the way the template URLs are defined in the Go API versus as they are presented at https://api.github.com/, which I have marked with **. Of the items I have marked, the most prominent issue seems to be that the API is missing type, page, per_page and sort parameters.

Here's the output of the script:

29 APIs found on https://api.github.com/.
14 APIs implementations found.

Existing APIs:
repos/{owner}/{repo}
user
emojis
gists{/gist_id}

Unaccounted APIs:
repos/{owner}/{repo}/pulls{/number}
repos/{owner}/{repo}/releases{/id}
repos/{owner}/{repo}/forks
orgs/{org}/repos
repos/{owner}/{repo}/commits{/sha}
repos/{owner}/{repo}/issues{/number}
user/repos
repos/{owner}/{repo}/statuses/{ref}
**users{/user}
authorizations{/id}

Missing APIs:
notifications
feeds
teams
hub
**users/{user}/repos{?type,page,per_page,sort}
**user/repos{?type,page,per_page,sort}
orgs/{org}
user/starred{/owner}{/repo}
authorizations
user/emails
issues
search/repositories?q={query}{&page,per_page,sort,order}
**orgs/{org}/repos{?type,page,per_page,sort}
search/issues?q={query}{&page,per_page,sort,order}
**users/{user}
search/users?q={query}{&page,per_page,sort,order}
search/code?q={query}{&page,per_page,sort,order}
user/keys
ings/connections/applications{/client_id}
gists/starred
events
user/orgs
rate_limit
gists/public
user/following{/target}

[pengwynn]

Very nifty, @dhruvsinghal. I love the output format. :sparkles:

After thinking about this, I think we'll need to expand our audit a bit. Some API methods use the same URL with different HTTP verbs. The approach we used in Octokit.rb was to match on documentation URLs. With the work @dhs252 is doing in #78, I think we can do the same thing here.

I was able to compile a list of all documentation URLs from the Ruby library with this shell command:

ag --no-numbers "@see https://developer.github.com/v3" | sed -ne 's/.*\(http[^"]*\).*/\1/p' | sort -u

Based on the output of this script, we could create a TODO.md in the project root using the task list syntax. The auditor could then just complete the ones it finds marked See <url> in our *.go files, perhaps entirely in bash.

[dhruvsinghal]

@pengwynn The audit script is complete and functional. Just run go script/auditor.go

@dannysperling I've pulled in changes from your fork's doc-links branch, so you might want to work with this (audit) branch itself for any updates to documentation.

[pengwynn]

@dhruvsinghal I'm getting an error running it:

❯ go run auditor.go
panic: open auth_method.go: no such file or directory

[dhruvsinghal]

@pengwynn It should work now.

[feiranchen]

Hmmm in the TODO.md, it seems like only the bigger categories are getting checked off.

For example the search is checked off: https://developer.github.com/v3/search

All the below aren't checked off: https://developer.github.com/v3/search/#search-code https://developer.github.com/v3/search/#search-issues https://developer.github.com/v3/search/#search-repositories https://developer.github.com/v3/search/#search-users

I know for a fact that all the above are implemented.

Shall we bring this back? @dhruvsinghal @pengwynn

[dhruvsinghal]

@feiranchen The code documentation is incomplete actually: it should include "https://developer.github.com/v3/search/#search-code" explicitly. The script does not have natural language processing capabilities yet :)

[feiranchen]

Hmm, just found another example: https://github.com/octokit/go-octokit/blob/master/octokit/gists.go

The file is very well documented thanks to @dannysperling. Yet none of the sub-functions are marked in TODO.md. I just ran the auditor locally to be sure.

[dhruvsinghal]

@feiranchen Fixed and merged.