jeena/tent.io
1
0
Fork 0
Code Issues Pull requests Projects Packages Wiki Activity Actions
tent.io/content/docs/server-protocol.md
Jonathan Rudenberg 68ce1aeaff Add docs
2012-08-22 14:04:09 -04:00

9.3 KiB
Raw Blame History

Tent Server-Server Communication Protocol

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

Server Discovery

Both discovery methods should be implemented.

HTML link tag

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

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

HTTP 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.

Tent-Server: https://tent.titanous.com

The Tent-Server header can contain multiple comma-separated urls that should be tried in order.

Entity Profile

GET /profile
Accept: application/json

200 OK
Content-Type: application/json

[
  {
    "type": {
      "url": "https://tent.io",
      "version": "0.2.0"
    },
    "licenses": [
      {
        "url": "https://tent.io/types/licenses/creative-commons",
        "version": "3.0.0"
      }
    ],
    "entity": "titanous.com",
    "servers": [
      "https://tent.titanous.com",
      "https://eqt5g4fuenphqinx.onion",
      "https://titn.us/api"
    ]
  },
  {
    "type": {
      "url": "https://tent.io/types/profile/music",
      "version": "2.0.0"
    },
    "bands": [ "foo", "bar" ]
  }
]

Follow an entity

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

The secret is only returned once and should be persisted along with the id for authentication.

POST /followers

POST /followers
Content-Type: application/json
Accept: application/json

{
  "entity": "danielsiders.com",
  "licenses": [
    {
      "url": "https://tent.io/types/licenses/creative-commons",
      "version": "3.0.0"
    }
  ],
  "types": [
    {
      "url": "https://tent.io/types/posts/status",
      "version": "~> 1.1",
      "view": "full"
    },
    {
      "url": "https://tent.io/types/posts/photo",
      "version": "~> 1.0",
      "view": "meta"
    },
  ]
}

201 Created
Content-Type: application/json
Location: https://tent.titanous.com/api/followers/775ecf8

{
  "id": "775ecf8"
  "secret": "b524ce27f1882bcad98092175fbe7040",
  "mac_algorithm": "hmac-sha-256"
}

Authentication

All requests must be made using SSL.

Authentication is required for all resources except some of the profile and publicly accessible posts.

Tent uses MAC Access Authentication for all requests. The id and secret from the follow response are used as the MAC key identifier and MAC key respectively.

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

Currently the signatures in example requests are fake, they will be correct when the documentation generator is done.

Get Current Following

danielsiders.com checks its following of titanous.com

GET /followers/:id

GET /followers/775ecf8
Accept: application/json
Authorization: MAC id="775ecf8",
                   ts="1336363200",
                   nonce="dj83hs9s",
                   mac="bhCQXTVyfj5cmA9uKkPFx1zeOXM="

{
  "id": "775ecf8",
  "entity": "danielsiders.com",
  "licenses": [
    {
      "url": "https://tent.io/types/licenses/creative-commons",
      "version": "3.0.0"
    }
  ],
  "types": [
    {
      "url": "https://tent.io/types/posts/status",
      "version": "~> 1.1",
      "view": "full"
    },
    {
      "url": "https://tent.io/types/posts/photo",
      "version": "~> 1.0",
      "view": "meta"
    },
  ],
  "mac_algorithm": "hmac-sha-256"
}

Edit Following

PATCH /followers/:id

PATCH /followers/775ecf8
Accept: application/json
Content-Type: application/json
Authorization: MAC id="775ecf8",
                   ts="1336363200",
                   nonce="dj83hs9s",
                   mac="bhCQXTVyfj5cmA9uKkPFx1zeOXM="

{
  "id": "775ecf8",
  "entity": "danielsiders.com",
  "licenses": [
    {
      "url": "https://tent.io/types/licenses/creative-commons",
      "version": "3.0.0"
    }
  ],
  "types": [
    {
      "url": "https://tent.io/types/posts/status",
      "version": "~> 1.1",
      "view": "full"
    },
    {
      "url": "https://tent.io/types/posts/photo",
      "version": "~> 1.0",
      "view": "thumb"
    },
  ],
  "mac_algorithm": "hmac-sha-256"
}

200 OK
Content-Type: application/json

