Preliminaries

1. Please see the taglets.org site overview here.
2. The API is still under development, and can change at any time.
3. All API calls are made to host http://api.taglets.org, or, for secure connections, https://api.taglets.org.  You can obtain the secure site's certificate authority cert in the here.
   
4. See the Java reference implementation for the Taglets public API here.  The license is Apache2.
   
5. There are a few public API related examples and recipes here.

---

Account methods

Register account

    Method:  POST
    URL:  /account/register
    Body:  email=<email address>&password=<password>&sitename=<sitename>&confirmurl=<confirmurl>&adminmail=<adminmail>&homeurl=<homeurl>
    Requires session/auth:  no
    Returns: 
       Success:  201 Created
       Fail:  412 Precondition Failed if account already exists; 422 Unprocessable Entity for platform error; 400 Bad Request for invalid email address; 403 Forbidden for an invalid password; 410 Gone for rate limit exceeded; 500 Internal Server Error for request timeout

    Notes:

• 201 Created results in confirmaton email being sent to <email address>.
• sitename, confirmurl, adminmail, and homeurl are optional.  Defaults are: 'Taglets.org' 'http://www.taglets.org/confirm' 'support@taglets.org' and 'http://www.taglets.org' respectively.
• the email address is checked for proper form, and passwords must be 5-16 characters in length, taken from the set of letters digits and . - _
  

Confirm account registration

    Method:  GET
    URL:  /account/confirm/{confirmationKey}
    Body:  n/a
    Requires session/auth:  no
    Returns:
        Success:  201 Created
        Fail:  404 Not Found for wrong key or confirmation not pending; 422 Unprocessable Entity for platform error; 410 Gone for rate limit exceeded; 500 Internal Server Error for request timeout.

Retrieve account information

    Method:  POST
    URL:  /account/retrieve
    Body:  email=<email address>&password=<password>
    Requires session/auth:  yes
    Returns:
        Success:  200 OK
        Fail: 412 Precondition Failed for failed authentication or user unknown; 410 Gone for rate limit exceeded; 500 Internal Server Error for request timeout.
    Notes:

• Upon success, a self explanatory XML representation of the user.
  

Remind password

    Method:  POST
    URL:  /account/remind
    Body:  email=<email address>&sitename=<sitename>&adminmail=<adminmail>&homeurl=<homeurl>
    Returns:
        Success:  200 OK
        Fail:  412 Precondition Failed for unknown user; 410 Gone for rate limit exceeded; 500 Internal Server Error for request timeout.
    Notes: 

• An email reminder is sent to the user upon success.
• sitename, adminmail, and homeurl are optional.  Defaults are: 'Taglets.org' 'support@taglets.org' and 'http://www.taglets.org' respectively

 

---

Add a Twitter account to a user profile

Method:  POST
    URL:  /twitter/add
    Body:  email=<email address>&password=<password>&tuid=<Twitter username>
    Requires auth:  yes
    Returns: 
        Success:  201 CREATED
        Fail:  412 Precondition failed for authentication failed or unknown user; 410 Gone for rate limit exceeded; 500 Internal Server Error for timeout
    Notes:

• Adds a Twitter account to the user profile.  The Twitter account must be verified and confirmed before it can be added as an outlet.

Verify a Twitter account

Method:  POST
    URL:  /twitter/verify
    Body:  email=<email address>&password=<password>
    Requires auth:  yes
    Returns: 
        Success:  201 CREATED
        Fail:  412 Precondition failed for authentication failed or unknown user; 409 Conflict for Twitter send-direct of confirmation pin failed; 400 Bad Request pin slots full; 410 Gone for rate limit exceeded; 500 Internal Server Error for timeout
    Notes:

• Verifies a Twitter account in the user profile.  Between /twitter/add and this call, the Twitter user must follow Twitter user taglets.  Twitter user taglets will send a confirmation PIN to the Twitter user configured in /twitter/add via direct message.
  

