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:
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:
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``.
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:: json
GET /api/v1/pages/?type=demo.BlogPage&fields=title,date_posted,feed_image
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:: json
GET /api/v1/pages/?type=demo.BlogPage&fields=title,date_posted&date_posted=2015-01-24
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.
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:: json
GET /api/v1/pages/?type=demo.BlogPage&fields=title,date_posted,feed_image&order=-date_posted
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.
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.
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:
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.
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.
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:: json
GET /api/v1/images/?fields=title,width&order=width
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.
