Tent - the decentralized social web

Alpha Documentation

These docs are very rough, incorrect, and incomplete. They will be modified heavily over the next few weeks.

Please contribute by making Pull Requests and Issues on the GitHub repository.

Tent Server-Server Communication Protocol

This document describes the protocol that Tent servers use to communicate with each other.

Server Discovery

Server discovery is done through HTTP Link headers as well as HTML link tags. Multiple links may be presented, and should be tried by the client in order.

HTTP `Link` Header

The HTTP header allows discovery of Tent servers by just doing a HEAD request instead of getting the page and parsing it for the link tag. It should be added to all responses associated with the Tent entity.

Link: <https://tent.titanous.com/profile>; rel="https://tent.io/rels/profile"

HTML `link` tag

The link tag should be placed in the head tag of all HTML pages associated with the Tent entity.

<link href="https://tent.titanous.com/profile" rel="https://tent.io/rels/profile" />

Follow an entity

A follow request is required in order to receive notifications about posts published by an entity.

POST /followers

POST /followers HTTP/1.1
Content-Type: application/vnd.tent.v0+json
Accept: application/vnd.tent.v0+json

{
  "entity": "https://example.org",
  "types": [
    "all"
  ],
  "licenses": [
    "http://creativecommons.org/licenses/by/3.0/"
  ]
}

HTTP/1.1 200 OK
Content-Type: application/vnd.tent.v0+json
Content-Length: 254

{
  "entity": "https://example.org",
  "permissions": {
    "public": false
  },
  "id": "7m3dto",
  "mac_key_id": "s:16e9933f",
  "mac_key": "fd45af54f59b930e5e6eab4bf1e6a0f3",
  "mac_algorithm": "hmac-sha-256",
  "licenses": [
    "http://creativecommons.org/licenses/by/3.0/"
  ],
  "types": [
    "all"
  ]
}

Authentication

All requests should be made using SSL.

Authentication is required to access resources that are not marked as public.

Tent uses MAC Access Authentication for all requests.

All requests must be signed using MAC, and all notifications from the server are signed as well.

Get Current Following

GET /followers/:id

GET /followers/7m3dto HTTP/1.1
Accept: application/vnd.tent.v0+json
Authorization: MAC id="s:16e9933f", ts="1346984266", nonce="3824e1", mac="aRnrSo+80AHRru2FJE1Sj6GfCsmpKcyv7w5FZONAtOM="

HTTP/1.1 200 OK
Content-Type: application/vnd.tent.v0+json
Last-Modified: Fri, 07 Sep 2012 02:17:46 GMT
Cache-Control: private
Content-Length: 152

{
  "entity": "https://example.org",
  "permissions": {
    "public": false
  },
  "id": "7m3dto",
  "licenses": [
    "http://creativecommons.org/licenses/by/3.0/"
  ],
  "types": [
    "all"
  ]
}

Edit Following

PUT /followers/:id

PUT /followers/7m3dto HTTP/1.1
Content-Type: application/vnd.tent.v0+json
Accept: application/vnd.tent.v0+json
Authorization: MAC id="s:16e9933f", ts="1346984266", nonce="6e4ff8", mac="MAr2L6Z1ZcAe4tv5XGmafCUH8w/OrkUFpJKhK8dtoBs="

{
  "entity": "https://example.org",
  "licenses": [
    "http://creativecommons.org/licenses/by/3.0/"
  ],
  "types": [
    "https://tent.io/types/post/essay/v0.1.0#full"
  ]
}

HTTP/1.1 200 OK
Content-Type: application/vnd.tent.v0+json
Content-Length: 193

{
  "entity": "https://example.org",
  "permissions": {
    "public": false
  },
  "id": "7m3dto",
  "licenses": [
    "http://creativecommons.org/licenses/by/3.0/"
  ],
  "types": [
    "https://tent.io/types/post/essay/v0.1.0#full"
  ]
}

Stop Following

DELETE /followers/:id

DELETE /followers/eazohw HTTP/1.1
Accept: application/vnd.tent.v0+json
Authorization: MAC id="s:16e9933f", ts="1346984266", nonce="fa20ba", mac="SkbEBnIsBUvZ9jLce6cXfry7dqNN9OELnnF1UvwkHys="

HTTP/1.1 403 Forbidden
Content-Type: text/html
Content-Length: 12

Unauthorized

Fetch Posts

GET /posts

GET /posts HTTP/1.1
Accept: application/vnd.tent.v0+json
Authorization: MAC id="s:16e9933f", ts="1346984266", nonce="11a3ee", mac="30RvjuvuDkTitC+iubWLvMfqyr2JegqtrKaSE+cEN78="

HTTP/1.1 200 OK
Content-Type: application/vnd.tent.v0+json
Last-Modified: Fri, 07 Sep 2012 02:17:46 GMT
Cache-Control: private
Content-Length: 378

[
  {
    "entity": "https://example.org",
    "type": "https://tent.io/types/post/status/v0.1.0",
    "licenses": [
      "http://creativecommons.org/licenses/by/3.0/"
    ],
    "content": {
      "text": "Just landed.",
      "location": {
        "type": "Point",
        "coordinates": [
          50.923878,
          4.028605
        ]
      }
    },
    "published_at": 1346984266,
    "permissions": {
      "public": true
    },
    "id": "xk3mlq",
    "app": {
      "url": "http://example.com",
      "name": "FooApp"
    },
    "attachments": [

    ]
  }
]

GET /posts/:id

GET /posts/xk3mlq HTTP/1.1
Accept: application/vnd.tent.v0+json
Authorization: MAC id="s:16e9933f", ts="1346984266", nonce="e9d768", mac="gaw/GTjat0ANZmdoo+X4NHpAk+SuJNLj+rSGdcD0JbE="

HTTP/1.1 200 OK
Content-Type: application/vnd.tent.v0+json
Last-Modified: Fri, 07 Sep 2012 02:17:46 GMT
Cache-Control: public
Content-Length: 376

{
  "entity": "https://example.org",
  "type": "https://tent.io/types/post/status/v0.1.0",
  "licenses": [
    "http://creativecommons.org/licenses/by/3.0/"
  ],
  "content": {
    "text": "Just landed.",
    "location": {
      "type": "Point",
      "coordinates": [
        50.923878,
        4.028605
      ]
    }
  },
  "published_at": 1346984266,
  "permissions": {
    "public": true
  },
  "id": "xk3mlq",
  "app": {
    "url": "http://example.com",
    "name": "FooApp"
  },
  "attachments": [

  ]
}

Notifications

Notifications of new content are sent as POST requests to /posts and authenticated using the negotiated credentials.