API v1

Current draft: http://pad.spored.de/ro/r.qWmvhSZg7rk4OQam
Implementation: https://github.com/MrZYX/diaspora/tree/mobile_api
WIP docs: https://gist.github.com/01c93096c30dc44caf71

1. Old Info
   *

I (Dennis Schubert) am working at this document right now. Please wait until I’ve fully inserted my drafts – should be done until the end of the day. :-)
“must be a long day ;)” ~eferdi

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

---

Table of Contents:

• Introduction
  • General notes
  • Authentication
• Stream methods
  • GET /stream
• Post functions
  • GET /post/[post]
• Conversation
  • GET /conversations
  • GET /conversation/[conversation]

General notes

We want to use as much already existing standards as possible, so we decided to use JSON Activity Streams for everything related with streams and messages and Portable Contacts for everything regarding profiles.

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.

Stream

GET /stream

Returns a JSON of the stream items. (ActivityStreams)

Parameters

no parameters

Example

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": "[email protected]",
        "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": "[email protected]",
        "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!"
      }
    }
  ]
}

Posts

GET /post/[post]

Returns a JSON containing the requested post. (ActivityStreams)

Parameters

• post: The post ID

Example

GET /posts/456
{
  "id": "456",
  "published": "2011-02-10T15:04:55Z",
  "actor": {
    "id": "42",
    "displayName": "Jane Doe",
    "name": "Jane Doe",
    "nickname": "[email protected]",
    "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"
  }
}

Conversations

GET /conversations

Returns a JSON containing all conversations. (extended ActivitySreams)

Parameters

none

Example

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": "[email protected]",
        "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": "[email protected]",
        "preferredUsername": "John",
        "birthday": "1975-02-14",
        "gender": "who knows",
        "note": "John profile description",
        "picture": "http://example.com/uploads/images/foo.png"
      }
    }
  ]
}

GET /conversation/[conversation]

Returns a JSON (ActivityStreams) containing all messages of the given conversation

Parameters

• conversation: the id of a conversation

Example

See GET /stream, this will look similar.