Docs for Delivery API V2 incl. new property expansion and limiting

13/umbraco-cms/SUMMARY.md

@@ -20,6 +20,13 @@
   * [External login providers](reference/security/external-login-providers.md)
   * [Two-factor Authentication](reference/security/two-factor-authentication.md)
 
+* [Content Delivery API](reference/content-delivery-api/README.md)
+    * [Custom property editors support](reference/content-delivery-api/custom-property-editors-support.md)
+    * [Extension API for querying](reference/content-delivery-api/extension-api-for-querying.md)
+    * [Media Delivery API](reference/content-delivery-api/media-delivery-api.md)
+    * [Protected content in the Delivery API](reference/content-delivery-api/protected-content-in-the-delivery-api.md)
+    * [Property expansion and limiting](reference/content-delivery-api/property-expansion-and-limiting.md)
+
 ## Tutorials
 
 

13/umbraco-cms/reference/content-delivery-api/custom-property-editors-support.md

@@ -8,7 +8,7 @@ description: >-
 
 Out of the box, the Delivery API supports custom property editors, ensuring they are rendered alongside the built-in ones in Umbraco. However, if the output generated by your property editor isn't optimal for a headless context, you have the ability to customize the API response. This customization won't impact the Razor rendering, allowing you to tailor the Content Delivery API response according to your specific requirements.
 
-In this article, we'll look into how you can work with the `IDeliveryApiPropertyValueConverter` interface and implement custom [output expansion](./#output-expansion) for your custom property editors.
+In this article, we'll look into how you can work with the `IDeliveryApiPropertyValueConverter` interface and implement custom [property expansion](./#property-expansion) for your custom property editors.
 
 ## Prerequisite
 
@@ -59,6 +59,9 @@ public class MyCustomPickerValueConverter : PropertyValueConverterBase, IDeliver
     public PropertyCacheLevel GetDeliveryApiPropertyCacheLevel(IPublishedPropertyType propertyType)
         => PropertyCacheLevel.Elements;
 
+    public PropertyCacheLevel GetDeliveryApiPropertyCacheLevelForExpansion(IPublishedPropertyType propertyType)
+        => PropertyCacheLevel.Snapshot;
+
     public Type GetDeliveryApiPropertyValueType(IPublishedPropertyType propertyType)
         => typeof(DeliveryApiCustomPicker);
 
@@ -114,6 +117,7 @@ public class DeliveryApiItemDetails
 The Implementation of the `IDeliveryApiPropertyValueConverter` interface can be found in the following methods:
 
 * `GetDeliveryApiPropertyCacheLevel()`: This method specifies the cache level used for our property representation in the Delivery API response.
+* `GetDeliveryApiPropertyCacheLevelForExpansion()`: This method specifies the cache level used for our property representation in the Delivery API response when [property expansion](./property-expansion-and-limiting) is applied.
 * `GetDeliveryApiPropertyValueType()`: This method defines the value type of the custom property output for the Delivery API response.
 * `ConvertIntermediateToDeliveryApiObject()`: This method converts the value from the property editor to the desired custom object in a headless context.
 
@@ -124,7 +128,7 @@ The following example request shows how our custom implementation is reflected i
 **Request**
 
 ```http
-GET /umbraco/delivery/api/v1/content/item/blog
+GET /umbraco/delivery/api/v2/content/item/blog
 ```
 
 **Response**
@@ -153,11 +157,11 @@ GET /umbraco/delivery/api/v1/content/item/blog
 }
 ```
 
-## Output expansion support
+## Property expansion support
 
-Output expansion allows us to conditionally add another level of detail to the Delivery API output. Usually, these additional details are "expensive" to retrieve (for example, requiring database access to populate). By applying output expansion, we provide the option for the caller of the API to opt-in explicitly to this "expensive" operation. From the caller's perspective, the alternative might be an even more expensive additional round-trip to the server.
+Property expansion allows us to conditionally add another level of detail to the Delivery API output. Usually, these additional details are "expensive" to retrieve (for example, requiring database access to populate). By applying property expansion, we provide the option for the caller of the API to opt-in explicitly to this "expensive" operation. From the caller's perspective, the alternative might be an even more expensive additional round-trip to the server.
 
-In our example, output expansion is implemented within `ConvertIntermediateToDeliveryApiObject()`. By considering the value of the `expanding` parameter, we can modify the `BuildDeliveryApiCustomPicker()` method as follows:
+In our example, property expansion is implemented within `ConvertIntermediateToDeliveryApiObject()`. By considering the value of the `expanding` parameter, we can modify the `BuildDeliveryApiCustomPicker()` method as follows:
 
 ```csharp
 private DeliveryApiCustomPicker? BuildDeliveryApiCustomPicker(object inter, bool expanding)
@@ -173,7 +177,7 @@ private DeliveryApiCustomPicker? BuildDeliveryApiCustomPicker(object inter, bool
         return null;
     }
 