Confirm a Twitter account

Method:  POST
    URL:  /twitter/confirm/{confirmationPin}
    Body:  email=<email address>&password=<password>
    Requires auth:  yes
    Returns: 
        Success:  201 CREATED
        Fail:  412 Precondition failed for authentication failed or unknown user; 404 Not Found for confirmation not pending or pin not found; 409 Conflict for platform or db error;  411 Length Requred for invalid pin format; 410 Gone for rate limit exceeded; 500 Internal Server Error for timeout
    Notes:

• Confirms and activates a Twitter account for use in comment outlets.  This call follows /twitter/verify, where confirmationPin is the PIN sent to the Twitter user via direct message in /twitter/verify.
  

---

Tag methods

Create a tag

    Method:  POST
    URL:  /tag/create/{tagName}
    Body:  email=<email address>&password=<password>&description=<tag description>&comment=<tag comment>&sitename=<sitename>&adminmail=<adminmail>&homeurl=<homeurl>
    Requires auth:  yes
    Returns: 
        Success:  201 CREATED
        Fail:  412 Precondition failed for authentication failed or no such user; 400 Bad Request for invalid tag name; 409 Conflict for tag name exists; 410 Gone for rate limit exceeded; 422 Unprocessable Entity for platform error; 500 Internal Server Error for request timeout
    Notes:

