Re-think HTTP API Documentation

[Mr0grog]

One of the things I called out in the current docs PR (#68) and in the research is the issues around the HTTP API docs (https://ipfs.io/ipfs/QmVUdHfpo9hyC8wXmgd2frRrsp83iRvuL8HWyp1LPzjsPq/reference/api/http/). Virtually every user I’ve talked with finds them to be pretty bad (sometimes entirely unhelpful) and has cheered when shown the interface-ipfs-core “specs,” even though they don’t cover HTTP-specific concerns! Specifically:

• They are way too thin. All the in-depth docs in the Go code (where the HTTP docs are generated) can’t be used because they are very specific to the CLI and would be confusing for HTTP.

• They are specific to the Go implementation (they miss anything that might be unique to js-ipfs; they include without noting the situation things that are unique to go-ipfs)

• They don’t cover changes over time.

I do think it’s helpful that there is a single HTTP API reference and that it’s not buried inside the Go-specific docs because the recommended model for programmatic usage is to treat it like PostgreSQL or Redis, where it should run as a separate process locally. So I don’t think the right solution is to generate implementation- and version-specific docs and put them alongside the js-ipfs and go-ipfs docs.

I see two possible solutions here:

1. Maintain HTTP API docs separately, by hand, rather than generating them from go-ipfs.

   • Upside: it’s all in one place and not repeated; it’s specific to the HTTP use case.
   • Downside: the docs are no longer in/alongside the code. It’s a lot more effort to update. It requires more coordination between Go and JS teams.

2. Add a LongHttpDescription field to cmdkit.HelpText in Go and some similar way of generating HTTP API docs from js-ipfs. Generate implementation- and version-specific HTTP API docs for each and put them in the “JS Implementation” and “Go Implementation” sections of the docs site. Keep a top-level one that is just a copy of the current release version of the Go HTTP docs, but make sure it includes links to the HTTP docs for all the other versions/implementations.

   • Upside: docs are stored alongside the code; it’s easier for people to maintain and keep up-to-date as part of their regular coding work and harder to get out of sync with the implementation; it’s easier to let the JS parts be JS-specific and same for Go.
   • Downside: the vast majority of content will be duplicated and it’s a lot of manual work to make sure the two implementation’s inline docs stay in sync (but we are more-or-less already doing it with CLI help text). We have to invent whole new structures in the tooling for it — in both implementations.

I propose doing # 1. It is less technologically savvy, but makes it easier to separate HTTP-specific concerns and to play with various ways of documenting things. Does anybody have strong opinions about either (or a different, better idea)?

/cc @daviddias @alanshaw @whyrusleeping @Stebalien

[Mr0grog]

Pulling in @olizilla’s comment from #68:

A useful http api doc would be accurate for a given implementation and version, so you know exactly what to expect. Ideally it should let you diff any differences between versions. being able to diff between implementations at given versions would be super rad. Something like: http://apidocjs.com/ (example docs: http://apidocjs.com/example/) could work for creating versioned, generated docs.

If we go the other route and create a separate, hand crafted api documentation, then it would be most useful if it was in the form of an api spec, that we could then use to show where each impl complies and drifts from the ideal. Somthing like Swagger / openAPI / RAML. I'd go for that over hand crafted html api docs; I think they'd just be different again, and probably out of date, and not programatically verifiable without a lot of bespoke work.

[Mr0grog]

Something like: http://apidocjs.com/ (example docs: http://apidocjs.com/example/) could work for creating versioned, generated docs

Oh, that’s neat! I wonder if there is anything similar that can do diffs for OpenAPI (it feels a little more standard, which I like, and has a decent ecosystem of tools around it, but is certainly not perfect).

I'd go for that over hand crafted html api docs; I think they'd just be different again, and probably out of date, and not programatically verifiable without a lot of bespoke work.

Yeah, to be clear, I wasn’t thinking a manually written doc needed be written in HTML and not one of these :)

Good point about a structured format making it programmatically verifiable.

It would be most useful if it was in the form of an api spec, that we could then use to show where each impl complies and drifts from the ideal.

I don’t know if it needs or even should be though of as a specification (depends a lot on how you interpret that word), but seeing and comparing both implementations in one place is one of the major advantages I was thinking of here.

[Mr0grog]

Yeah, to be clear, I wasn’t thinking a manually written doc needed be written in HTML and not one of these :)

That said, I think it’s really critical that whatever format we use makes it easy to include copious explanatory text and multiple examples. These are the things people have problems with in the current version. It’s explanations don’t say much and its examples aren’t really examples.

(My previous experiences with OpenAPI was that having a lot of that felt kinda cramped inside the YAML structure and the standard templates don’t always provide good markup parsing for the content.)

[daviddias]

Just adding bits of context here for things that we have explored and problems that we have identified:

• Previous attempt on writing the spec manually - https://github.com/ipfs/http-api-spec
• Many of the issues with the HTTP API implementation itself https://github.com/ipfs/http-api-spec/issues
• The problems of the HTTP API, HTTP API Spec and discussions around it https://github.com/ipfs/http-api-spec/issues/116 (circa aug 2016)