Prepare for a Typed Octokat

[philschatz]

Many responses from GitHub's API yield JSON that describes a User but are missing the name: field (see below for a partial list).

This Pull Request changes the API interface to match that expectation.

This work is part of philschatz/octokat.js#176 (add TypeScript Definitions) and refs #1522 and #1281

To verify that these are the only changes needed, I plugged the octokat/index.d.ts file into Desktop and ran the CI tests. Here is a branch of that work: philschatz/desktop@master...philschatz:octokat-typescript-example

---

GitHub API Routes and User Objects

The following routes yield a User with a name: field in the Response JSON:

GET /users/:username yields a 'UserWithName'
GET /user yields a 'UserWithName'

The following routes (39) yield a User that does not contain the name: field in the Response JSON:

• GET /repos/:owner/:repo (click to see the API Response)
• GET /repos/:owner/:repo/issues/events
• GET /repos/:owner/:repo/issues
• GET /repos/:owner/:repo/pulls/:pull_request_number
• GET /repos/:owner/:repo

[Click me] to see all the routes...

GET /repos/:owner/:repo/issues/events
GET /users/:username/starred
GET /user/starred
GET /repos/:owner/:repo/subscribers
GET /issues
GET /repos/:owner/:repo/issues
GET /repos/:owner/:repo/issues/:issue_number
GET /repos/:owner/:repo/assignees
GET /repos/:owner/:repo/issues/:issue_number/comments
GET /repos/:owner/:repo/issues/comments
GET /repos/:owner/:repo/issues/comments/:issue_comment_id
GET /repos/:owner/:repo/issues/:issue_number/events
GET /repos/:owner/:repo/issues/events
GET /repos/:owner/:repo/pulls/:pull_request_number
GET /repos/:owner/:repo/pulls/:pull_request_number/commits
GET /repos/:owner/:repo/pulls/:pull_request_number/reviews
GET /repos/:owner/:repo/pulls/:pull_request_number/reviews/:review_id
GET /repos/:owner/:repo/pulls/:pull_request_number/reviews/:review_id/comments
GET /repos/:owner/:repo/pulls/:pull_request_number/comments
GET /repos/:owner/:repo/pulls/comments
GET /user/repos
GET /users/:username/repos
GET /repositories/:repository_id
GET /repos/:owner/:repo
GET /repos/:owner/:repo/collaborators
GET /repos/:owner/:repo/collaborators/:username/permission
GET /repos/:owner/:repo/comments
GET /repos/:owner/:repo/commits/:commit_sha/comments
GET /repos/:owner/:repo/comments/:repo_comment_id
GET /repos/:owner/:repo/commits
GET /repos/:owner/:repo/commits/:commit_sha
GET /repos/:owner/:repo/deployments
GET /repos/:owner/:repo/pages/builds
GET /repos/:owner/:repo/pages/builds/latest
GET /users
GET /users/:username/followers
GET /user/followers
GET /users/:username/following
GET /user/following

[philschatz]

Some notes on the proposed changes

[joshaber]

Thanks @philschatz! It's awesome you're looking into providing typings!

I'm a little concerned about the knock-on effects of making name optional everywhere. I imagine we should split it into two types so we're clear about where we can rely on name and where we can't.

[philschatz]

Thanks for the feedback!

I split the IAPIUser type into 3:

• IAPIUserNoName used when searching for users by email, or as part of an IAPICommit (to update the user store cache)
• IAPIUserWithName used when getting the current user
• IAPIOrganizationSlug used when getting the list of the current users' Organizations

As a result, the User autocomplete no longer tries to show the user name (it did not work before anyway).

Aside: I tend to be extra-verbose so it is easier to replace the names later but can rename them to something shorter like IAPIOrgSlug, IAPIUserSlug, and IAPIUser.

[joshaber]

Thanks @philschatz! We're getting close:

As a result, the User autocomplete no longer tries to show the user name (it did not work before anyway).

It seems to be working for me currently, or maybe I'm misunderstanding?

[niik]

Thanks for all your work here @philschatz! I'm personally really excited to see a strongly typed Octokat!

With #2080 moving us over to issuing API requests manually I'm going to close this PR.