# Wren API

markdown=yes

 #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 "Content-Type: 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