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

The draft API supports creating drafts, updating already saved drafts, and publishing drafts on site.

.. _creating-drafts:

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

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

.. code::

   POST /api/1.3/drafts

.. important::

   We provide another endpoint for backward compatibility with 1.1 API version:

   .. code::

       POST /api/1.1/posts

Parameters
**********

.. include:: posts-fields.rst

Response
********

The response can contain several fields, but would like to highlight some of them that were
specially requested:

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

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

Publishes a draft.

.. code::

   PUT /api/1.3/drafts/<id>

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

In addition to the specification from updating drafts, an "action" parameter with
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 response payload when publishing a draft.
   * Stored data from the draft will be published if not received updated data is coming
     within request payload.

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

Fetch all drafts ordered by recency on publish date.

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

This resource returns an array of objects with the specification described on
:ref:`creating-drafts`.

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

.. code::

   GET /api/1.3/drafts/<id>

Response
********

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