Services/F1/Server/API

Share Server API

Status: brain dump

Dependencies

• Portable Contacts. All profile or contact data is in Portable Contacts format.

X-Target-Domain

All APIs must be called with a X-Target-Domain header. The header contains the name of the domain that is being called through the server. This header is used by the server to determine if the service for the domain is available or not.

If the domain is not available, the client will immediately receive a 503 with a Retry-After header, the value will be the number of seconds to wait before retrying. The RFC for Retry-After also allows for a timestamp, but the server will be sending a number that represents seconds.

The client will then need to wait for that time before retrying. In the interim, the client is allowed to call the server for other services.

Security

The servers do not store any user account information, the service stores all important user data on the client. All API endpoints MUST be provided ONLY over SSL. User account data sent for each API call in the clear, depending on SSL for security and privacy.

Share Authorization

The Share Authorization is essentially an authorization proxy supporting OpenID+OAuth, OAuth 1 and OAuth 2. All authorization data is returned to and stored on the client.

POST /authorize

Initiates the OAuth dance for a given OAuth provider. The browser will be redirected to the OAuth endpoint for the service, providing a return url pointing to the verify endpoint described below.

Post Data:

domain: google.com

Success Result

Upon a successful authorization the OAuth providers redirect back to the verify endpoint, using GET or POST depending on the service implementation.

Error Result

If the user cancels the authorization, we cannot depend upon a redirect back to the f1 server; some services do, others do not.

GET|POST /verify

For a successful authorization, the verify endpoint will create a temporary cookie (account_tokens) to pass the users OAuth tokens back to the client. The client MUST delete this cookie after retrieving the account data. This account data also contains a POCO formatted profile object for the user that is retrieved from that service. The endpoint then redirects to the configured success or error url.

Example cookie data:

[bug 642980 for cleanup]

{
"username": "mozmotest", 
"profile": {
  "displayName": "Shane Carav\u0119o", 
  "providerName": "Twitter", 
  "photos": [{
     "type": "profile", 
     "value": "url to image"}], 
  "accounts": [{
     "username": "mytestaccount", 
     "domain": "twitter.com", 
     "userid": 1234567890}], 
  "published": "Thu Sep 02 19:53:53 +0000 2010", 
  "identifier": "http://twitter.com/?id=1234567890"}, 
"domain": "twitter.com", 
"oauth_token_secret": "My Super Secret OAuth Token", 
"userid": "1234567890", 
"updated": "2011-03-18T14:03:58.742713", 
"oauth_token": "My less than secret OAuth token", 
"key": "3e464104-51a3-11e0-9b46-d49a200eaa62"
}

OAuth APIs

Request and Response bodies

All APIs require POST and part of the post data must be the account object that was received via the account_tokens cookie (see the verify endpoint above).

All api's return a json object with the following format:

{
result: {} | NULL
error: {} | NULL
} 

If the result is valid, error will be NULL, and if there is an error, result will be NULL.

The error object consists of the following data:

{
'status': status code, integer
'provider': domain of the service provider
'message': text message, not necessarily usable for UI
}

The status codes generally follow HTTP status codes.

Status codes:

• 200: ok, message sent, response object in body, used for synchronous calls
• 202: message has been queued, client must call response api to find the result (NOT IMPLEMENTED, suggested for async version of server)
• 400: TODO under which conditions?
• 401: authorization required (e.g. oauth tokens may be expired)
• 403: TODO under which conditions?
• 502: remote service (e.g. twitter) is temporarily unavailable, try again later
• 503: share service is temporarily unavailable

POST /send

The send API is used to share a link to a service.

Request Arguments:

• domain (string): Domain of service to share to (google.com for gmail, facebook.com, twitter.com)
• username (string): Optional username, required if more than one account is configured for a domain.
• userid (string): Optional userid, required if more than one account is configured for a domain.
• account (object): json formatted account object retrieved during OAuth authorization
• link (string): URL to share
• message (string): Message entered by user

• shorturl (string): Shortened version of URL to share
• shorten (boolean): Force a shortening of the URL provided
• to (string): Individual or group to share with, not supported by all services.
• subject (string): Subject line for emails, not supported by all services.
• picture (string): URL to publicly available thumbnail, not supported by all services.
• picture_base64 (string): Base 64 encoded PNG version of the picture used for attaching to emails.
• description (string): Site provided description of the shared item, not supported by all services.

Any number of other parameters may be sent. They will be silently dropped by any given service implementation if the parameter is not understood.

POST /contacts

The contacts api is used to retrieve the users contacts for a given service. The contacts are used to provide direct sharing functionality.

Request Arguments:

• domain (string): The domain of the service to get contacts from (e.g. google.com)
• username (string): The user name used by the service. The username or userid is required if more than one account is setup for the service.
• userid (string): The user id used by the service. The username or userid is required if more than one account is setup for the service.
• startindex (integer): Start index used for paging results.
• maxresults (integer): Max results to be returned per request, used with startindex for paging.
• group (string): Name of the group to return.
• account (object): json formatted account object retrieved during OAuth authorization

Successful responses will contain a POCO formatted response object:

{
'entry': array of poco objects,
'itemsPerPage': items_per_page,
'startIndex':   start_index,
'totalResults': total_results,
}

See Portable Contacts for more details.

GET /response

The response api is used to retrieve responses to other api calls.

Request Arguments:

transaction_id: guid or other key

Response:

As defined by the APIs above.