From 35e66dece53b69a54d9433dd8f07283a2114abd5 Mon Sep 17 00:00:00 2001 From: Jonathan Rudenberg Date: Wed, 5 Sep 2012 14:58:23 -0400 Subject: [PATCH] Update follower examples --- Gemfile.lock | 13 +- content/docs/server-protocol.md | 395 ++------------------------------ 2 files changed, 32 insertions(+), 376 deletions(-) diff --git a/Gemfile.lock b/Gemfile.lock index 5c60f36..4a9d4cd 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -16,27 +16,30 @@ GIT GIT remote: git@github.com:tent/tent-apidoc.git - revision: 3894f0a84d5ca02896139da07edd321b1551887a + revision: 9bb0ab5c2f0bad683fa407148d0635a96c1ab71d branch: master specs: tent-apidoc (0.1.0) + fabrication + faker rack-test tent-client tentd GIT remote: git@github.com:tent/tent-client-ruby.git - revision: cefddd03e1d2b42dc4ccca0059d0dd7c333d06f3 + revision: d70a052f676173823a8d34de0e13aeb40a95e006 branch: master specs: tent-client (0.0.1) faraday (= 0.8.4) faraday_middleware (= 0.8.8) + json nokogiri GIT remote: git@github.com:tent/tentd.git - revision: 64b90e175e265f76db937dc9483e86e5ae1cc71c + revision: 6c492a0953a32e8d0c1f1b0f0bd6ab30f821ce31 branch: master specs: tentd (0.0.1) @@ -114,6 +117,9 @@ GEM dm-core (~> 1.2.0) do_postgres (0.10.8) data_objects (= 0.10.8) + fabrication (2.2.3) + faker (1.0.1) + i18n (~> 0.4) faraday (0.8.4) multipart-post (~> 1.1) faraday_middleware (0.8.8) @@ -123,6 +129,7 @@ GEM girl_friday (0.10.0) connection_pool (~> 0.9.0) hashie (1.2.0) + i18n (0.6.1) json (1.7.5) json-schema (1.0.9) json_pure (1.7.5) diff --git a/content/docs/server-protocol.md b/content/docs/server-protocol.md index fd4586e..731f1a4 100644 --- a/content/docs/server-protocol.md +++ b/content/docs/server-protocol.md @@ -5,7 +5,19 @@ each other. ### Server Discovery -Both discovery methods should be implemented. +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. + +```text +Link: ; rel="https://tent.io/rels/profile" +``` #### HTML `link` tag @@ -13,63 +25,7 @@ The `link` tag should be placed in the `head` tag of all HTML pages associated with the Tent entity. ```html - -``` - -#### 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. - -```text -Tent-Server: https://tent.titanous.com -``` - -The `Tent-Server` header can contain multiple comma-separated urls that should -be tried in order. - - -### Entity Profile - -```text -GET /profile -Accept: application/json -``` - -```text -200 OK -Content-Type: application/json -``` - -```json -[ - { - "type": { - "url": "https://tent.io", - "version": "0.1.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": "0.1.0" - }, - "bands": [ "foo", "bar" ] - } -] + ``` @@ -78,279 +34,52 @@ Content-Type: application/json 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 -```text -POST /followers -Content-Type: application/json -Accept: application/json -``` +{create_follower example} -```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" - }, - ] -} -``` - -```text -201 Created -Content-Type: application/json -Location: https://tent.titanous.com/api/followers/775ecf8 -``` - -```json -{ - "id": "775ecf8" - "secret": "b524ce27f1882bcad98092175fbe7040", - "mac_algorithm": "hmac-sha-256" -} -``` ## Authentication -All requests must be made using SSL. +All requests should be made using SSL. -Authentication is required for all resources except some of the profile and -publicly accessible posts. +Authentication is required to access resources that are not marked as public. Tent uses [MAC Access Authentication](http://tools.ietf.org/html/draft-ietf-oauth-v2-http-mac-01) -for all requests. The `id` and `secret` from the follow response are used as the -MAC key identifier and MAC key respectively. +for all requests. 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 -```text -GET /followers/775ecf8 -Accept: application/json -Authorization: MAC id="775ecf8", - ts="1336363200", - nonce="dj83hs9s", - mac="bhCQXTVyfj5cmA9uKkPFx1zeOXM=" -``` +{get_follower example} -```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": "meta" - }, - ], - "mac_algorithm": "hmac-sha-256" -} -``` ## Edit Following -### PATCH /followers/:id +### PUT /followers/:id -```text -PATCH /followers/775ecf8 -Accept: application/json -Content-Type: application/json -Authorization: MAC id="775ecf8", - ts="1336363200", - nonce="dj83hs9s", - mac="bhCQXTVyfj5cmA9uKkPFx1zeOXM=" -``` +{update_follower example} -```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" -} -``` - -```text -200 OK -Content-Type: application/json -``` - -```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 -```text -DELETE /followers/775ecf8 -Authorization: MAC id="775ecf8", - ts="1336363200", - nonce="dj83hs9s", - mac="bhCQXTVyfj5cmA9uKkPFx1zeOXM=" -``` +{delete_follower example} -```text -204 No Content -``` ## Notifications Notification from titanous.com to danielsiders.com that new content has been posted. -### POST /notifications -```text -POST /notifications -Content-Type: application/json -Authorization: MAC id="775ecf8", - ts="1336363200", - nonce="dj83hs9s", - mac="bhCQXTVyfj5cmA9uKkPFx1zeOXM=" -``` - -```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": "0.1.0", - "view": "full" - }, - "text": "Tent.io is awesome!" - } - } -] -``` - -### POST /notifications - -```text -POST /notifications -Content-Type: application/json -Authorization: MAC id="775ecf8", - ts="1336363200", - nonce="dj83hs9s", - mac="bhCQXTVyfj5cmA9uKkPFx1zeOXM=" -``` - -```json -[ - { - "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": "0.1.0", - "view": "full" - }, - "id": "jA4Mzdh", - "entity": "titanous.com", - } - } -] -``` ## Fetch Post Feed @@ -406,83 +135,3 @@ Authorization: MAC id="775ecf8", - -```text -GET /posts -Accept: application/json -Authorization: MAC id="775ecf8", - ts="1336363200", - nonce="dj83hs9s", - mac="bhCQXTVyfj5cmA9uKkPFx1zeOXM=" -``` - -```text -200 OK -Content-Type: application/json -``` - -```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": "0.1.0", - "view": "full" - }, - "text": "Tent.io is awesome!" - } - } -] -``` - -## Fetch Single Post - -### GET /posts/:id - -```text -GET /posts/jA4Mzdh -Accept: application/json -Authorization: MAC id="775ecf8", - ts="1336363200", - nonce="dj83hs9s", - mac="bhCQXTVyfj5cmA9uKkPFx1zeOXM=" -``` - -```text -200 OK -Content-Type: application/json -``` - -```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": "0.1.0", - "view": "full" - }, - "text": "Tent.io is awesome!" - } -} -```