[xrstf]

I really like the clean API docs, well done! Did you build it on your own or is that some REST doc framework?

The only thing I was missing from the API (maybe those are there but left out in the docs, which would be totally fine) are links between your resources (to make it a bit more actual REST). You already more promimently documented the usecase ("create an invoice") instead of listing URL endpoints, but with links between the resources, the API becomes even more discoverable for new developers.

Oh, one more minor thing: "Paid uses UTC unix timestamps for all dates and times." -- I was under the impression that unix timestamps are always UTC anyway (i.e. it's defined as "seconds since 1970-01-01 UTC")? If I'm wrong, please correct me :)

[ryanwjackson]

The docs are an awesome repo by TripIt (https://github.com/tripit/slate). They aren't perfect, but they get you pretty far pretty quickly.

Not sure what you mean by "links between your resources." Have an example? May be there (or we can build it if not).

Correct on Unix time. Just being extra redundant.

[xrstf]

Roy says[1] that to be truly RESTful, your resources (documents) need to be linked between each other, just like HTML pages. There are no definite standards yet (that I'm aware of), but JSON HAL[1] seems to be on the IETF standards track to be the one solution we settle on (just like we "settled on" <a href> in HTML). See also [3] for a broader overview on links in JSON and [4] for more information on resource linking and stuff in general.

[1] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...

[2] http://stateless.co/hal_specification.html

[3] https://www.mnot.net/blog/2011/11/25/linking_in_json

[4] http://en.wikipedia.org/wiki/HATEOAS

[jerven]

What about JSON-LD and linked data platform. At least JSON-LD comes from the W3C Web payement workgroup

[xrstf]

I haven't looked into the available techniques for a few months. JSON HAL works fine for me for now. ;)