Wagtail API Usage Guide ======================= Listing views ------------- Performing a ``GET`` request against one of the endpoints will get you a listing of objects in that endpoint. The response will look something like this: .. code-block:: text GET /api/v1/endpoint_name/ HTTP 200 OK Content-Type: application/json { "meta": { "total_count": "total number of results" }, "endpoint_name": [ { "id": 1, "meta": { "type": "app_name.ModelName", "detail_url": "http://api.example.com/api/v1/endpoint_name/1/" }, "field": "value" }, { "id": 2, "meta": { "type": "app_name.ModelName", "detail_url": "http://api.example.com/api/v1/endpoint_name/2/" }, "field": "different value" } ] } This is the basic structure of all of the listing views. They all have a ``meta`` section with a ``total_count`` variable and a listing of things. Detail views ------------ All of the endpoints also contain a "detail" view which returns information on an individual object. This view is always accessed by appending the id of the object to the URL. The ``pages`` endpoint ---------------------- This endpoint includes all live pages in your site that have not been put in a private section. The listing view (``/api/v1/pages/``) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This is what a typical response from a ``GET`` request to this listing would look like: .. code-block:: text GET /api/v1/pages/ HTTP 200 OK Content-Type: application/json { "meta": { "total_count": 2 }, "pages": [ { "id": 2, "meta": { "type": "demo.HomePage", "detail_url": "http://api.example.com/api/v1/pages/2/" }, "title": "Homepage" }, { "id": 3, "meta": { "type": "demo.BlogIndexPage", "detail_url": "http://api.example.com/api/v1/pages/3/" }, "title": "Blog" } ] } Each page object contains the ``id``, a ``meta`` section and the fields with their values. ``meta`` ^^^^^^^^ This section is used to hold "metadata" fields which aren't fields in the database. Wagtail API adds two by default: - ``type`` - The app label/model name of the object - ``detail_url`` - A URL linking to the detail view for this object Selecting a page type ^^^^^^^^^^^^^^^^^^^^^ Most Wagtail sites are made up of multiple different types of page that each have their own specific fields. In order to view/filter/order on fields specific to one page type, you must select that page type using the ``type`` query parameter. The ``type`` query parameter must be set to the Pages model name in the format: ``app_label.ModelName``. .. code-block:: text GET /api/v1/pages/?type=demo.BlogPage HTTP 200 OK Content-Type: application/json { "meta": { "total_count": 3 }, "pages": [ { "id": 4, "meta": { "type": "demo.BlogPage", "detail_url": "http://api.example.com/api/v1/pages/4/" }, "title": "My blog 1" }, { "id": 5, "meta": { "type": "demo.BlogPage", "detail_url": "http://api.example.com/api/v1/pages/5/" }, "title": "My blog 2" }, { "id": 6, "meta": { "type": "demo.BlogPage", "detail_url": "http://api.example.com/api/v1/pages/6/" }, "title": "My blog 3" } ] } Specifying a list of fields to return ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ As you can see, we still only get the ``title`` field, even though we have selected a type. That's because listing pages require you to explicitly tell it what extra fields you would like to see. You can do this with the ``fields`` query parameter. Just set ``fields`` to a command-separated list of field names that you would like to use. .. code-block:: text GET /api/v1/pages/?type=demo.BlogPage&fields=title,date_posted,feed_image HTTP 200 OK Content-Type: application/json { "meta": { "total_count": 3 }, "pages": [ { "id": 4, "meta": { "type": "demo.BlogPage", "detail_url": "http://api.example.com/api/v1/pages/4/" }, "title": "My blog 1", "date_posted": "2015-01-23", "feed_image": { "id": 1, "meta": { "type": "wagtailimages.Image", "detail_url": "http://api.example.com/api/v1/images/1/" } } }, { "id": 5, "meta": { "type": "demo.BlogPage", "detail_url": "http://api.example.com/api/v1/pages/5/" }, "title": "My blog 2", "date_posted": "2015-01-24", "feed_image": { "id": 2, "meta": { "type": "wagtailimages.Image", "detail_url": "http://api.example.com/api/v1/images/2/" } } }, { "id": 6, "meta": { "type": "demo.BlogPage", "detail_url": "http://api.example.com/api/v1/pages/6/" }, "title": "My blog 3", "date_posted": "2015-01-25", "feed_image": { "id": 3, "meta": { "type": "wagtailimages.Image", "detail_url": "http://api.example.com/api/v1/images/3/" } } } ] } We now have enough information to make a basic blog listing with a feed image and date that the blog was posted. Filtering on fields ^^^^^^^^^^^^^^^^^^^ Exact matches on field values can be done by using a query parameter with the same name as the field. Any pages with the field that exactly matches the value of this parameter will be returned. .. code-block:: text GET /api/v1/pages/?type=demo.BlogPage&fields=title,date_posted&date_posted=2015-01-24 HTTP 200 OK Content-Type: application/json { "meta": { "total_count": 1 }, "pages": [ { "id": 5, "meta": { "type": "demo.BlogPage", "detail_url": "http://api.example.com/api/v1/pages/5/" }, "title": "My blog 2", "date_posted": "2015-01-24", } ] } Filtering by section of the tree ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ It is also possible to filter the listing to only include pages with a particular parent or ancestor. This is useful if you have multiple blogs on your site and only want to view the contents of one of them. **child_of** Filters the listing to only include direct children of the specified page. For example, to get all the pages that are direct children of page 7. .. code-block:: text GET /api/v1/pages/?child_of=7 HTTP 200 OK Content-Type: application/json { "meta": { "total_count": 1 }, "pages": [ { "id": 4, "meta": { "type": "demo.BlogPage", "detail_url": "http://api.example.com/api/v1/pages/4/" }, "title": "Other blog 1" } ] } **descendant_of** Filters the listing to only include descendants of the specified page. For example, to get all pages underneath the homepage: .. code-block:: text GET /api/v1/pages/?descendant_of=2 HTTP 200 OK Content-Type: application/json { "meta": { "total_count": 1 }, "pages": [ { "id": 3, "meta": { "type": "demo.BlogIndexPage", "detail_url": "http://api.example.com/api/v1/pages/3/" }, "title": "Blog" }, { "id": 4, "meta": { "type": "demo.BlogPage", "detail_url": "http://api.example.com/api/v1/pages/4/" }, "title": "My blog 1", }, { "id": 5, "meta": { "type": "demo.BlogPage", "detail_url": "http://api.example.com/api/v1/pages/5/" }, "title": "My blog 2", }, { "id": 6, "meta": { "type": "demo.BlogPage", "detail_url": "http://api.example.com/api/v1/pages/6/" }, "title": "My blog 3", } ] } Ordering ^^^^^^^^ Like filtering, it is also possible to order on database fields. The endpoint accepts a query parameter called ``order`` which should be set to the field name to order by. Field names can be prefixed with a ``-`` to reverse the ordering. It is also possible to order randomly by setting this parameter to ``random``. .. code-block:: text GET /api/v1/pages/?type=demo.BlogPage&fields=title,date_posted,feed_image&order=-date_posted HTTP 200 OK Content-Type: application/json { "meta": { "total_count": 3 }, "pages": [ { "id": 6, "meta": { "type": "demo.BlogPage", "detail_url": "http://api.example.com/api/v1/pages/6/" }, "title": "My blog 3", "date_posted": "2015-01-25", "feed_image": { "id": 3, "meta": { "type": "wagtailimages.Image", "detail_url": "http://api.example.com/api/v1/images/3/" } } }, { "id": 5, "meta": { "type": "demo.BlogPage", "detail_url": "http://api.example.com/api/v1/pages/5/" }, "title": "My blog 2", "date_posted": "2015-01-24", "feed_image": { "id": 2, "meta": { "type": "wagtailimages.Image", "detail_url": "http://api.example.com/api/v1/images/2/" } } }, { "id": 4, "meta": { "type": "demo.BlogPage", "detail_url": "http://api.example.com/api/v1/pages/4/" }, "title": "My blog 1", "date_posted": "2015-01-23", "feed_image": { "id": 1, "meta": { "type": "wagtailimages.Image", "detail_url": "http://api.example.com/api/v1/images/1/" } } } ] } Pagination ^^^^^^^^^^ Pagination is done using two query parameters called ``limit`` and ``offset``. ``limit`` sets the number of results to return and ``offset`` is the index of the first result to return. The default and maximum value for ``limit`` is ``20``. The maximum value can be changed using the ``WAGTAILAPI_LIMIT_MAX`` setting. .. code-block:: text GET /api/v1/pages/?limit=1&offset=1 HTTP 200 OK Content-Type: application/json { "meta": { "total_count": 2 }, "pages": [ { "id": 3, "meta": { "type": "demo.BlogIndexPage", "detail_url": "http://api.example.com/api/v1/pages/3/" }, "title": "Blog" } ] } Pagination will not change the ``total_count`` value in the meta. Searching ^^^^^^^^^ To perform a full-text search, set the ``search`` parameter to the query string you would like to search on. .. code-block:: text GET /api/v1/pages/?search=Blog HTTP 200 OK Content-Type: application/json { "meta": { "total_count": 3 }, "pages": [ { "id": 3, "meta": { "type": "demo.BlogIndexPage", "detail_url": "http://api.example.com/api/v1/pages/3/" }, "title": "Blog" }, { "id": 4, "meta": { "type": "demo.BlogPage", "detail_url": "http://api.example.com/api/v1/pages/4/" }, "title": "My blog 1", }, { "id": 5, "meta": { "type": "demo.BlogPage", "detail_url": "http://api.example.com/api/v1/pages/5/" }, "title": "My blog 2", }, { "id": 6, "meta": { "type": "demo.BlogPage", "detail_url": "http://api.example.com/api/v1/pages/6/" }, "title": "My blog 3", } ] } The results are ordered by relevance. It is not possible to use the ``order`` parameter with a search query. If your Wagtail site is using Elasticsearch, you do not need to select a type to access specific fields. This will search anything that's defined in the models' ``search_fields``. The detail view (``/api/v1/pages/{id}/``) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This view gives you access to all of the details for a particular page. .. code-block:: text GET /api/v1/pages/6/ HTTP 200 OK Content-Type: application/json { "id": 6, "meta": { "type": "demo.BlogPage", "detail_url": "http://api.example.com/api/v1/pages/6/" }, "parent": { "id": 3, "meta": { "type": "demo.BlogIndexPage", "detail_url": "http://api.example.com/api/v1/pages/3/" } }, "title": "My blog 3", "date_posted": "2015-01-25", "feed_image": { "id": 3, "meta": { "type": "wagtailimages.Image", "detail_url": "http://api.example.com/api/v1/images/3/" } }, "related_links": [ { "title": "Other blog page", "page": { "id": 5, "meta": { "type": "demo.BlogPage", "detail_url": "http://api.example.com/api/v1/pages/5/" } } } ] } The format is the same as that which is returned inside the listing view, with two additions: - All of the available fields are added to the detail page by default - A ``parent`` field has been included that contains information about the parent page The ``images`` endpoint ----------------------- This endpoint gives access to all uploaded images. This will use the custom image model if one was specified. Otherwise, it falls back to ``wagtailimages.Image``. The listing view (``/api/v1/images/``) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This is what a typical response from a ``GET`` request to this listing would look like: .. code-block:: text GET /api/v1/images/ HTTP 200 OK Content-Type: application/json { "meta": { "total_count": 3 }, "images": [ { "id": 4, "meta": { "type": "wagtailimages.Image", "detail_url": "http://api.example.com/api/v1/images/4/" }, "title": "Wagtail by Mark Harkin" }, { "id": 5, "meta": { "type": "wagtailimages.Image", "detail_url": "http://api.example.com/api/v1/images/5/" }, "title": "James Joyce" }, { "id": 6, "meta": { "type": "wagtailimages.Image", "detail_url": "http://api.example.com/api/v1/images/6/" }, "title": "David Mitchell" } ] } Each image object contains the ``id`` and ``title`` of the image. Getting ``width``, ``height`` and other fields ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Like the pages endpoint, the images endpoint supports the ``fields`` query parameter. By default, this will allow you to add the ``width`` and ``height`` fields to your results. If your Wagtail site uses a custom image model, it is possible to have more. .. code-block:: text GET /api/v1/images/?fields=title,width,height HTTP 200 OK Content-Type: application/json { "meta": { "total_count": 3 }, "images": [ { "id": 4, "meta": { "type": "wagtailimages.Image", "detail_url": "http://api.example.com/api/v1/images/4/" }, "title": "Wagtail by Mark Harkin", "width": 640, "height": 427 }, { "id": 5, "meta": { "type": "wagtailimages.Image", "detail_url": "http://api.example.com/api/v1/images/5/" }, "title": "James Joyce", "width": 500, "height": 392 }, { "id": 6, "meta": { "type": "wagtailimages.Image", "detail_url": "http://api.example.com/api/v1/images/6/" }, "title": "David Mitchell", "width": 360, "height": 282 } ] } Filtering on fields ^^^^^^^^^^^^^^^^^^^ Exact matches on field values can be done by using a query parameter with the same name as the field. Any images with the field that exactly matches the value of this parameter will be returned. .. code-block:: text GET /api/v1/pages/?title=James Joyce HTTP 200 OK Content-Type: application/json { "meta": { "total_count": 3 }, "images": [ { "id": 5, "meta": { "type": "wagtailimages.Image", "detail_url": "http://api.example.com/api/v1/images/5/" }, "title": "James Joyce" } ] } Ordering ^^^^^^^^ The images endpoint also accepts the ``order`` parameter which should be set to a field name to order by. Field names can be prefixed with a ``-`` to reverse the ordering. It is also possible to order randomly by setting this parameter to ``random``. .. code-block:: text GET /api/v1/images/?fields=title,width&order=width HTTP 200 OK Content-Type: application/json { "meta": { "total_count": 3 }, "images": [ { "id": 6, "meta": { "type": "wagtailimages.Image", "detail_url": "http://api.example.com/api/v1/images/6/" }, "title": "David Mitchell", "width": 360 }, { "id": 5, "meta": { "type": "wagtailimages.Image", "detail_url": "http://api.example.com/api/v1/images/5/" }, "title": "James Joyce", "width": 500 }, { "id": 4, "meta": { "type": "wagtailimages.Image", "detail_url": "http://api.example.com/api/v1/images/4/" }, "title": "Wagtail by Mark Harkin", "width": 640 } ] } Pagination ^^^^^^^^^^ Pagination is done using two query parameters called ``limit`` and ``offset``. ``limit`` sets the number of results to return and ``offset`` is the index of the first result to return. The default and maximum value for ``limit`` is ``20``. The maximum value can be changed using the ``WAGTAILAPI_LIMIT_MAX`` setting. .. code-block:: text GET /api/v1/images/?limit=1&offset=1 HTTP 200 OK Content-Type: application/json { "meta": { "total_count": 3 }, "images": [ { "id": 5, "meta": { "type": "wagtailimages.Image", "detail_url": "http://api.example.com/api/v1/images/5/" }, "title": "James Joyce", "width": 500, "height": 392 } ] } Pagination will not change the ``total_count`` value in the meta. Searching ^^^^^^^^^ To perform a full-text search, set the ``search`` parameter to the query string you would like to search on. .. code-block:: text GET /api/v1/images/?search=James HTTP 200 OK Content-Type: application/json { "meta": { "total_count": 1 }, "pages": [ { "id": 5, "meta": { "type": "wagtailimages.Image", "detail_url": "http://api.example.com/api/v1/images/5/" }, "title": "James Joyce", "width": 500, "height": 392 } ] } Like the pages endpoint, the results are ordered by relevance and it is not possible to use the ``order`` parameter with a search query. The detail view (``/api/v1/images/{id}/``) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This view gives you access to all of the details for a particular image. .. code-block:: text GET /api/v1/images/5/ HTTP 200 OK Content-Type: application/json { "id": 5, "meta": { "type": "wagtailimages.Image", "detail_url": "http://api.example.com/api/v1/images/5/" }, "title": "James Joyce", "width": 500, "height": 392 } The ``documents`` endpoint -------------------------- This endpoint gives access to all uploaded documents. The listing view (``/api/v1/documents/``) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The documents listing supports the same features as the images listing (documented above) but works with Documents instead. The detail view (``/api/v1/documents/{id}/``) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This view gives you access to all of the details for a particular document. .. code-block:: text GET /api/v1/documents/1/ HTTP 200 OK Content-Type: application/json { "id": 1, "meta": { "type": "wagtaildocs.Document", "detail_url": "http://api.example.com/api/v1/documents/1/", "download_url": "http://api.example.com/documents/1/usage.md" }, "title": "Wagtail API usage" }