[Flow] Implementing an REST-Interface with Flow 2.0

[Jacob Floyd]

A lot of people think using an API that spits out JSON and uses HTTP verbs is RESTful, but that's only two elements of a RESTful api. You could call it REST-like, but not RESTful. To be RESTful, it also needs to be a self-documenting API with links from resource to resource (ie it needs to use HATEOAS).

Could we clarify this difference in the tutorial (RESTful vs REST-like)? One of the goals of Flow is to help all of us become better programmers. And this is an area where there's a lot of confusion (heck. It took me hours of studying before I began to understand the difference, and the importance of HATEOAS).

So, maybe we need a tutorial for building merely REST-like tutorials (that use JSON and HTTP verbs), and at the end, some kind of "Next steps" section that says that to make the API truly RESTful you need to make it use HATEOAS, and then link to another tutorial that expands on the first tutorial and goes into all the nitty gritty of what HATEOAS is, and where to find out about the available specs, and (most importantly), how to implement HATEOAS in an API built in Flow.

Cheers,
Jacob Floyd