-    // Output expansion support
+    // Property expansion support
     if (expanding == false)
     {
         return new DeliveryApiCustomPicker { Id = id };
@@ -194,12 +198,12 @@ private DeliveryApiCustomPicker? BuildDeliveryApiCustomPicker(object inter, bool
 
 If the `expanding` parameter is `false`, the method returns the same shallow representation of the referenced content item as before. Otherwise, we retrieve the corresponding `IPublishedContent` and construct our response object accordingly.
 
-To see the expanded output in the API response, we need to add the `expand` query parameter to our request. We can use either `?expand=all` to expand all properties or `?expand=property:pickedItem` to expand the specific `'pickedItem'` property.
+To see the expanded output in the API response, we need to add the `expand` query parameter to our request. We can use either `?expand=properties[$all]` to expand all properties or `?expand=properties[pickedItem]` to expand the specific `'pickedItem'` property.
 
 **Request**
 
 ```http
-GET /umbraco/delivery/api/v1/content/item/blog?expand=property:pickedItem
+GET /umbraco/delivery/api/v2/content/item/blog?expand=properties[pickedItem]
 ```
 
 **Response**

13/umbraco-cms/reference/content-delivery-api/extension-api-for-querying.md

@@ -6,7 +6,7 @@ description: >-
 
 # Extension API for querying
 
-The Delivery API allows you to retrieve multiple items by utilizing the `/umbraco/delivery/api/v1/content` endpoint. With the built-in query parameters, you have the flexibility to get any number of content nodes based on your needs. For a comprehensive list of supported query options, please refer to the [Endpoints](./#endpoints) section.
+The Delivery API allows you to retrieve multiple items by utilizing the `/umbraco/delivery/api/v2/content` endpoint. With the built-in query parameters, you have the flexibility to get any number of content nodes based on your needs. For a comprehensive list of supported query options, please refer to the [Endpoints](./#endpoints) section.
 
 For the query endpoint, we have created a new Examine index (_DeliveryApiContentIndex_) that facilitates fast retrieval of the desired content. This index ensures quick indexing and searching of data, with the possibility for future extensions.
 
@@ -17,7 +17,7 @@ In this article, we'll explore creating custom selecting, filtering, and sorting
 Let's take a look at an example of using the query endpoint with query parameters for `fetch`, `filter`, and `sort`. A request might look like this:
 
 ```http
-GET /umbraco/delivery/api/v1/content?fetch=xxx&filter=yyy&filter=zzz&sort=aaa&sort=bbb
+GET /umbraco/delivery/api/v2/content?fetch=xxx&filter=yyy&filter=zzz&sort=aaa&sort=bbb
 ```
 
 The placeholders in the example (`xxx`, `yyy`, etc.) represent the values that each query option evaluates in order to determine the suitable query handler.
@@ -114,7 +114,7 @@ Since our custom query option modifies the index structure, we will need to rebu
 **Request**
 
 ```http
-GET /umbraco/delivery/api/v1/content?fetch=featuredAuthors
+GET /umbraco/delivery/api/v2/content?fetch=featuredAuthors
 ```
 
 **Response**
@@ -139,7 +139,7 @@ This filter allows specifying the desired author(s) by their key (`Guid`) in an
 **Request**
 
 ```http
-GET /umbraco/delivery/api/v1/content?filter=author:7c630f15-8d93-4980-a0fc-027314dc827a,75380b4f-6d6e-47a1-9222-975cdfb2ac5f
+GET /umbraco/delivery/api/v2/content?filter=author:7c630f15-8d93-4980-a0fc-027314dc827a,75380b4f-6d6e-47a1-9222-975cdfb2ac5f
 ```
 
 The response will include the blog posts associated with the provided authors, enabling us to retrieve only the relevant results from the API.
@@ -317,7 +317,7 @@ In the following example request, we also apply the author filter to retrieve on
 **Request**
 
 ```http
-GET /umbraco/delivery/api/v1/content?filter=author:7c630f15-8d93-4980-a0fc-027314dc827a&sort=publishDate:asc
+GET /umbraco/delivery/api/v2/content?filter=author:7c630f15-8d93-4980-a0fc-027314dc827a&sort=publishDate:asc
 ```
 
 **Response**

13/umbraco-cms/reference/content-delivery-api/media-delivery-api.md

@@ -56,7 +56,7 @@ The Media Delivery API can either be queried for a specific media item or a page
 In the Media Delivery API, `id` parameters always refer to media item keys (`Guid`), not node ids (`integer`).
 {% endhint %}
 
-{% swagger method="get" path="/media/item/{id}" baseUrl="/umbraco/delivery/api/v1" summary="Gets a media item by id" %}
+{% swagger method="get" path="/media/item/{id}" baseUrl="/umbraco/delivery/api/v2" summary="Gets a media item by id" %}
 {% swagger-description %}
 Returns a single item.
 {% endswagger-description %}
@@ -73,6 +73,10 @@ Access token
 Which properties to expand in the response
 {% endswagger-parameter %}
 
+{% swagger-parameter in="query" name="fields" type="String" required="false" %}
+Which properties to include in the response (_by default all properties are included_)
+{% endswagger-parameter %}
+
 {% swagger-response status="200: OK" description="Media item" %}
 
 {% endswagger-response %}
@@ -86,13 +90,13 @@ Which properties to expand in the response
 {% endswagger-response %}
 {% endswagger %}
 
-{% swagger method="get" path="/media/item/{path}" baseUrl="/umbraco/delivery/api/v1" summary="Gets a media item by path" %}
+{% swagger method="get" path="/media/item/{path}" baseUrl="/umbraco/delivery/api/v2" summary="Gets a media item by path" %}
 {% swagger-description %}
 Returns a single item.
 {% endswagger-description %}
 
 {% swagger-parameter in="path" name="path" type="String" required="true" %}
-Path of the media item. The path is composed by the names of any ancestor folders and the name of the media item itself, separated by 
+Path of the media item. The path is composed by the names of any ancestor folders and the name of the media item itself, separated by
 
 `/`
 
@@ -107,6 +111,10 @@ Access token
 Which properties to expand in the response
 {% endswagger-parameter %}
 
+{% swagger-parameter in="query" name="fields" type="String" required="false" %}
+Which properties to include in the response (_by default all properties are included_)
+{% endswagger-parameter %}
+
 {% swagger-response status="200: OK" description="Media item" %}
 
 {% endswagger-response %}
@@ -120,7 +128,7 @@ Which properties to expand in the response
 {% endswagger-response %}
 {% endswagger %}
 
-{% swagger method="get" path="/media/item" baseUrl="/umbraco/delivery/api/v1" summary="Gets media item(s) by id" %}
+{% swagger method="get" path="/media/items" baseUrl="/umbraco/delivery/api/v2" summary="Gets media item(s) by id" %}
 {% swagger-description %}
 Returns single or multiple items by id.
 {% endswagger-description %}
@@ -137,6 +145,10 @@ Access token
 Which properties to expand in the response
 {% endswagger-parameter %}
 
+{% swagger-parameter in="query" name="fields" type="String" required="false" %}
+Which properties to include in the response (_by default all properties are included_)
+{% endswagger-parameter %}
+
 {% swagger-response status="200: OK" description="List of media items" %}
 
 {% endswagger-response %}
@@ -146,7 +158,7 @@ Which properties to expand in the response
 {% endswagger-response %}
 {% endswagger %}
 
-{% swagger method="get" path="/media" baseUrl="/umbraco/delivery/api/v1" summary="Gets media item(s) from a query" %}
+{% swagger method="get" path="/media" baseUrl="/umbraco/delivery/api/v2" summary="Gets media item(s) from a query" %}
 {% swagger-description %}
 Returns single or multiple items.
 {% endswagger-description %}
@@ -181,6 +193,10 @@ Access token
 Which properties to expand in the response
 {% endswagger-parameter %}
 
+{% swagger-parameter in="query" name="fields" type="String" required="false" %}
+Which properties to include in the response (_by default all properties are included_)
+{% endswagger-parameter %}
+
 {% swagger-response status="200: OK" description="Paginated list of media items" %}
 
 {% endswagger-response %}
@@ -195,31 +211,31 @@ Which properties to expand in the response
 Fetch a media item by its ID:
 
 ```http
-GET /umbraco/delivery/api/v1/media/item/3fa85f64-5717-4562-b3fc-2c963f66afa6
+GET /umbraco/delivery/api/v2/media/item/3fa85f64-5717-4562-b3fc-2c963f66afa6
 ```
 
 Fetch a media item inside a folder structure by its full path, and expand its `author` property:
 
 ```http
-GET /umbraco/delivery/api/v1/media/item/root level folder/child folder/media item name/&expand=property:author
+GET /umbraco/delivery/api/v2/media/item/root level folder/child folder/media item name/&expand=property:author
 ```
 
 Fetch two media items by their ids:
 
 ```http
-GET /umbraco/delivery/api/v1/media/item?id=11178b4f-f8e2-4686-9697-6d990851a081&id=7cd00706-de93-4db8-8fc2-4b20e8419c30
+GET /umbraco/delivery/api/v2/media/item?id=11178b4f-f8e2-4686-9697-6d990851a081&id=7cd00706-de93-4db8-8fc2-4b20e8419c30
 ```
 
 Fetch the first 10 media items of type `Image` at root level. Return the found items sorted by name ascending:
 
 ```http
-GET /umbraco/delivery/api/v1/media?fetch=children:/&filter=mediaType:Image&sort=name:asc&skip=0&take=10
+GET /umbraco/delivery/api/v2/media?fetch=children:/&filter=mediaType:Image&sort=name:asc&skip=0&take=10
 ```
 
 Fetch the first 5 media items inside a folder structure. Return only items of type `Image` whose item names contain "size".
 
 ```http
-GET /umbraco/delivery/api/v1/media?fetch=children:/root level folder/child folder/&filter=mediaType:Image&filter=name:size&skip=0&take=5
+GET /umbraco/delivery/api/v2/media?fetch=children:/root level folder/child folder/&filter=mediaType:Image&filter=name:size&skip=0&take=5
 ```
 
 ## Media item JSON structure