HLD of the JSON interface

[peterbrittain]

What should the JSON API look like?

I'm assuming we're aiming for a RESTful API and so will have something like this:

• Read/modify/delete through GET/POST/DELETE. Create is just a special case of modify, where there is no existing object.
• Success/failure through HTTP return codes.
• Requests generally return the current state of the object being manipulated (or blank for delete requests).
• Objects to manipulate are users, congas and messages. Register/deregister is just user creation/deletion.

Make sense?

[peterbrittain]

Was just thinking about adding yourself to a conga and think the post request is effectively an append in this case, getting the conga members on a successful result.

[peterbrittain]

As of last night, I've got a basic working prototype of this API for users and congas. In addition to the basic logic above I've had to resort to using a PUT request to allow people to append themselves to a conga.

The resulting API isn't too bad, but there are some rough edges. For example:

• We should probably consistently use a collection style address - e.g. ../users - and then specific entries - e.g. ../users/peter.
• We should make it so that all requests follow this standard - there is some grunge in the POST/DELETE right now.

That said, I think the resulting API is looking broadly suitable. You can try it out yourself by installing the server (see https://github.com/neilcollins/piconga/wiki/Django-Server) and then running the sample script https://github.com/neilcollins/piconga/blob/master/server/scripts/test_json.py to see some conga set up.

[neilcollins]

Nice !

[Lukasa]

Awesome! My only suggestions here are a) minor and b) not really suitable for the development deployment.

In production, we should limit the add/delete user endpoints to HTTPS to prevent accidental transmission of credentials in plaintext. Once that's done, we should not send passwords on the other endpoints but some kind of session token. Django has a method for using session cookies, and Requests should propagate them on the Session object, so that might work: alternatively, we can handle session tokens ourselves.

Also, it goes without saying that conga deletion should be a privileged action as well. =D