-
Notifications
You must be signed in to change notification settings - Fork 1
API version zero
Note that this version of the API may change at any time, including in ways that break backwards compatibility. If you need a stable API, wait until we publish something with a non-zero version number.
URL prefix: /api/v0
Response
[
{ "id": 1,
"name": "Conversations",
"unread_conversations": 3
},
{ "id": 4,
"name": "Structural",
"unread_conversations": 0
}
]Returns a list of conversations that the logged-in user is participating in. Each conversation has a name, id and a count of how many conversations in the topic are unread (again, for the logged-in user).
Request
{ "name": "Shenanigans" }Response
{ "id": 6,
"name": "Shenanigans",
"unread_conversations": 0
}Creates a new topic with the name supplied in the request. New, empty topics are guaranteed to have no unread conversations (more generally, they have no conversations of any sort).
Response
[
{ "id": 3,
"title": "Talk about stuff",
"most_recent_message": 1734512345,
"most_recent_viewed": 1722345134,
"participants": [
{ "id": 2,
"full_name": "Paul Revere",
"last_updated_time": 1235123423,
},
{ "id": 4,
"full_name": "Thomas Paine",
"last_updated_time": 1613423423,
}
]
},
{ ... }
]Returns a list of all the conversations the logged-in user is participating in in a particular topic. Each conversation has an id, a name, the timestamp of the last message in the conversation (most_recent_event), the timestamp of when the logged-in user last looked at the conversation (most_recent_viewed) and a list of participants. Each participant has and id, a name and the timestamp of when that user last posted a message to the conversation.
Request
{ }Response
{ "id": 7,
"title": "New Conversation"
}Request
{ "title": "Chitter Chatter",
"participants": [
{ "id": 5,
"name": "Benedict Arnold"
},
{ "id": 7,
"name": "Benjamin Franklin"
}
],
"actions": [
{ "type": "message",
"user": {
"id": 2
},
"text": "Hey, everyone"
}
]
}Response
{ "title": "Chitter Chatter",
"id": 7
}Creates a new conversation in the given topic. The new conversation's name, participants and initial message are optional data in the request. If omitted, the new conversation will have a default title, no participants aside from the logged-in user and no messages. If supplied, the participants and actions will be applied to the message, but not returned in the response. They can be accessed at /conversations/7/participants and /conversations/7/actions, respectively.
Response
{ "id": 3,
"title": "Talk about stuff",
"topic_id": 65
}Returns the id and title of a particular conversation.
Response
[
{ "id": 2,
"full_name": "Paul Revere",
"email": "paul@twoifbysea.com",
"last_updated_time": 1234625721
},
{ "id": 5,
"full_name": "Ethan Allen",
"email": "ethan@somefurniturestore.com",
"last_updated_time": 1723424351
}
]Return a list of the users participating in a particular conversation. Each user has an id, a name and the timestamp of when the user last posted a message to the conversation.
Request
[
{ "user_id": 1
}
]Response
[
{ "id": 1,
"full_name": "George Washington",
"email": "6foot20weighsafuckington@example.com",
"last_updated_time": null
}
]Enlists another user to participate in the conversation. Users who have never posted a message to the conversation have null for their updated timestamp. For sorting purposes, null should be considered to be before any non-null timestamp.
Response
{ "id": 1,
"full_name": "George Washington",
"email": "butnotthebritishchildren@example.com",
"last_updated_time": 1264652323
}Bars a particular user from participating in the conversation.
Response
[
{ "type": "retitle",
"user": {
"name": "Ethan Allen",
"id": 4
},
"timestamp": 1252576323,
"title": "Talk about stuff",
"id": 634
},
{ "type": "message",
"user": "user": {
"name": "Ethan Allen",
"id": 4
},
"timestamp": 1465344532,
"text": "Hey everyone. What do you think about England? I kind of think they suck.",
"id": 764
}
]Returns the list of actions that have been performed against this conversation. Each action is guaranteed to have an id, the id of the user that performed the action, the timestamp for when the action happened, and a string representing the type of action. Each type of action may have additional fields to store further data, such as the text of a message or the identities of users who were added and removed from the conversation.
Valid actions look like one of these:
{ "type": "message",
"user": {
"name": "Ethan Allen",
"id": 2
},
"timestamp": 213651324213,
"id": 523,
"text": "Hey, Ticonderoga! I'm coming for you!"
}
{ "type": "retitle",
"user": {
"name": "Ethan Allen",
"id": 2
},
"timestamp": 213651324213,
"id": 531,
"title": "Green Mountain Chat"
}
{ "type": "deletion",
"user": {
"name": "Ethan Allen",
"id": 2
},
"timestamp": 213651324213,
"id": 525,
"msg_id": 523
}
{ "type": "update_users",
"user": {
"name": "Ethan Allen",
"id": 2
},
"timestamp": 213651324213,
"id": 523,
"added": [],
"removed": [
{ "name": "Benedict Arnold",
"id": 19
}
]
}
{ "type": "move_message",
"user": {
"name": "Ethan Allen",
"id": 2
},
"timestamp": 213651324213,
"id": 523,
"message_id": 781
"from": {
"title": "Whatever whatever",
"id": 10
},
"to": {
"title": "Something something",
"id" 24
}
}
{ "type": "move_conversation",
"user": {
"name": "Ethan Allen",
"id": 2
},
"timestamp": 213651324213,
"id": 523,
"conversation_id": 18,
"from": {
"name": "Chatty Chat",
"id": 5
},
"to": {
"name": "Talkaby talk",
"id" 13
}
}Request
{ "type": "message",
"user": {
"name": "Ethan Allen",
"id": 4
},
"text": "Oh, man King George is the worst. Fuckin' taxes, right?"
}Response
{ "type": "message",
"user": "user": {
"name": "Ethan Allen",
"id": 4
},
"text": "Oh, man King George is the worst. Fuckin' taxes, right?",
"timestamp": 2324536234,
"id": 674
}Performs a new action against a particular conversation. Actions must specify their user, type and any type-specific data in the request. Note that creating some actions (e.g., "move" actions) may also create actions against other conversations.
Response
{ "email": "george.washington@usa.gov",
"full_name": "George Washington",
"id": 1,
"address_book": [
{ "name": "Paul Revere",
"id": 2
},
{ "name": "Ethan Allen",
"id": 4
},
{ "name": "Benjamin Franklin",
"id": 4
}
]
}Returns data about a particular user.
Request
{ "email": "president@usa.gov",
"full_name": "George Washington",
"password": "yeOldeCorrectOldPassword",
"new_password": "totallyModernPassword",
"id": 1
}Response
{ "email": "president@usa.gov",
"full_name": "George Washington",
"id": 1
}Updates the data for the logged in user. Note that new_password is optional if the password is not being updated.
Request
{ "email": "marquis@lafayette.fr",
"full_name": "Gilbert du Motier, Marquis du Lafayette",
"password": "totallySecurePassword"
}Response
{ "email": "marquis@lafayette.fr",
"full_name": "Gilbert du Motier, Marquis du Lafayette",
"id": 8
}Creates a new user.
Response
{ "db_usage": [
{ "table": "users",
"rows": 14
},
{ "table", "actions",
"rows": 2653
},
{ "table": "conversations",
"rows": 256
}
],
"invitations": [
{ "from": "Will Lubelski",
"count": 13
},
{ "from": "Nick Martin",
"count": 5
}
]
}Returns the data needed to construct the admin page. Each database table (including join tables) is returned along with the number of rows in said table. Each admin user is returned along with the number of people they've invited to the app.
- Sessions. How do we log in, and how do we tell the server that we're logged in? Right now I think it's all handled through cookies. We make a request that logs us in, a cookie is returned with the 200 response, and I guess it's automatically sent with all further (including Backbone) requests? If we use a Backbone/JQuery request (since the session doesn't warrant its own model on the client, I'm not sure it needs a Backbone object) how do we make sure we get a hold of that cookie properly?
- Errors. I don't think we need much fancier than a 4xx code and some sort of basic descriptive payload, but we should document it.
- Should timestamps be seconds or milliseconds? It doesn't really matter for what we're doing (we calculate timestamps on the server, and I suspect that the randomness introduced by network latency is enough that we can't really aspire to sub-second message ordering anyway). Ruby does one and javascript does the other, so we have to pick one and do the conversation on one side.
- User-facing routes. These will probably be simpler than the API routes, but we need to figure them out and document them.