Major architecture

[DuncanvR]

Seeing that this will be a multi-user application, I'd opt for a client-server architecture. This has the added benefit that we can write/replace both sides separately and play around with different approaches.

A simple RESTful service using JSON messages should do the trick for the server side. A client implementation could be done as a website or console application, or perhaps even a mobile app if someone is feeling generous.

Given the premise from the readme, that backwards and forwards compatibility should be part of the design criteria, I'd suggest versioning the APIs from the start. I'm not entirely sure how to best incorporate that with the statelessness of the REST principles though; any thoughts?

[jankramer]

I agree on the choice for a client-server architecture with a RESTful service. 👍

Regarding versioning: incorporating a version part in the URL is not really RESTful as it violates the principle that the URI should represent a resource, not a representation. An alternative is to use content negotiation by putting the version in the content type, e.g. application/vnd.arnold+json;v=1.

Another important aspect of the API is its documentation. It would be nice to define it in some sort of standard format that can be interpreted. I have some experience with http://apiary.io and it generates very shiny yet useful documentation as it has a built-in client to try out the API. However, I'd love to hear other suggestions.

For now, I think the high level architecture is pretty clear and it's best to start focusing on what functionality to implement, but let's open another issue for that.