Drafts API
==========

.. contents:: :depth: 2

The draft API supports the creation of new drafts, updating saved drafts, and publishing drafts on site.

.. _creating-drafts:

Creating drafts
---------------

Creates a draft and sets the current user as the author by default.


.. code::

   POST /api/1.3/drafts

Parameters
**********

.. include:: includes/posts-fields.rst

Response
********

The response will most likely contain several fields, but the following are some important ones to take note of:

============= ====== ===================================================================================
Name          Type   Description
============= ====== ===================================================================================
``post_url``  String URL for the draft when is published.
``draft_url`` String Composited by ``post_url`` + ``"?draft=1"``, which enables users to see draft page.
``slug``      String URL path from ``post_url``.
============= ====== ===================================================================================

Editing drafts
--------------

Edits a draft.

.. code::

   PUT /api/1.3/drafts/<id>

Parameters and Response
***********************

The same specification from :ref:`creating-drafts` applies here.

.. important::

  For PUT requests, if ``roar_author_ids`` is sent with no value, then the user identified with the API key received is assigned as the unique author.

  If ``roar_author_ids`` is not sent, then the author value will not be modified.

Publishing drafts
-----------------

Publishes a draft.

.. code::

   PUT /api/1.3/drafts/<id>

Parameters and Response
***********************

In addition to the specifications from updating drafts, an "action" parameter with the
value "publish" can be sent to API in order to publish a draft.

+-----------------+---------+---------------------------+
|Name             |Type     |Description                |
+=================+=========+===========================+
|``action``       |String   || Action to be performed.  |
|                 |         || Optional.                |
|                 |         || Choices:                 |
|                 |         |                           |
|                 |         | - ``"publish"``           |
+-----------------+---------+---------------------------+

.. note::

   * ``draft_url`` is not returned in the response payload when publishing a draft.
   * Stored data from the draft will be published if unreceived updated data is coming
     within request payload.

Deleting drafts
---------------

Deletes a draft.

.. code::

   DELETE /api/1.3/drafts/<id>

Response
********

The response payload is an empty object.

.. code:: json

   {}

List drafts
-----------

Fetch all drafts ordered by most recently published.

.. code::

   GET /api/1.3/drafts

Parameters
**********

====================== ======= ===========================================================================
Name                   Type    Description
====================== ======= ===========================================================================
``offset``             Integer Offset -- Optional
``limit``              Integer Limit -- Optional, defaults to 10, maximum value is 30
``removed``            Integer Removed posts -- Optional, removed articles will be listed only if received
====================== ======= ===========================================================================

Response
********

Returns an array of objects with the same specifications as
:ref:`creating-drafts`.

Get a single draft
------------------

.. code::

   GET /api/1.3/drafts/<id>

Response
********

The same specifications as :ref:`creating-drafts` apply here.