 |
You are not logged in. Log in |
 |
Roadmap DraftFrom $1Table of contents
OverviewAccount Service is the public REST API into the notify.me service. The API serves both end users and notification sources
AuthenticationThe notify.me API provides two mechanisms for providing authentication information:
Both forms of authentication are used to provide the same authentication token to the API. For security reasons, this authentication token is temporary and tied to the client's IP. Any client using the notify.me API must be able to to cope with 401 - Unauthorized response (which includes a Location header for the authentication endpoint) and re-authenticate before continuing. An example authentication workflow follows:
Since the auth token is tied to an IP, clustered client services CANNOT share a single authtoken, but MUST go through the above authetication flow and persist their authentication token locally. Exposing Sources for Customers to subscribe toThe GET Uri of a source is also it's identifier for subscription. I.e. if a customer provides this uri as a source in the notify.me webapp or via the IM client and that source is marked public, we will automatically subscribe user to that source. Global HeadersNote on Headers: By rfc2616, Http header field names are case-insensitive, i.e. while this document describes headers in mixed-case, it is not guaranteed that the API will return them as such, nor does it have any expectations of them being sent in any particular casing. X-Api-VersionAll API keys should include an X-Api-Version header to indicate the compatibility mode desired. If omitted, the current API compatibility level is assumed X-AuthTo be used for authentication by clients that cannot use cookie authentication X-GrantThe grant token for authorizing modification of another account's subscription on their behalf. Data TypesLegal Id ValuesA resource id is specified as part of a URI as an alphanumeric ID. {sourceid}, {notificationid} and {subscriptionid} are both resource id's and are created either by:
Account Data<account>
...
</account>
Account Settings<account>
<settings>
...
</settings>
</account>
Grant<grant id="..." href="...">
<description>...</description>
<authtoken>...</authtoken>
<!-- grantee is optional -->
<grantee id="...">
</grant>
The Grant authtoken is used as the X-Grant header by a third party account (grantee) to be able to modify subscriptions on the grantor's account, but limited to only to subscriptions to grantee's sources. Grants can be either global, i.e. any third party can use it, or locked down to a specific grantee. Either way, it limits modifications to subscriptions on the grantor account to sources on the grantee account. Notification<notification id="..." href="..."> <uri>...</uri> <subject>...</subject> <body> ...</body> </notification> id and href are meta-daa about the notification returned by GET requests and are ignored if included in PUT or POST requests. id is the globally unique reference id for the notification associated on creation, while href is the canonical uri to the notification document. Source<source id="..." href="..." type="(email|api|rss)">
<name>...</name>
<!-- href to be used on source owner site to direct users to www.notify.me
to subscribe -->
<affiliate href="..." />
<!-- uri is optional and used to provide an information link about the source -->
<uri>...</uri>
<!-- rss href is only used for rss sources and denotes the rss feed uri -->
<rss href="..." />
<!-- email is used only for email sources -->
<email>...</email>
</source>
id and href are meta-data about the source returned by GET requests and are ignored if included in PUT or POST requests. id is the account unique reference id for the source, either generated by the API on POST or provided as part of the Uri on PUT, while href is the canonical uri to the source document. The default type (i.e. if omitted on create) is api, meaning that the source receives notifications from posts to the REST API. Subscription<subscription id="..." href="...">
<!-- if the source id isn't known, the source document can be included
to locate/create the appropriate the source (used by POST) -->
<source id="...">
<uri>...</uri>
...
<source>
<destination type="(email|xmpp|pingfm|sms|webhook)"/>
...
<!-- the webhook destination carries along destination and status information -->
<webhook enabled="(true|false)">
<uri>...</uri>
<last-request>
<date>...</date>
<status>...</status>
</last-request>
<avg-response>...</avg-response>
<disable-reason>...</disable-reason>
</destination>
...
</subscription >
id and href are meta-data about the subscription returned by GET requests and are ignored if included in PUT or POST requests. id is the account unique reference id for the subscription, either generated by the API on POST or provided as part of the Uri on PUT, while href is the canonical uri to the subscription document. FeaturesAccount InformationLegal {id} values for Accounts
Retrieve Account informationPath: GET:/accounts/{id} This feature provides basic account information. It's path also forms the root for all other account service features. Response
Response body <account>
<!-- see above -->
</account>
Retrieve authentication credential requirementsPath: GET:/accounts/{id}/authenticate This feature returns the challenge key that must be used to execute a successful authenticate PUT Response
Request body <authenticate>
<challenge>...</challenge>
</account>
Authenticate accountPath: POST:/accounts/{id}/authenticate This call must follow a GET on the same URL, since the request body must include the challenge and a response, which consists of an md5sum ofthe account password and the challenge contatenated like {password}{challenge} Request body <authenticate>
<challenge>...</challenge>
<response>...</response>
</account>
Response
Response body The reponse body will always be empty, but on Ok (200) the response will include a authentication cookie (for clients that can use cookies) and an X-Auth header which can be used in lieu of the cookie. Retrieve Account SettingsPath: GET:/accounts/{id}/settings This feature returns mutable settings, such as preferences for an account Response
Response body <account>
<settings>
<!-- see above -->
</settings>
</account>
Modify Account SettingsPath: PUT:/accounts/{id}/settings This feature provides basic account information. It's path also forms the root for all other account service features. Request body The request body should be a GET response document with the appropriate changes. The PUT expects the revision on the document and uses it for optimistic locking. I.e. if the current revision number is higher than the one in the request, a response of 409 - Conflict is issued, indicating that the resource has changed since it was last inspected. Response
Retrieve GrantsPath: GET:/accounts/{id}/grants This feature returns all grants issued by this account Response
Response body <grants>
<grant>
<!-- see above -->
</grant>
</grants>
Create a new GrantPath: POST:/accounts/{id}/grants Create a new grant Response
Response body
<grant>
<!-- see above -->
</grant>
Retrieve a specific GrantPath: GET:/accounts/{id}/grants/{id} This feature returns a grant document Response
Response body <grant>
<!-- see above -->
</grant>
Modify a specific GrantPath: PUT:/accounts/{id}/grants/{id} This stores the provided grant document as the new grant (re-generating an authtoken, none was provided Response
Response body <grant>
<!-- see above -->
</grant>
Revoke a specific GrantPath: DELETE:/accounts/{id}/grants/{id} Deleteds the specific grant, revoking it Response
NotificationsRetrieve notificationsPath: GET:/accounts/{id}/notifications This feature returns notifications that were addressed to the account. By default the response is limited it to the notifications received in the last hour. Request
Response
Response body <notifications>
<notification>
<!-- see above -->
</notification>
...
</notifications>
Post new notificationPath: POST:/accounts/{id}/notifications Post a new notification to the account. This posts the notification to the implicit source self. For any notification that should be received by a number of accounts, the post should be done against the source on the source owning account, i.e.
POST:/accounts/{id}/sources/{resourceid}/notifications
Request Body <notification>
<!-- see above -->
</notification>
Response
Response Headers
Retrieve specific notificationPath: GET:/accounts/{id}/notifications/{resourceid} This feature provides access to a specific notification that was delivered to the account Response
Response body <notification>
<!-- see above -->
</notification>
SourcesRetrieve all Sources for the accountPath: GET:/accounts/{id}/sources This feature returns all sources owned by the account Request
Response
Response body <sources>
<source>
<!-- see above -->
</source>
...
</sources>
Create a new Source on the accountPath: POST:/accounts/{id}/sources Post a registration of a new source available for subscription by other accounts that this account posts messages to Request Body <source>
<!-- see above -->
</source>
Response
Response Headers
Retrieve Source InformationPath: GET:/accounts/{id}/sources/{sourceid} Create a Source with a specific Id or Modify an existing SourcePath: PUT:/accounts/{id}/sources/{sourceid} Remove an existing SourcePath: DELETE:/accounts/{id}/sources/{sourceid} Retrieve notifications posted to the SourcePath: GET:/accounts/{id}/sources/{sourceid}/notifications See GET:/accounts/{id}/notifications Post new notification to the sourcePath: POST:/accounts/{id}/sources/{sourceid}/notifications See POST:/accounts/{id}/notifications Retrieve a specific notification posted to the SourcePath: GET:/accounts/{id}/sources/{sourceid}/notifications/{notificationid} See GET:/accounts/{id}/notifications/{notificationid} SubscriptionsRetrieve all Source Subscriptions for the accountPath: GET:/accounts/{id}/subscriptions This feature returns all subscriptions for the account Request
Response
Response body <subscriptions>
<subscription>
<!-- see above -->
</subscription>
...
</subscriptions>
Create a new Subscription for an unknown sourcePath: POST:/accounts/{id}/subscriptions Post a subscription, locating or creating the included source Request Body <subscription>
<!-- the source information for the subscription (locates or creates source) -->
<source>
<uri>...</uri>
...
<source>
...
<!-- see above -->
</subscription>
Response
Response Headers
Retrieve Subscription InformationPath: GET:/accounts/{id}/subscription/{sourceid} Create or modify a new Subscription to a sourcePath: PUT:/accounts/{id}/subscriptions/{sourceid} Create or modify a subscription to a source Request Body <subscription>
<!-- see above -->
</subscription>
Response
Remove an existing SubscriptionPath: DELETE:/accounts/{id}/subscription/{sourceid} Retrieve notifications posted to the SubscriptionPath: GET:/accounts/{id}/subscription/{sourceid}/notifications See GET:/accounts/{id}/notifications
Tags:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||