Posts API ========= .. contents:: :depth: 2 The post API supports updating already published content as well as un-publishing posts. .. _creating-posts: Creating posts -------------- Creates a post and sets the current user as the author by default. .. code:: POST /api/1.3/posts Parameters ********** .. include:: includes/posts-fields.rst Response ******** The response will contain several fields, but here are two important ones to take note of: ============= ====== =================================================================================== Name Type Description ============= ====== =================================================================================== ``post_url`` String URL for the draft when is published. ``slug`` String URL path from ``post_url``. ============= ====== =================================================================================== Editing posts ------------- Edits a post. .. code:: PUT /api/1.3/posts/ Parameters ********** The same specification from :ref:`creating-posts` applies here, but the following additional parameters are available: +----------------------------------+---------+-------------------------------------------------------------------------+ | Name | Type | Description | +==================================+=========+=========================================================================+ | ``prevent_modifying_updated_ts`` | Integer || Controls whether the ``updated_ts`` is going to be modified - Optional | | | || Defaults to ``0``. It works only if a value is not sent in payload for | | | | ``updated_ts`` | | | || Choices available: | | | | | | | | - ``0`` to allow updating ``updated_ts`` | | | | - ``1`` to prevent updating ``updated_ts`` | +----------------------------------+---------+-------------------------------------------------------------------------+ .. 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. Response ******** The response structure here is the same as the response structure used for :ref:`creating-posts`. .. note:: * Unlike the drafts API, the posts API doesn't return the ``draft_url`` in the response payload unless the post was unpublished. Unpublishing posts ------------------ Unpublishes a post. .. code:: PUT /api/1.3/posts/ Parameters and Response *********************** In addition to the specifications for editing posts, an "action" parameter with the value "unpublish" can be sent to the API in order to unpublish a post. +-----------------+---------+---------------------------+ | Name | Type | Description | +=================+=========+===========================+ | ``action`` | String || Action to be performed. | | | || Optional. | | | || Choices: | | | | | | | | - ``"unpublish"`` | +-----------------+---------+---------------------------+ .. note:: * ``draft_url`` is returned in response payload when unpublishing a post. Deleting posts -------------- Deletes a post. .. code:: DELETE /api/1.3/posts/ Response ******** The response payload is an empty object. .. code:: json {} Get a single post ----------------- Fetch a single post by ID. .. code:: GET /api/1.3/posts/ Response ******** The response structure here is the same as the response structure used for :ref:`creating-posts`. List posts ----------- Fetch all posts ordered by most recent publish date. .. code:: GET /api/1.3/posts Parameters ********** =========================== ========= ============================================================================================================================== Name Type Description =========================== ========= ============================================================================================================================== ``offset`` Integer Offset -- Optional ``limit`` Integer Limit -- Optional, defaults to 10, maximum value is 100 ``provider_id`` Integer Provider of Post -- Optional, defaults to 20 (Public API) if ``provider_post_id`` is received in payload. Choices available: - ``0`` Entry Editor - ``15`` Custom Import - ``20`` Public API ``provider_post_id`` String External Post ID -- Optional ``order_by`` String Changes the order of posts, defaults to ``recency`` Choices available: - ``last_update`` to start from newest ``updated_ts`` - ``oldness`` to start from oldest ``created_ts`` - ``recency`` to start from newest ``created_ts`` - ``popularity`` to order by page views in last x days. x is defined in ``order_by_period_in_days`` parameter. x defaults to 7 ``include_sections`` String Section IDs to include, multiple values can be sent with a comma-separated string -- Optional ``exclude_sections`` String Section IDs to exclude, multiple values can be sent with a comma-separated string -- Optional ``require_sections`` String Selects posts that have all these sections selected, multiple values can be sent with a comma-separated string -- Optional ``phrase`` String Filter posts by phrase -- Optional ``date_from`` Integer Date to start filtering from -- Optional ``date_to`` Integer Date to end filtering to -- Optional ``type`` String Post type -- Optional, ``order_by_period_in_days`` String Number of days to use in ``popularity``, defaults to 7 -- Optional ``exclude_private`` Boolean Excludes private posts -- Optional ``include_tags`` String Tags to include, multiple values can be sent with a comma-separated string -- Optional ``include_fields`` String Fields to include in response, multiple values can be sent with a comma-separated string -- Optional ``exclude_fields`` String Fields to exclude in response, multiple values can be sent with a comma-separated string -- Optional =========================== ========= ============================================================================================================================== Response ******** An array of objects is returned with each object having the same structure as the response returned in :ref:`creating-posts`. List frontpage posts -------------------- Fetch all frontpage posts in editorial order. .. code:: GET /api/1.3/posts/frontpage Parameters ********** ====================== ======= ========================================================================= Name Type Description ====================== ======= ========================================================================= ``offset`` Integer Offset -- Optional ``limit`` Integer Limit -- Optional, defaults to 10, maximum value is 100 ====================== ======= ========================================================================= Response ******** An array of objects is returned with each object having the same structure as the response returned in :ref:`creating-posts`. List posts by section --------------------- Fetch all posts by section in editorial order. .. code:: GET /api/1.3/posts/section Parameters ********** ====================== ======= ========================================================================= Name Type Description ====================== ======= ========================================================================= ``section_name`` String Section name -- Required ``offset`` Integer Offset -- Optional ``limit`` Integer Limit -- Optional, defaults to 10, maximum value is 100 ====================== ======= ========================================================================= Response ******** An array of objects is returned with each object having the same structure as the response returned in :ref:`creating-posts`. List posts by tag ----------------- Fetch all posts by tag. All returned posts will be ordered by date with the most recently published appearing first. .. code:: GET /api/1.3/posts/tag Parameters ********** ====================== ======= ========================================================================= Name Type Description ====================== ======= ========================================================================= ``tag`` String Tag -- Required ``offset`` Integer Offset -- Optional ``limit`` Integer Limit -- Optional, defaults to 10, maximum value is 100 ====================== ======= ========================================================================= Response ******** An array of objects is returned with each object having the same structure as the response returned in :ref:`creating-posts`. List posts by search phrase --------------------------- Fetch all posts filtered by search phrase. All returned posts will be ordered by date with the most recently published appearing first. .. code:: GET /api/1.3/posts/search Parameters ********** ====================== ======= ========================================================================= Name Type Description ====================== ======= ========================================================================= ``phrase`` String Search phrase -- Required ``offset`` Integer Offset -- Optional ``limit`` Integer Limit -- Optional, defaults to 10, maximum value is 100 ====================== ======= ========================================================================= Response ******** An array of objects is returned with each object having the same structure as the response returned in :ref:`creating-posts`. List posts by basename ---------------------- Fetch all posts by basename. All returned posts will be ordered by date with the most recently published appearing first. .. code:: GET /api/1.3/posts/basename .. important:: Unlike all other endpoints that list posts, this endpoint will return articles in draft status too. Parameters ********** ====================== ======= =========================================================================== Name Type Description ====================== ======= =========================================================================== ``basename`` String Basename -- Required ``removed`` Integer Removed posts -- Optional, removed articles will be listed only if received ====================== ======= =========================================================================== Response ******** An array of objects is returned with each object having the same structure as the response returned in :ref:`creating-posts`. List posts sorted by page views ------------------------------- Fetch published posts sorted by page views. .. code:: GET /api/1.3/posts/page_views Parameters ********** ====================== ======= ========================================================================= Name Type Description ====================== ======= ========================================================================= ``period_in_hours`` Integer Period of time in hours -- Optional, defaults to 24 ``offset`` Integer Offset -- Optional ``limit`` Integer Limit -- Optional, defaults to 10, maximum value is 100 ====================== ======= ========================================================================= Response ******** An array of objects is returned with each object having the same structure as the response returned in :ref:`creating-posts`.