[Specifications] Start a Hydra gitbook

tpluscode has just created a new issue for https://github.com/HydraCG/Specifications:

== Start a Hydra gitbook ==
I'd like to point our attention to recent messages from [HTTP APIs](http://httpapis.slack.com) by @paul:

> We're embarking on the next version of our API [...]. I really want to use Hydra, but it seems like its not ready yet: The "spec" has to be derived from reading a bunch of Github issues, and the few examples I can find seem to be based on various versions of the spec and haven't been updated. It's hard for me to get a feel for what a Hydra API should actually look like.

> I really, really want to use Hydra. [...], and its really hard to cobble together the Hydra docs from all over to figure out what it should actually look like.

> Another example involves paged collections. The Hydra spec doesn't really mention it, the github repo has a document about collections in "drafts", which links to ISSUE 41, which was resolved in a comment 2 years ago, which updated the `hydra.jsonld` file, but nothing else. The only example I can find of a paged collection is in one of the "api-platform.com" demo app, and it doesn't even match what was decided in that PR.

-----

The Use Cases that we've been working on are a great step forward. We made great progress with some decisions, maybe partially because there are fewer voices.

However, I think that Paul is right on that the knowledge is fragmented and difficult to access.

What would you guys think about starting a separate repo and make the use cases a gitbook? https://hydracg.gitbooks.io/use-cases. 

But that could only be the first step. Why not have a a number of books under the HydraCG umbrella?

* /samples -> snippets of actual representations (I think most close to what Paul is asking)
* /heracles.ts -> docs for the client
* /aclaeus -> that's how I intend to rebrand the "old" Heracles which I want to keep developing
* /URSA -> Karol's C# back end
* /argolis -> My C# backend

I know that this will be a big effort but currently we still have limited reach IMO and a fragmented community. Maybe this way we could showcase that Hydra really is a viable alternative to other hypermedia formats?

Please view or discuss this issue at https://github.com/HydraCG/Specifications/issues/147 using your GitHub account

Received on Friday, 3 November 2017 18:35:24 UTC