REST API

Client Implementations

Overview

Account Service is the public REST API into the notify.me service. The API serves both end users and notification sources

Authentication

The notify.me API provides two mechanisms for providing authentication information:

• An auth cookie (for client frameworks supporting the persistence of cookies)
• An X-Auth Header (in case cookies are not supported)

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:

1. Client calls some API uri, such as GET:/accounts/{id}/notifications
2. Server responds with 401 - Unauthorized, provideing a Location of http://{server}/accounts/{id}/authenticate
3. Client MUST do a GET on the authentication URI, generally GET:/accounts/{id}/authenticate to retrieve the authentication challenge
4. Client computes the response to the Server challenge
   1. Client constructs a string from the account password and the challenge node content, like {password}{challenge}
   2. Client creates an encoded md5sum hash from the {password}{challenge} string
   3. Client constructs an authentication document including the challenge and the computed response
5. Client POSTs the authentication document at POST:/accounts/{id}/authenticate
6. Upon verfication of the response string, Server responds with a 200 - Ok, including an auth cookie and an X-Auth header, either one of which can be used for authentication
7. Client resumes, by calling the original URI providing the new authentication credentials

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 Users to subscribe to

The href attribute of the affiliate element that is returned in with the following call GET:/accounts/{id}/sources provides a uri that a customer can post for users to subsribe to that source. You can get a notify.me badge for your site from the following page: Notify.me Affiliate Program.

Global Headers

Note 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.

Data Types

<notification id="..." href="...">
  <uri>...</uri>
  <subject>...</subject>
</notification>

<source id="..." href="...">
    <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>
</source>

Features

<authenticate>
    <challenge>...</challenge>
</authenticate>

<authenticate>
    <challenge>...</challenge>
    <response>...</response>
</authenticate>

<sources>
    <source>
        <!-- see above -->
    </source>
    ...
</sources>

<source>
    <!-- see above -->
</source>