ReSpec vs Bikeshed: How to document and publish a standard REST API interface to be implemented by a number of vendors?

Question

We want to document a standard REST API interface which will be implemented by a number of vendors. Currently we are using Google Docs to store the specification.

Requirements (which must be common to most):

• Spec history: We want to be able to reference previous versions of the specification.
• Version control: We want to store the spec in version control, so that we can tag versions against our codebase and store it alongside the related
• Issues: We want to allow the community to submit issues.
• Community / Affiliation: We want to share the specification with a broader community, to receive validation on our approach. endpoint validator.
• Format / Tooling: We want to use a format that is easy to edit, and also publishable into an easy-to-understand form.
• Potential ratification: If it's useful, it would be good to create a standard where there's a pathway for it becoming more widely adopted.

From a little research there are a few relevant standards bodies:

• IETF (Internet Engineering Task Force): Mostly use the text-based RFC format, but seem to have some nice tracking tools. Generally for lower-level standards (e.g. TCP), though they've created higher level ones too.

• W3C (World Wide Web Consortium): If we are publishing through the W3C eventually, it looks like we'll need to conform to pubrules.

• WHATWG (Web Hypertext Application Technology Working Group): A group that appears to focus mainly on HTML5, so less relevant for a REST API spec.

• OASIS (Organization for the Advancement of Structured Information Standards): Seems to be more about business abstractions on top of IETF / W3C standards.

I have looked at a few examples over the web, and note a difference of approaches:

• YAML: spec history, versioned in GitHub, issues on GitHub, no apparent affiliation, uses DocBook.

• JSON-LD: spec history, versioned in GitHub, issues on GitHub, W3C affiliation, uses ReSpec (also on GitHub).

• JSON API: spec history, versioned in GitHub, issues on GitHub, no apparent affiliation, appears to use Jekyll and some custom templates.

• JMAP: versioned in GitHub, issues on GitHub, no apparent affiliation, appears to use markdown and some custom templates.

• HTML 5 (W3C): versioned in GitHub, issues on GitHub, W3C affiliation, uses Bikeshed.

• HTML 5 (WHATWG): versioned in GitHub, issues on GitHub, WHATWG affiliation, uses a "proprietary language that is then post-processed into HTML" (source).

• JSON Schema: versioned using IETF tooling, issues on GitHub, IETF affiliation, uses IETF RFC format.

• CSS 3: spec history, versioned in Mercurial, issues inline in spec, W3C affiliation, uses Bikeshed.

For a REST API, which approach should we follow? What are the advantages and disadvantages of each?

Answer 1

Caveat: I was the original author of ReSpec (though maintenance has now passed on to others).

I think that at the end of the day, a lot of it boils down to your personal preferences. Both tools support your first list of requirements. Both tools have a similar feature set with a lot of overlap (but also distinct things) and in both cases the documentation may not cover that fact.

Some things that might help you choose:

• ReSpec requires zero installation. In my experience that makes it easier for contributors who are relatively new to spec-writing to get started since they can just fork the repo and edit the HTML — refreshing the browser will show the edits directly. ReSpec source uses conventions beyond HTML, but it is always conforming HTML. Bikeshed requires either a working Python2 installation and it needs to be installed, or use of a curl command to the web version (but I don't think that's very convenient). To more seasoned users, that point makes no difference.
• ReSpec does support batch building, there's a respec2html tool that comes with it. You should normally be able to operate it in CI (otherwise spec-gen works too).
• Publican is dead, as far as I know.
• If you are producing specs that are not intended for W3C, you might need to patch whichever option you pick. At that point your preference in language might be a factor.
• ReSpec will not be very good at very large specifications (but for most cases it's fine).

Overall I think that's it. If you're undecided, the best thing might be for you to grab the sources of two similar specs and compare to see what you like best, and also to play at making a few small edits to both and see what's most convenient for your expected workflow. At the end of the day, don't agonise over this: both formats are HTML-based (and support embedded Markdown if that's your thing). Converting between them should you need to will likely require less time than a properly thorough investigation!

Answer 2

Caveat: I'm the author of Bikeshed.

As Robin said, the choice of processor is largely one of personal taste. Most of the differences in processor are minor; to my knowledge there are two major differences to consider:

1. Bikeshed compiles a source document into HTML; ReSpec is included into an HTML file and on-the-fly rewrites it into better HTML. In my opinion, this makes ReSpec slightly easier for casual use (nothing to install, just refresh the source document to see changes), but Bikeshed is better for the ecosystem (no "flash of un-ReSpec'd content" or "jumping spec" when you navigate to an anchor). That said, Bikeshed is easy to install locally, and a lot of people use the server version instead quite happily.

2. One of Bikeshed's primary features is its cross-spec linking database; it has a growing (largely W3C-centric) database of specs that it regularly spiders for definitions, and makes it very simple to link to those definitions. This has resulted in greatly improved cross-linking in W3C specs, which makes things much easier to read and follow. However, if you're not planning to link into W3C specs, or have them link into you, that's not a big deal. Linking "locally" (within your own spec) is about as easy in either processor.

Answer 3

So on the Bikeshed vs. ReSpec topic, a few thoughts:

When choosing software to rely on, technical superiority or feature set of a project over an other one should rarely be your deciding factor; unless of course there are specific features that you absolutely need to get your job done and that aren't available in all contenders.

Software tends to come and go. And that's true of commercial software as it is of open-source. The steeper the learning curve and the higher migration costs, the more you want to consider a tool's future when picking one.

Bikeshed's killer feature is its cross-spec linking database integration. But it's only a killer feature if you need it. I doubt you would given your current use case.

That said, because it is a killer feature for some of the more involved and Web-centric spec editing, it's acting as a magnet, pulling in key members of the community. As these members adopt Bikeshed and use it for new spec or convert existing specs to it, it increases that tool's appeal creating a snowball effect. Conversely, it makes it harder for ReSpec to maintain its traction. Having a reactive maintainer whose job it is to write specs and whose tool to do so is Bikeshed also helps.

All in all, Bikeshed has a brighter future in front of it than ReSpec does at this point. So, even though you don't need Bikeshed's extra features, its learning curve is a bit steeper and installation more involved, you might still want to pick it simply because it has more traction, which is code for the following:

• it will be along longer,
• bugs should get fixed faster,
• it should improve faster,
• it should be more stable,
• it might add a bit of veneer to your work because you're using the cool kids' tool.

However it seems that you're planning to specify a REST API. I'm not sure either tool is the right one for the job. Have you considered a combination of JSON Schema, JSON Hyper-Schema, and a documentation tool like prmd? This has the added benefits of being (highly) machine readable which can be used to generate test suites for implementations, clients for different programming languages, etc.

Full disclosure: I started off using ReSpec, added Markdown support to it, helped maintain it and recently switched to Bikeshed to benefit from its cross-spec linking database integration.