• tag names are limited to 16 characters total length,  must begin with a letter or a digit, and thereafter consist of a letter or digit or one of the characters [- # @ _ .] (brackets not included)
  
• descriptions will be silently truncated to 120 characters
  
• the comment parameter is optional
• neither the tag name or description are treated as case sensitive
• Upon success, the user is automatically following the new tag with an email outlet
• sitename, adminmail, and homeurl are optional.  Defaults are: 'Taglets.org' 'support@taglets.org' and 'http://www.taglets.org' respectively

Edit a tag description

    Method:  POST
    URL:  /tag/update/{tagname}
    Body:  email=<email address>&password=<password>&description=<new description>
    Requires auth:  yes
    Returns: 
        Success: 
            201 CREATED for a successful update
        Fail:  412 Precondition failed for authentication failure or unknown user; 403 Forbidden for user unauthorized to edit tag; 404 Not Found for tag does not exist; 410 Gone for rate limit exceeded; 500 Internal Server Error for timeout

Follow or unfollow a tag

    Method:  POST
    URL:  /tag/follow/{tagid}
    Body:  email=<email address>&password=<password>&mode={true | false}
    Requires auth:  yes
    Returns: 
        Success: 
            200 OK if the tag is already being followed for mode==true
            200 OK if the tag is not being followed for mode==false
            200 OK if the tag is followed and mode==false
            201 Created if the tag is not being followed and mode==true
        Fail:  412 Precondition failed for authentication failure or unknown user; 403 Forbidden for invalid follow mode; 404 Not Found for tag does not exist; 410 Gone for rate limit exceeded; 500 Internal Server Error for timeout
    Notes:
mode==true means follow; mode==false means unfollow.  Those are the only allowed modes.

Get follow status for a tag

    Method:  POST
    URL:  /tag/status/{tagid}
    Body:  email=<email address>&password=<password>
    Requires auth:  yes
    Returns: 
        Success:  200 OK if the tag status can be ascertained
        Fail:  412 Precondition failed for authentication failed or unknown user; 404 Not Found for tag does not exist; 410 Gone for rate limit exceeded; 500 Internal Server Error for timeout
    Notes:

• For 200 OK, self explanatory XML is returned in the response body to indicate the tag status
  

Get followed tags for authenticated user

    Method:  POST
    URL:  /tag/list
    Body:  email=<email address>&password=<password>
    Requires auth:  yes
    Returns:
        Success:  200 OK
        Fail:  412 Precondition Failed for authentication failed or unknown user; 410 Gone for rate limit exceeded; 500 Internal Server Error for timeout
    Notes:

• output is self-explanatory XML
  

Post a comment about a tag

    Method:  POST
    URL:  /tag/comment/{tagid}
    Body: comment=<free form text, 120-130 or so char limit (should fit in a tweet, leaving room for @userid)>&sitename=<sitename>&adminmail=<adminmail>&homeurl=<homeurl>
    Requires auth:  no
    Returns:
        Success:  201 Created
        Fail:  403 Forbidden for tag is suspended for comments; 404 Not Found for tag does not exist; 410 Gone for rate limit exceeded; 500 Internal Server Error for timeout
   Notes:   

• Comment is truncated on the server side to maximum comment size, currently 120 characters.
  
• sitename, adminmail, and homeurl are optional.  Defaults are: 'Taglets.org' 'support@taglets.org' and 'http://www.taglets.org' respectively

Search all tags

    Method:  POST
    URL:  /tag/search
    Body:  email=<email address>&password=<password>&keywords=<space-separated list of keywords>
    Requires auth:  yes
    Returns:
        Success:  200 OK
        Fail:  412 Precondition Failed for authentication failed or unknown user; 410 Gone for rate limit exceeded; 500 Internal Server Error for timeout
    Notes:

• 412 Precondition failed means authentication failed.
• The method searches the entire tag space, not just the space of tags followed by this user.
  
• The order of the keywords is not significant and is not taken into account in the search.
• Keywords are treated case insensitively.
  
• output is self-explanatory xml

Retrieve a tag

    Method:  GET
    URL:  /tag/retrieve/{tagname}
    Body:  n/a
    Requires auth: no
    Returns:
        Success:  200 OK
        Fail:  404 Not Found if tag does not exist; 410 Gone for rate limit exceeded; 500 Internal Error for timeout
    Notes:

• The tagname is not case sensitive.
  
• For 200 OK, output is self-explanatory xml.

Get most commented tags

    Method:  GET
    URL:  /tag/mostcomment/{n}
    Body:  n/a
    Requires auth: no
    Returns:
        Success:  200 OK
        Fail:  410 Gone for rate limit exceeded; 500 Internal Error for server timeout or other error
    Notes:

• For 200 OK, output is self-explanatory xml.
• n is a positive integer that limits the output to n tags
• order of output is descending number of comments
  

Get most recently created tags

    Method:  GET
    URL:  /tag/mostrecent/{n}
    Body:  n/a
    Requires auth: no
    Returns:
        Success:  200 OK
        Fail:  410 Gone for rate limit exceeded; 500 Internal Error for server timeout or other error
    Notes:

• For 200 OK, output is self-explanatory xml.
• n is a positive integer that limits the output to n tags
• order of output is reverse chronological
  

---

Comment delivery outlet binding methods

Bind or Unbind a Comment Outlet

    Method:  POST
    URL:  /outlet/bind
    Body:  The body for all requests must contain:  email=<email address>&password=<password>&tagname=<tagname>&mode={true | false}

    Requires auth:  yes
    Returns:
        Success:  201 Created for adding bindings; 200 OK for successful binding deletions
        Fail:  412 Precondition failed for authentication failed or unknown user; 415 Unsupported Media Type for user is not following this tag; 400 Bad Request for invalid outlet protocol; 403 Forbidden for invalid binding mode, 404 Not Found for tag does not exist; 406 Not Acceptable for outlet is unconfirmed; 410 Gone for rate limit exceeded; 500 Internal Server Error for timeout
    Notes: 

• The outlet is bound by the tuple [user,tag], so both must be provided.
• An email outlet can only be bound to the email address of the authenticating user.
  
• The request must contain exactly one outlet with its associated parameters.  Other combinations are undefined.
  
• mode=true binds the outlet; mode=false unbinds the outlet.
• Twitter outlet binding requires that the calling user has added, verified, and confirmed the Twitter userid.

---