Skip to content
This repository has been archived by the owner on May 3, 2023. It is now read-only.

Tent Server Protocol

Jump to bottom
SoftlySplinter edited this page Dec 17, 2012 · 7 revisions

How we do it

For more in depth information see: https://tent.io/docs/server-protocol

Overview

Terms

  • server relates to a full URI without any following path (e.g: http://example.com). This may also contain domain information which holds information about the user.
  • username relates to the username of the user on the primary server.
  • resource relates to a resource on the server. It is usually prefixed by username. These may be named in the documentation below as things such as profile.
  • <id> is used to request a resource with the given id.

Routes

  • HEAD server Returns a Link header to server/username/profile
  • HEAD server/* Returns a Link header to server/username/profile
  • GET server/username/profile Returns a JSON file with the profile for the specified user.
  • POST server/username/followers Starts following a user specified by the parameters of the POST.
  • GET server/username/followers/<id> Returns information about a given follower.
  • PUT server/username/followers/<id> Edits the information about a given follower.
  • DELETE server/username/followers/<id> Stops following a user.
  • GET server/username/posts Gets all posts from the given user. Filters are part of the request.
  • GET server/username/posts/<id> Gets post with the specified ID.

Server Discovery

The idea of tent is that users discover servers by either:

  • Sending a HEAD request.
  • Looking at a <link> tag in the HTML.

This is why any HEAD request to server should add the Link header to the user's profile.

This header should look like the following:

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

For where there are multiple users on a server, the Link header should contain all of them, like so:

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

In any HTML pages there should be a link tag like the following:

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

Followers

Follow an Entity

Performing the following REST request:

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

With this information:

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

Should result in the response similar to:

HTTP/1.1 200 OK
Content-Type: application/vnd.tent.v0+json
ETag: "b25b413ff9d0042c953cddc269d60568"
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 253

And a file along the lines of:

{
  "entity": "https://example.org",
  "permissions": {
    "public": true
  },
  "id": "ram8he",
  "mac_key_id": "s:6fdcb540",
  "mac_key": "8583f8dc112c8590aefd32f52d7985c2",
  "mac_algorithm": "hmac-sha-256",
  "licenses": [
    "http://creativecommons.org/licenses/by/3.0/"
  ],
  "types": [
    "all"
  ]
}

This will set-up the notification settings on the receiving server to POST any new posts matching the criteria specified by that given entity to the notification__path (in this example this is: notifications/ifegf4 (the full URL I assume is: http://example.org/notifications/ifegf4)).

NOTE: What happens if that address isn't available?

Get Follower

Issuing the following request:

GET /followers/ram8he HTTP/1.1
Accept: application/vnd.tent.v0+json
Authorization: ...

Should result in the following response:

HTTP/1.1 200 OK
Content-Type: application/vnd.tent.v0+json
ETag: "8cc9fe6fc3fcedacf9b152eedfcab5fb"
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 151
{
  "entity": "https://example.org",
  "permissions": {
    "public": true
  },
  "id": "ram8he",
  "licenses": [
    "http://creativecommons.org/licenses/by/3.0/"
  ],
  "types": [
    "all"
  ]
}

Changing what you follow

To edit the details of a following relationship to only follow essay posts, issue the following request:

PUT /followers/ram8he HTTP/1.1
Content-Type: application/vnd.tent.v0+json
Accept: application/vnd.tent.v0+json
Authorization: ...
{
  "entity": "https://example.org",
  "licenses": [
    "http://creativecommons.org/licenses/by/3.0/"
  ],
  "types": [
    "https://tent.io/types/post/essay/v0.1.0#full"
  ]
}

This should generate a response like:

HTTP/1.1 200 OK
Content-Type: application/vnd.tent.v0+json
ETag: "28bcb78c8164c2d88ee663fefaef5fac"
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 192
{
  "entity": "https://example.org",
  "permissions": {
    "public": true
  },
  "id": "ram8he",
  "licenses": [
    "http://creativecommons.org/licenses/by/3.0/"
  ],
  "types": [
    "https://tent.io/types/post/essay/v0.1.0#full"
  ]
}

Stop following an entity

To stop following an entity, issue a delete request, like the following:

DELETE /followers/ram8he HTTP/1.1
Accept: application/vnd.tent.v0+json
Authorization: ...

The response should be something along the following lines:

HTTP/1.1 200 OK
Content-Type: text/html
Cache-Control: 
Content-Length: 0

Taken from: https://tent.io/docs/server-protocol

And therefore this copyright notice is required:

Copyright © 2012 by Apollic Software, LLC. All rights reserved

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Apollic Software, LLC.

Clone this wiki locally