API v1
###403 DO NOT MOVE###
We're currently moving this wiki over to our new project site. The contents of this page are not important enough to be ported over because they are either very old, very outdated or wrong and misleading.
Current draft: "http://pad.spored.de/ro/r.qWmvhSZg7rk4OQam":http://pad.spored.de/ro/r.qWmvhSZg7rk4OQam Implementation: "https://github.com/MrZYX/diaspora/tree/mobile_api":https://github.com/MrZYX/diaspora/tree/mobile_api WIP docs: "https://gist.github.com/01c93096c30dc44caf71":https://gist.github.com/01c93096c30dc44caf71
h1. Old Info
This is a draft for designing Diaspora's API version 1. This is neither complete nor correct, it's just a collection of ideas.
"Here's the main discussion of the API":http://groups.google.com/group/diaspora-dev/browse_thread/thread/eeaf48ac16e35877/1246731e9cf114ba
Table of Contents:
- Introduction ** "General notes":#general_notes ** "Authentication":#authentication
- Stream methods ** "GET /stream":#get_stream
- Post functions ** "GET /post/[post]":#get_post
- Conversation ** "GET /conversations":#get_conversations ** "GET /conversation/[conversation]":#get_conversation
h2(#general_notes). General notes
We want to use as much already existing standards as possible, so we decided to use "JSON Activity Streams":http://activitystrea.ms/specs/json/1.0/ for everything related with streams and messages and "Portable Contacts":http://portablecontacts.net/draft-spec.html for everything regarding profiles.
h2(#authentication). Authentication
In this first version we are going to use http basic auth until OAuth is fully implemented and tested. Devise supports http basic auth and that's easy to enable.
h2. Stream
h3(#get_stream). GET /stream
Returns a JSON of the stream items. (ActivityStreams)
h4. Parameters
no parameters
h4. Example
bc. GET /stream?sort_order=created_at { "items": [ { "id": "456", "published": "2011-02-10T15:04:55Z", "actor": { "id": "42", "displayName": "Jane Doe", "name": "Jane Doe", "nickname": "jane@pod.example.org", "preferredUsername": "jane", "birthday": "1975-02-14", "gender": "who knows", "note": "Janes profile description" "picture": "http://example.com/uploads/images/foo.png" }, "verb": "post", "object": { "content": "Hello, epic Diasporaverse" } }, { "id": "564", "published": "2011-02-11T14:03:55Z", "actor": { "id": "23", "displayName": "John Doe", "name": "John Doe", "nickname": "john@pod.example.org", "preferredUsername": "john", "birthday": "1975-02-14", "gender": "who knows", "note": "Johns profile description" "picture": "http://example.com/uploads/images/foo.png" }, "verb": "post", "object": { "content": "Good morning!" } } ] }
h2. Posts
h3(#get_post). GET /post/[post]
Returns a JSON containing the requested post. (ActivityStreams)
h4. Parameters
- post: The post ID
h4. Example
bc. GET /posts/456 { "id": "456", "published": "2011-02-10T15:04:55Z", "actor": { "id": "42", "displayName": "Jane Doe", "name": "Jane Doe", "nickname": "jane@pod.example.org", "preferredUsername": "jane", "birthday": "1975-02-14", "gender": "who knows", "note": "Janes profile description" "picture": "http://example.com/uploads/images/foo.png" }, "verb": "post", "object": { "content": "Hello, epic Diasporaverse" } }
h2. Conversations
h3(#get_conversations). GET /conversations
Returns a JSON containing all conversations. (extended ActivitySreams)
h4. Parameters
none
h4. Example
bc. GET /conversations { "conversations": [ { "id": "123", "subject": "Hello, you", "created_at": "2011-02-10T15:04:55Z", "updated_at": "2011-02-10T15:04:55Z", "lastAuthor": { "id": "42", "displayName": "Jane Doe", "name": "Jane Doe", "nickname": "jane@pod.example.org", "preferredUsername": "jane", "birthday": "1975-02-14", "gender": "who knows", "note": "Janes profile description", "picture": "http://example.com/uploads/images/foo.png" } }, { "id": "456", "subject": "BugBug!", "created_at": "2011-02-10T15:04:55Z", "updated_at": "2011-02-10T15:04:55Z", "lastAuthor": { "id": "23", "displayName": "John Doe", "name": "John Doe", "nickname": "John@pod.example.org", "preferredUsername": "John", "birthday": "1975-02-14", "gender": "who knows", "note": "John profile description", "picture": "http://example.com/uploads/images/foo.png" } } ] }
h3(#get_conversation). GET /conversation/[conversation]
Returns a JSON (ActivityStreams) containing all messages of the given conversation
h4. Parameters
- conversation: the id of a conversation
h4. Example
See GET /stream, this will look similar.