handling custom media types

[willnorris]

A handful of API methods (like issues) support the use of custom mime types to return additional fields in the response, using different formats.

As currently designed, go-github doesn't have a simple way to expose this, since most HTTP-specific details are hidden from the caller. We could probably just add it to the Options parameter for the given method, but that feels a little weird. Additionally, I don't yet have a real use-case for needing to use these custom mime-types. Therefore, I'm currently leaning toward punting on this until someone actually needs it.

So if you need it, please comment here, and we can look at how to work that into the library.

[willnorris]

now that we're using go-querystring to parse the Options structs into query strings, adding custom media types is a bit cleaner, since we can ensure it won't be added as a query param...

type IssueListOptions struct {
    // all the normal fields

    MediaType string `url:"-"`
}

[willnorris]

closing this issue since there isn't really any work to be done at this point. The library already requests the v3 media type for all methods, with an easy way to override that which a few methods do use. If and when we need to expose this to the user, adding it to the Options struct as noted above is the best approach.

[cburmeister]

@willnorris is there a way to specify a media type for GetContents?

client := github.NewClient(tc)
file, _, _, err := client.Repositories.GetContents("username", "repository", "path", nil)

As is the contents are base64 encoded.

[willnorris]

We don't currently expose that for GetContents, but it wouldn't be too hard to add it to the existing RepositoryContentGetOptions... just add a MediaType field like in the example above, then switch on that inside the method to set the Accept header.

Do you wanna take a pass at that?

[parkr]

What about a global toggle for each feature?

github.Enable(github.BetaLicenses)

[willnorris]

@parkr this is a bit different than the media types that are used to enable pre-released APIs. In those cases, we intentionally try to just enable those APIs transparently so that users of the library don't even realize that it's sending a custom media type. So far this has worked well, and we haven't had any conflicts between multiple pre-release APIs running on the same endpoints.

What @cburmeister is asking for though is not a pre-release API, it's just an endpoint that supports responses in JSON, HTML, or raw (and just happens to use media type to indicate which one is preferred). In this case we definitely do want to expose this to users of the library, since the desired response type is generally a conscious decision on the developer's part.

Of course now that I say all this, I realize that we might not simply be able to add MediaType to the Options struct and use the existing method, since the go method expects to return a *RepositoryContent and []*RepositoryContent, which we won't have. Maybe if a custom media type is specified, then we return nil for both of those, and the caller is expected to parse the body of the *Response manually? I don't think there is really any other way to do it, we'll just need to make that clear on the docs for the MediaType field.

[parkr]

Ah! I misunderstood. Thanks for the explanation.

[willnorris]

actually... @cburmeister, have you seen Repositories.DownloadContents? It was just added a couple of weeks ago. If you're mainly interested in the raw contents, It might work better since it handles files over 1 Mb in size (GetContents does not), and has a more straightforward API for just getting the contents of a file. The only downside is that it incurs one additional API roundtrip per call, so may not be suitable for all cases.

[xcoulon]

@willnorris I'm actually looking for a way to pass the Accept header with the application/vnd.github.VERSION.html+json value to retrieve the issues with the body_html field containing the HTML version of body. Is there any way to do that in the current version of go-github, or does this needs an enhancement ?

[dmitshur]

@xcoulon That isn't currently possible, we don't have support for .html+json media type nor body_html fields.

I imagine a solution might look similar to what @willnorris said in #6 (comment), or what we did #481. I'd suggest you look at that, at least to consider it as a starting point. @xcoulon, if you need this functionality, please open a new issue and describe in more detail what exactly you're looking for (and mention this issue for reference).