Confirmed users
169
edits
Services/F1/Server/API: Difference between revisions
→GET /response
Mixedpuppy (talk | contribs) No edit summary |
Mixedpuppy (talk | contribs) |
||
| (7 intermediate revisions by 3 users not shown) | |||
| Line 2: | Line 2: | ||
Status: brain dump | 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 [http://www.freesoft.org/CIE/RFC/2068/201.htm 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 === | === Security === | ||
| Line 58: | Line 70: | ||
=== OAuth APIs === | === 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 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). | ||
| Line 79: | Line 93: | ||
The status codes generally follow HTTP status codes. | 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 ==== | ==== POST /send ==== | ||
| Line 103: | Line 128: | ||
Any number of other parameters may be sent. They will be silently dropped by any given service implementation if the parameter is not understood. | 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 ==== | ==== GET /response ==== | ||
[NOT IMPLEMENTED] | |||
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. | |||