:orphan:

.. role:: json(code)
   :language: json

.. role:: python(code)
   :language: python


Routing API
===========

.. contents:: :depth: 3


Endpoints
#########

Search Records
--------------

.. code::

    GET /core/v1/routing/records?limit=50[&offset=20[&__json__=<See JSON below>]]

.. code:: json

    {
      "filters": [
        <record filter>,
        <record filter>,
        ...
      ]
    }

200 OK
******

.. code:: json

    {
      "records": [
        {
          "path": "path/to/external/redirect",
          "resource": {
            "external-redirect": {
              "href": "https://www.example.org/",
              "code": 302
            }
          }
        },
        {
          "path": "static-pages/some-layout-page",
          "resource": {
            "layout-page": {
              "id": "66ac95356999be9ddafa45cc"
            }
          }
        },
        {
          "path": "path/to/any/other/resource",
          "resource": <resource>
        },
        ...
      ],
      "records_count": 345
    }

Hints:

- <resource> (see: `Resources`_)
- <record filter> (see: `Record Filters`_)


Search Redirects
----------------

.. code::

    GET /core/v1/routing/redirects/records?limit=50[&offset=20[&__json__=<See JSON below>]]

.. code:: json

    {
      "filters": [
        <record filter>,
        <record filter>,
        ...
      ]
    }

200 OK
******

.. code:: json

    {
      "records": [
        {
          "path": "path/to/internal/redirect",
          "resource": {
            "internal-redirect": {
              "path": "path/to/any/other/resource",
              "code": 301
            }
          }
        },
        {
          "path": "path/to/external/redirect",
          "resource": {
            "override": {
              "delegate": {
                "external-redirect": {
                  "href": "https://www.example.org/",
                  "code": 302
                }
              },
              "original": <resource>
            }
          }
        },
        ...
      ],
      "records_count": 234
    }

Hints:

- <resource> (see: `Resources`_)
- <record filter> (see: `Record Filters`_)


Remove Records
--------------

.. code::

    PUT /core/v1/routing/records?__json__=<See JSON below>

.. code:: json

    {
      "filters": [
        <record filter>,
        <record filter>,
        ...
      ],
      "commands": [
        {"remove": {}}
      ]
    }

200 OK
******

.. code:: json

    {
      "records_count": 345
    }

Hints:

- <resource> (see: `Resources`_)
- <record filter> (see: `Record Filters`_)


Remove Redirects
----------------

.. code::

    GET /core/v1/routing/redirects/records?__json__=<See JSON below>

.. code:: json

    {
      "filters": [
        <record filter>,
        <record filter>,
        ...
      ],
      "commands": [
        {"remove": {}}
      ]
    }

200 OK
******

.. code:: json

    {
      "records_count": 234
    }

Hints:

- <resource> (see: `Resources`_)
- <record filter> (see: `Record Filters`_)


Create Redirect
---------------

.. code::

    POST /core/v1/routing/redirects/records

.. code:: json

    {
      "path": "path/to/new/redirect",
      "resource": {
        "internal-redirect": {
          "path": "path/to/any/other/resource",
          "code": 305
        }
      }
    }

200 OK
******

.. code:: json

    {
      "record": {
        "path": "path/to/new/redirect",
        "resource": {
          "internal-redirect": {
            "path": "path/to/any/other/resource",
            "code": 305
          }
        }
      }
    }


Export Redirects (async/await)
------------------------------

Async
*****

.. code::

    POST /core/v1/routing/records/export?__json__=<See JSON below>

.. code:: json

    {
      "filters": [
        <record filter>,
        <record filter>,
        ...
      ],
      "format": {
        "csv": {
          "fields": []
        }
      },
      "filename": "redirects-export"  // optional
    }

200 OK
******

.. code:: json

    {
      "task": {
        "id": "38e9eea7-fc5b-4373-90f0-cb2d59109113",
        "is_ready": false,
        "progress": null,
        "response": null,
        "exception": null
    }


Await
*****

.. code::

    GET /core/v1/routing/records/export?task_id=38e9eea7-fc5b-4373-90f0-cb2d59109113


200 OK
******

.. code:: json

    {
      "task": {
        "id": "38e9eea7-fc5b-4373-90f0-cb2d59109113",
        "is_ready": true,
        "progress": null,
        "response": {
          "download_href": "https://s3.amazonaws.com/site-assets.rbl.ms/sites/17243519/exports/routing/redirects-export.csv"
        },
        "exception": null
    }

Hints:

- <record filter> (see: `Record Filters`_)


Resources
#########

External Redirect
-----------------

Represents an external redirect.

.. code:: json

    {
      "external-redirect": {
        "href": "https://www.example.org/",
        "code": 302
      }
    }

Internal Redirect
-----------------

Represents an internal redirect.

.. code:: json

    {
      "internal-redirect": {
        "path": "path/to/any/other/resource",
        "code": 301
      }
    }


Layout Page
-----------

Represents a custom static page (see: :ref:`pages`).

.. code:: json

    {
      "layout-page": {
        "id": "66ac95356999be9ddafa45cc"
      }
    }


Override
--------

Represents any resource that is overridden by another resource.
For example, a so-called "link-out" -- an article page that is overridden by an external redirect.

.. code:: json

    {
      "override": {
        "delegate": {
          "external-redirect": {
            "href": "https://www.example.org/",
            "code": 302
          }
        },
        "original": <resource>
      }
    }


Record Filters
###############

- `{"path": {"prefix": "path/to"}}` -- filter by path prefix
  - TODO: Consider `{"syntax": {"prefix": {}}, "phrase": "path/to"}`, see: :ref:`sections-filters-phrase-syntaxes`
- `{"paths": ["path/to/record-1", "path/to/record-2"]}` -- filter by exact paths
- `{"resource-types": ["<resource type>", "<resource type>"]}` -- filter by resource types

Hints:

- <resource type> (see: `Resources`_)