• USERS
• Login
• Activate Login Link
• Logout
• POSTS
• Read a Post
• Create a New Post
• Update a Post

Wren API

#wren

USERS

Login

The author's email address is stored in the YAML file. To login, only the email address is provided. The Wren app uses the MailGun service to send the message that contains the login activation link.

This uses a POST request to /users/login that sends the following JSON:

{
  "email" : "jothut@fastmail.fm", 
  "url"   : "http://wren.soupmode.com/nopwdlogin"
}

Curl example:

curl -X POST -H "Content-Type: application/json" --data '{ "email" : "jothut@fastmail.fm", "url" : "http://wren.soupmode.com/nopwdlogin"}' http://wren.soupmode.com/api/v1/users/login

Returned JSON if successful:

{
  "status":200,
  "description":"OK",
  "user_message":"Creating New Login Link",
  "system_message":"A new login link has been created and sent."
}

The session_id_digest value is only included in the returned JSON when debug_mode equals 1 in the YAML config file. This value is included on the login link that is emailed to the author.

Activate Login Link

This uses a GET request to /users/login/?rev=[session_id_digest].

This activation process can occur only one time. A flag is set in the session ID file that prevents the login link from being used again.

[session_id_digest] is the alpha-numeric string attached to the end of the login link emailed above.

This login activation process can occur only one time. A flag is set in the session file for this digest.

Curl example:

curl http://wren.soupmode.com/api/v1/users/login/?rev=Dhcs6CkF

If the request to login is successful, then the API returns the following JSON:

{
  "status":200,
  "description":"OK",
  "author_name":"cawr",
  "rev":"Dhcs6CkF",
  "session_id":"iqQT4QJSDNfYWSzzQYMQ0g"
}

The author_name, rev, and session_id values are stored as cookies in the author's browser. This information is sent to the API for actions that require authentication.

Logout

This uses a GET request to:

/users/logout/?author=[author_name]&session_id=[session_id]&rev=[rev]

Curl example:

curl http://wren.soupmode.com/api/v1/users/logout/?author=wren\&session_id=iqQT4zQYMQ0g\&rev=Dhcs6CkF

Returned JSON if successful:

{
  "status":200,
  "description":"OK",
  "logged_out":"true"
}

POSTS

Read a Post

This uses a GET request to /posts/[page_id] where page_id equals the slug.

Example: http://wren.soupmode.com/info.html

Retrieve the info.html markup:

curl http://wren.soupmode.com/api/v1/posts/info

Returned JSON:

{
  "status":200,
  "description":"OK",
  "slug":"info",
  "markup":"# Info\r\n\r\n* [Tags](/tags.html)\r\n* [RSS feed](/rss.xml)\r\n* [JSON feed](/links.json)\r\n* [Sitemap XML](/sitemap.xml)\r\n* [Microformatted List of Posts](/mft.html)\n"
}

If the post was stored in a sub-directory, then the request would be like this example:

curl http://wren.soupmode.com/api/v1/posts/2016/03/30/cold-temps-expected-during-the-first-week-of-april-2016.html

The extension .html is optional. If it exists, the API code ignores it.

Within the returned JSON, slug may be a misnomer, since in the above example, slug equals 2016/03/30/cold-temps-expected-during-the-first-week-of-april-2016.

Technically, the slug would be the text that follows the last forward slash. But I permitted this exception to allow storing posts in sub-directories.

It's also possible to ignore the API code and access the .txt version of a post under document root, which contains the markup.

• HTML = http://wren.soupmode.com/info.html
• Markup = http://wren.soupmode.com/info.txt

Create a New Post

Uses a POST request to /posts with the following JSON being submitted as an example:

{
  "author"      : "MrX", 
  "session_id"  : "5012344558568686", 
  "rev"         : "g8ke3R",
  "submit_type" : "Post", 
  "markup"      : "# Test Post 4Apr2016 1937\n\nHello World"
}

submit_type can be either Post or Preview.

curl X POST H "ContentType: application/json" -data '{"author": "MrX", "session_id": "5012344558568686", "rev":"g8ke3R", "submit_type": "Post", "markup": "# Test Post 4Apr2016 1937\n\nHello World"}' http://wren.soupmode.com/api/v1/posts

If the "submit_type":"Post" request was successful, then JSON similar to this will be returned:

Update a Post