{
  "id": "775ecf8",
  "entity": "danielsiders.com",
  "licenses": [
    {
      "url": "https://tent.io/types/licenses/creative-commons",
      "version": "3.0.0"
    }
  ],
  "types": [
    {
      "url": "https://tent.io/types/posts/status",
      "version": "~> 1.1",
      "view": "full"
    },
    {
      "url": "https://tent.io/types/posts/photo",
      "version": "~> 1.0",
      "view": "thumb"
    },
  ],
  "mac_algorithm": "hmac-sha-256"
}

Stop Following

DELETE /followers/:id

DELETE /followers/775ecf8
Authorization: MAC id="775ecf8",
                   ts="1336363200",
                   nonce="dj83hs9s",
                   mac="bhCQXTVyfj5cmA9uKkPFx1zeOXM="

204 No Content

Notifications

Notification from titanous.com to danielsiders.com that new content has been posted.

POST /notifications

POST /notifications
Content-Type: application/json
Authorization: MAC id="775ecf8",
                   ts="1336363200",
                   nonce="dj83hs9s",
                   mac="bhCQXTVyfj5cmA9uKkPFx1zeOXM="

[
  {
    "id": "jA4Mzdh",
    "entity": "titanous.com",
    "time": 1345322351,
    "licenses": [
      {
        "url": "https://tent.io/types/licenses/creative-commons",
        "version": "3.0.0"
      }
    ],
    "scope": "public",
    "content": {
      "type": {
        "url": "https://tent.io/types/posts/status",
        "version": "1.2.0",
        "view": "full"
      },
      "text": "Tent.io is awesome!"
    }
  }
]

POST /notifications

POST /notifications
Content-Type: application/json
Authorization: MAC id="775ecf8",
                   ts="1336363200",
                   nonce="dj83hs9s",
                   mac="bhCQXTVyfj5cmA9uKkPFx1zeOXM="

[
  {
    "id": "8c73440",
    "entity": "titanous.com",
    "time": 1345322351,
    "licenses": [
      {
        "url": "https://tent.io/types/licenses/creative-commons",
        "version": "3.0.0"
      }
    ],
    "scope": "public",
    "content": {
      "type": {
        "url": "https://tent.io/types/posts/delete",
        "version": "1.2.0",
        "view": "full"
      },
      "id": "jA4Mzdh",
      "entity": "titanous.com",
    }
  }
]

Fetch Post Feed

GET /posts

Parameters

Name Required Type Description
post_types Optional string Specifies the post types and views to return. ex: https://tent.io/types/posts/blog#excerpt,https://tent.io/types/posts/photo#meta
since_id Optional string Show posts newer than this id.
before_id Optional string Show posts older than this id.
since_time Optional integer Show posts made since this time (unix epoch time).
before_time Optional integer Show posts made before this time (unix epoch time).
count Optional integer The number of posts to return. 
GET /posts
Accept: application/json
Authorization: MAC id="775ecf8",
                   ts="1336363200",
                   nonce="dj83hs9s",
                   mac="bhCQXTVyfj5cmA9uKkPFx1zeOXM="

200 OK
Content-Type: application/json

[
  {
    "id": "jA4Mzdh",
    "entity": "titanous.com",
    "time": 1345322351,
    "licenses": [
      {
        "url": "https://tent.io/types/licenses/creative-commons",
        "version": "3.0.0"
      }
    ],
    "scope": "public",
    "content": {
      "type": {
        "url": "https://tent.io/types/posts/status",
        "version": "1.2.0",
        "view": "full"
      },
      "text": "Tent.io is awesome!"
    }
  }
]

Fetch Single Post

GET /posts/:id

GET /posts/jA4Mzdh
Accept: application/json
Authorization: MAC id="775ecf8",
                   ts="1336363200",
                   nonce="dj83hs9s",
                   mac="bhCQXTVyfj5cmA9uKkPFx1zeOXM="

200 OK
Content-Type: application/json

{
  "id": "jA4Mzdh",
  "entity": "titanous.com",
  "time": 1345322351,
  "licenses": [
    {
      "url": "https://tent.io/types/licenses/creative-commons",
      "version": "3.0.0"
    }
  ],
  "scope": "public",
  "content": {
    "type": {
      "url": "https://tent.io/types/posts/status",
      "version": "1.2.0",
      "view": "full"
    },
    "text": "Tent.io is awesome!"
  }
}