This is a rough outline of the required methods needed to meet the working specification of FPS (Federated Packet Service or Federated Micro Publishing).

 

Core API Methods

 

Publisher Token Exchange

The purpose of the publisher_token methods are to enabled autonomous Consumer-Provider (under OAuth) key exchange so that all future federated requests may be validated using OAuth.

 

 

GET   /api/fps/publisher_token

Parameters:

  domain - the requester's domain, source of the method call

  nonce    - a randomized, unique string

 

The GET request of the publisher_token method takes two parameters (domain, nonce). Domain should be the calling service and must respond to a POST to publisher_token from the destination service (key provider). The nonce parameter is used as a verification for the calling domain.

 

POST /api/fps/publisher_token

Parameters:

  domain  - the source domain, the POSTer

  nonce     - a randomized, unique string supplied by the GET token requester (from above)

  consumer_key - a Consumer key under the OAuth specification

  consumer_secret - a Consumer secret under the OAuth specification

 

A POST to publisher_token occurs on the requesting domain after a GET request for publisher_token. The consumer_key/secret is inconsequential and self-created by the source service. Upon receiving a POST with valid domain/nonce, the destination service (original requester by GET publisher_token) must save the key/secret in order to create valid OAuth requests on the POSTing service.

 

POST /api/fps/share_token

Parameters:

  publisher   - user@domain (a user on the destination service)

  subscriber  - user@domain (a user on the calling service)

  request_token - Under OAuth, a public key

  request_token_secret - Under OAuth, a secret key

 

Used in subscribing for the publishing service to request an access token from the Subscriber. The access tokens provided (oauth_token and oauth_token_secret) should be stored on both the subscriber and publisher for federated authentication. This method goes hand-in-hand with the subscribing node's subscribe method (unspecified).

 

POST /api/fps/unshare_token

Parameters:

  [OAuth request, reverse] - valid/authenticate OAuth req.

 

 

Similar to share_token, but uses already established key-sharing, but in reverse. Reverse by, the same keys which the publisher uses to post to subscriber are used to unshare the token access; this goes hand-in-hand with the subscribing node's unsubscribe method (unspecified).

 

POST /api/fps/access_token

Parameters:

  request_token - The request token, as shared by a Subscriber

  request_token_secret - The request token secret, as shared by the Subscriber

  [other Parameters according to OAuth, Consumer key exchange should already have taken place]

 

 

Publishing Methods

 

POST /api/fps/publish

Parameters:

  id - The ID of the packet on the publishing node (for permalinking, editing, removing).

  ns - Namespaces associated with the packet (for organizing and indexing, optional).

  packet - Valid XML fps packet <fps>...</fps>

  [other Parameters according to OAuth, Consumer key exchange should already have taken place]

 

Publish allows a publisher to distribute packets to their subscribers, after OAuthentication. Namespaces may be used in order for themes/plugins/handlers to render the packet-data in customized ways (these are not part of the specification). Multiple namespaces should be comma-delimited. The packet may have any valid XML contents, but some services may restrict packet size (unspecified, recommended 5Kb).

 

Upon success, the subscribed node should return a message containing the number of subscribers reached.

 

POST /api/fps/republish

[see publish from above]

 

The purpose of the republish method is for allowing publisher to edit their data. Rather than writing a new packet to the service, all identification is maintained, but the packet content (whether inside a database or flat file storage) should be updated with the new packet. The ID should be the local ID of the packet.

 

POST /api/fps/unpublish

Parameters:

  id - The ID of the packet on the publishing node.

  [other Parameters according to OAuth, Consumer key exchange should already have taken place]

 

Unpublishing allows publishers to remove their messages from subscriber nodes, for whatever reason.

 

Questions/Comments

 

Why are subscribe and unsubscribe methods not specified?

 - These methods are bound to local nodes and do not play a part in the federation core. They act to instantiate some of the above specified methods (namely share_token), but only locally authorized users should be allowed subscribe (across the federation).

 

Why is a dispatch method not specified?

 - The dispatch is a key component to publishing as it may be serial or parallelized for efficiency. This is also in the hands of the local node and only serves as a gateway for local packets to be distributed to subscriber nodes via the publish method.