Skip to content

Commit 6387b95

Browse files
alina-tincasalina-tincas
authored
Merge pull request #5945 from umbraco/re-adding-v13-missing-commits
re-added lost commit changes from PR #5626
2 parents 63e5cc5 + 10636e2 commit 6387b95

File tree

2 files changed

+65
-126
lines changed

2 files changed

+65
-126
lines changed

‎13/umbraco-cms/reference/content-delivery-api/README.md‎

Lines changed: 64 additions & 125 deletions
Original file line numberDiff line numberDiff line change
@@ -186,130 +186,32 @@ This means that the content item resides under the `docs-portal` root node and c
186186
The start item can also be helpful through the `Start-Item` request header when obtaining content from the Delivery API. Supplying a root node `id` or `path` as the header value, allows you to specify which is the starting point for the requested content operation:
187187

188188
```http
189-
GET /umbraco/delivery/api/v1/content/item/articles/2023/getting-started
189+
GET /umbraco/delivery/api/v2/content/item/articles/2023/getting-started
190190
Start-Item: docs-portal
191191
```
192192

193193
</details>
194194

195195
<details>
196196

197-
<summary>Output expansion</summary>
197+
<summary>Property expansion and limiting</summary>
198198

199-
**Output expansion** allows you to retrieve additional data about related content or media in the API output for a given content item.
199+
Property expansion and limiting allows you to:
200200

201-
By default, a content property that allows picking a different content item (like a content picker property) outputs a shallow representation of the item. That means, only the basic information about the picked item, without the item properties. However, with output expansion, it is possible to include the properties of the picked item in the API output. Similar shallow representation applies to media items, as well.
201+
- Include properties from related content or media in the API output for a given content item.
202+
- Limit the content properties in the API output.
202203

203-
{% hint style="info" %}
204-
Currently, output expansion allows you to retrieve one level of property data from the point of view of the requested content node. This means that you can expand the properties of the chosen content item, but not the properties of other related items within that item.
205-
{% endhint %}
206-
207-
This feature can be used when querying for both single and multiple content items by adding an `expand` parameter to the query. The value of this parameter can be either `"all"` to expand all properties of the requested content item or `"property:alias, alias, alias"` to expand specific ones.
208-
209-
The following JSON snippet demonstrates the default output of a content item (without expanding any properties).
204+
By default, a content property that allows picking a different content item (for example a content picker) outputs a "shallow" representation of the picked item. This means that the output only includes basic information about the picked item, without the item properties.
210205

211-
**Request**
212-
213-
```http
214-
GET /umbraco/delivery/api/v1/content/item/9bdac0e9-66d8-4bfd-bba1-e954ed9c780d
215-
```
216-
217-
**Response**
218-
219-
{% code title="Shallow output for " %}
220-
```json
221-
{
222-
"name": "My post",
223-
"createDate": "2023-05-11T00:05:31.878211",
224-
"updateDate": "2023-05-15T11:25:53.912058",
225-
"route": {...
226-
},
227-
"id": "9bdac0e9-66d8-4bfd-bba1-e954ed9c780d",
228-
"contentType": "blogpost1",
229-
"properties": {
230-
"title": "My post page",
231-
"blogPostNumber": 11,
232-
"bodyContent": "Congue, sollicitudin? Est fames maiores, sociis suspendisse et aliquet tristique excepturi, aliquam, nihil illum pretium penatibus exercitationem lacinia! Dolorem tempus convallis, nulla! Eius scelerisque voluptatum penatibus, dignissimos molestiae, soluta eum. Voluptatibus quod? Temporibus potenti voluptates dictumst? Cillum metus, nec asperiores? Impedit sit! Eum tellus cillum facilisis ullamco tempor? Sint nostrum luctus? Neque dictumst diam, minus? Itaque, minus, etiam dignissimos debitis occaecat aptent tempus! Praesent molestiae duis nihil recusandae, eius imperdiet aspernatur natus. Tempus mattis at architecto, augue, consequuntur ultricies eligendi, litora morbi ante nesciunt pretium laoreet quidem recusandae voluptates dapibus, iure sagittis donec ipsum mollit? Blanditiis! Laborum sit assumenda beatae.",
233-
"linkedItem": {
234-
"name": "Demo blog",
235-
"createDate": "2023-05-11T00:26:52.591927",
236-
"updateDate": "2023-05-16T12:43:41.339963",
237-
"route": {
238-
"path": "/demo-blog/",
239-
"startItem": {
240-
"id": "5d5ae914-9885-4ee0-a14b-0ab57f501a55",
241-
"path": "demo-blog"
242-
}
243-
},
244-
"id": "5d5ae914-9885-4ee0-a14b-0ab57f501a55",
245-
"contentType": "blog",
246-
"properties": {}
247-
}
248-
},
249-
"cultures": {}
250-
}
251-
```
252-
{% endcode %}
206+
If we apply property expansion to the content property, the properties of the picked item are included in the output. This functionality applies to media items and block editors, as well.
253207

254-
Below is an example of how an expanded representation might look for the `linkedItem` property that references another content item with properties `title` and `description`:
208+
Property expansion can be applied to expanded properties too, thus obtaining nested property expansion. As a consequence, the output grows in size, and this is where property limiting comes into the picture.
255209

256-
**Request**
210+
By default, all content properties (including expanded properties) are included in the output. Property limiting allows us to specify exactly which content properties to include in the output. This means we can tailor the output specifically to concrete use cases without over-fetching.
257211

258-
```http
259-
GET /umbraco/delivery/api/v1/content/item/9bdac0e9-66d8-4bfd-bba1-e954ed9c780d?expand=property:linkedItem
260-
```
212+
Property expansion and limiting can be used when querying for both single and multiple content or media items. You can expand properties by adding an `expand` parameter to the query and limit them by the `fields` query parameter.
261213

262-
**Response**
263-
264-
{% code title="Expanded output for " %}
265-
```json
266-
{
267-
"name": "My post",
268-
"createDate": "2023-05-11T00:05:31.878211",
269-
"updateDate": "2023-05-15T11:25:53.912058",
270-
"route": {
271-
"path": "/my-post/",
272-
"startItem": {
273-
"id": "5d5ae914-9885-4ee0-a14b-0ab57f501a55",
274-
"path": "demo-blog"
275-
}
276-
},
277-
"id": "9bdac0e9-66d8-4bfd-bba1-e954ed9c780d",
278-
"contentType": "blogpost1",
279-
"properties": {
280-
"title": "My post page",
281-
"blogPostNumber": 11,
282-
"bodyContent": "Congue, sollicitudin? Est fames maiores, sociis suspendisse et aliquet tristique excepturi, aliquam, nihil illum pretium penatibus exercitationem lacinia! Dolorem tempus convallis, nulla! Eius scelerisque voluptatum penatibus, dignissimos molestiae, soluta eum. Voluptatibus quod? Temporibus potenti voluptates dictumst? Cillum metus, nec asperiores? Impedit sit! Eum tellus cillum facilisis ullamco tempor? Sint nostrum luctus? Neque dictumst diam, minus? Itaque, minus, etiam dignissimos debitis occaecat aptent tempus! Praesent molestiae duis nihil recusandae, eius imperdiet aspernatur natus. Tempus mattis at architecto, augue, consequuntur ultricies eligendi, litora morbi ante nesciunt pretium laoreet quidem recusandae voluptates dapibus, iure sagittis donec ipsum mollit? Blanditiis! Laborum sit assumenda beatae.",
283-
"linkedItem": {
284-
"name": "Demo blog",
285-
"createDate": "2023-05-11T00:26:52.591927",
286-
"updateDate": "2023-05-16T12:43:41.339963",
287-
"route": {
288-
"path": "/demo-blog/",
289-
"startItem": {
290-
"id": "5d5ae914-9885-4ee0-a14b-0ab57f501a55",
291-
"path": "demo-blog"
292-
}
293-
},
294-
"id": "5d5ae914-9885-4ee0-a14b-0ab57f501a55",
295-
"contentType": "blog",
296-
"properties": {
297-
"title": "My demo blog",
298-
"description": "Nihil incididunt dolores adipisicing placeat quisque imperdiet interdum autem, dolorem fusce rhoncus sunt leo inventore dictumst quisque, voluptatem, magni justo nostrud deserunt! Natus ipsam commodi dignissimos, sodales ab.\n"
299-
}
300-
}
301-
},
302-
"cultures": {}
303-
}
304-
```
305-
{% endcode %}
306-
307-
The built-in property editors in Umbraco that allow for output expansion are:
308-
309-
* `Umbraco.ContentPicker`
310-
* `Umbraco.MediaPicker`
311-
* `Umbraco.MediaPicker3`
312-
* `Umbraco.MultiNodeTreePicker`
214+
Please refer to [this article](./property-expansion-and-limiting) for an in-depth explanation of this feature.
313215

314216
</details>
315217

@@ -320,7 +222,7 @@ The built-in property editors in Umbraco that allow for output expansion are:
320222
Similar to the preview concept in Umbraco, the Delivery API allows for requesting unpublished content through its endpoints. This can be done by setting a `Preview` header to `true` in the API request. However, accessing draft versions of your content nodes requires authorization via an API key configured in `appsettings.json` file - `Umbraco:CMS:DeliveryApi:ApiKey` setting. To obtain preview data, you must add the `Api-Key` request header containing the configured API key to the appropriate endpoints, like:
321223

322224
```http
323-
GET /umbraco/delivery/api/v1/content/item/11fb598b-5c51-4d1a-8f2e-0c7594361d15
225+
GET /umbraco/delivery/api/v2/content/item/11fb598b-5c51-4d1a-8f2e-0c7594361d15
324226
Preview: true
325227
Api-Key: my-api-key
326228
```
@@ -336,7 +238,7 @@ Draft content is not going to be included in the JSON response otherwise.
336238
If your content is available in multiple languages, the Delivery API can resolve localized content. When querying content by `id`, the `Accept-Language` header can be used to request variant content.
337239

338240
```http
339-
GET /umbraco/delivery/api/v1/content/item/11fb598b-5c51-4d1a-8f2e-0c7594361d15
241+
GET /umbraco/delivery/api/v2/content/item/11fb598b-5c51-4d1a-8f2e-0c7594361d15
340242
Accept-Language: en-US
341243
```
342244

@@ -352,7 +254,7 @@ The output produced by the Delivery API can either represent a specific content
352254
When referring to a specific content item in your API requests, the `id` parameter always refers to the item’s key (GUID) and not its integer node id.
353255
{% endhint %}
354256

355-
{% swagger method="get" path="/content/item/{id}" baseUrl="/umbraco/delivery/api/v1" summary="Gets a content item by id" %}
257+
{% swagger method="get" path="/content/item/{id}" baseUrl="/umbraco/delivery/api/v2" summary="Gets a content item by id" %}
356258
{% swagger-description %}
357259
Returns a single item.
358260
{% endswagger-description %}
@@ -381,6 +283,10 @@ URL segment or GUID of the root content item
381283
Which properties to expand and therefore include in the output if they refer to another piece of content
382284
{% endswagger-parameter %}
383285

286+
{% swagger-parameter in="query" name="fields" type="String" required="false" %}
287+
Which properties to include in the response (_by default all properties are included_)
288+
{% endswagger-parameter %}
289+
384290
{% swagger-response status="200: OK" description="Content item" %}
385291

386292
{% endswagger-response %}
@@ -394,7 +300,7 @@ Which properties to expand and therefore include in the output if they refer to
394300
{% endswagger-response %}
395301
{% endswagger %}
396302

397-
{% swagger method="get" path="/content/item/{path}" baseUrl="/umbraco/delivery/api/v1" summary="Gets a content item by route" %}
303+
{% swagger method="get" path="/content/item/{path}" baseUrl="/umbraco/delivery/api/v2" summary="Gets a content item by route" %}
398304
{% swagger-description %}
399305
Returns a single item.
400306
{% endswagger-description %}
@@ -423,6 +329,10 @@ URL segment or GUID of the root content item
423329
Which properties to expand and therefore include in the output if they refer to another piece of content
424330
{% endswagger-parameter %}
425331

332+
{% swagger-parameter in="query" name="fields" type="String" required="false" %}
333+
Which properties to include in the response (_by default all properties are included_)
334+
{% endswagger-parameter %}
335+
426336
{% swagger-response status="200: OK" description="Content item" %}
427337

428338
{% endswagger-response %}
@@ -436,7 +346,7 @@ Which properties to expand and therefore include in the output if they refer to
436346
{% endswagger-response %}
437347
{% endswagger %}
438348

439-
{% swagger method="get" path="/content/item" baseUrl="/umbraco/delivery/api/v1" summary="Gets content item(s) by id" %}
349+
{% swagger method="get" path="/content/items" baseUrl="/umbraco/delivery/api/v2" summary="Gets content item(s) by id" %}
440350
{% swagger-description %}
441351
Returns single or multiple items by id.
442352
{% endswagger-description %}
@@ -465,6 +375,10 @@ URL segment or GUID of the root content item
465375
Which properties to expand in the response
466376
{% endswagger-parameter %}
467377

378+
{% swagger-parameter in="query" name="fields" type="String" required="false" %}
379+
Which properties to include in the response (_by default all properties are included_)
380+
{% endswagger-parameter %}
381+
468382
{% swagger-response status="200: OK" description="List of content items" %}
469383

470384
{% endswagger-response %}
@@ -474,7 +388,7 @@ Which properties to expand in the response
474388
{% endswagger-response %}
475389
{% endswagger %}
476390

477-
{% swagger method="get" path="/content" baseUrl="/umbraco/delivery/api/v1" summary="Gets content item(s) from a query" %}
391+
{% swagger method="get" path="/content" baseUrl="/umbraco/delivery/api/v2" summary="Gets content item(s) from a query" %}
478392
{% swagger-description %}
479393
Returns single or multiple items.
480394
{% endswagger-description %}
@@ -519,6 +433,10 @@ URL segment or GUID of the root content item
519433
Which properties to expand and therefore include in the output if they refer to another piece of content
520434
{% endswagger-parameter %}
521435

436+
{% swagger-parameter in="query" name="fields" type="String" required="false" %}
437+
Which properties to include in the response (_by default all properties are included_)
438+
{% endswagger-parameter %}
439+
522440
{% swagger-response status="200: OK" description="Paginated list of content items" %}
523441

524442
{% endswagger-response %}
@@ -536,7 +454,7 @@ All endpoints are documented in a Swagger document at `{yourdomain}/umbraco/swag
536454

537455
### Query parameters
538456

539-
The Content Delivery API provides a number of query parameters that allow you to customize the content returned by the API to fit your needs. For each endpoint, the relevant query parameters are already specified within their corresponding documentation above. In addition to standard parameters like `skip` and `take`, the API provides different possibilities for the value of `expand`, `fetch`, `filter` and `sort` parameters. Below are the options supported out of the box.
457+
The Content Delivery API provides a number of query parameters that allow you to customize the content returned by the API to fit your needs. For each endpoint, the relevant query parameters are already specified within their corresponding documentation above. In addition to standard parameters like `skip` and `take`, the API provides different possibilities for the value of `expand`, `fields`, `fetch`, `filter` and `sort` parameters. Below are the options supported out of the box.
540458

541459
{% hint style="info" %}
542460
You can extend the built-in selector, filter, and sorting capabilities of the Delivery API by creating your own custom query handlers.
@@ -545,21 +463,42 @@ You can extend the built-in selector, filter, and sorting capabilities of the De
545463
{% tabs %}
546464
{% tab title="expand" %}
547465
{% hint style="info" %}
548-
Refer to the [Output expansion](./#output-expansion) concept for more information about the benefits of this parameter.
466+
Refer to the [Property expansion and limiting](./#property-expansion-and-limiting) concept for more information about this parameter.
549467
{% endhint %}
550468

551-
**`?expand=all`**\
469+
**`?expand=properties[$all]`**\
552470
All expandable properties on the retrieved content item will be expanded.
553471

554-
**`?expand=property:alias1`**\
472+
**`?expand=properties[alias1]`**\
555473
A specific expandable property with the property alias _`alias1`_ will be expanded.
556474

557-
**`?expand=property:alias1,alias2,alias3`**\
475+
**`?expand=properties[alias1,alias2,alias3]`**\
558476
Multiple expandable properties with the specified property aliases will be expanded.
477+
478+
**`?expand=properties[alias1[properties[nestedAlias1,nestedAlias2]]]`**\
479+
The property with the property alias _`alias1`_ will be expanded, and likewise the properties _`nestedAlias1`_ and _`nestedAlias2`_ of the expanded _`alias1`_ property.
480+
{% endtab %}
481+
482+
{% tab title="fields" %}
483+
{% hint style="info" %}
484+
Refer to the [Property expansion and limiting](./#property-expansion-and-limiting) concept for more information about this parameter.
485+
{% endhint %}
486+
487+
**`?fields=properties[$all]`**\
488+
Includes all properties of the retrieved content item in the output.
489+
490+
**`?fields=properties[alias1]`**\
491+
Includes only the property with the property alias _`alias1`_ in the output.
492+
493+
**`?fields=properties[alias1,alias2,alias3]`**\
494+
Includes only the properties with the specified property aliases in the output.
495+
496+
**`?fields=properties[alias1[properties[nestedAlias1,nestedAlias2]]]`**\
497+
Includes only the property with the property alias _`alias1`_ in the output. If this property is expanded, only the properties _`nestedAlias1`_ and _`nestedAlias2`_ of the expanded _`alias1`_ property are included in the output.
559498
{% endtab %}
560499

561500
{% tab title="fetch" %}
562-
To query content items based on their structure, you can apply a selector option to the `/umbraco/delivery/api/v1/content` endpoint. The selector allows you to fetch different subsets of items based on a GUID or path of a specific content item. If no `fetch` parameter is provided, the Delivery API will search across all available content items. The following built-in selectors can be used out-of-the-box:
501+
To query content items based on their structure, you can apply a selector option to the `/umbraco/delivery/api/v2/content` endpoint. The selector allows you to fetch different subsets of items based on a GUID or path of a specific content item. If no `fetch` parameter is provided, the Delivery API will search across all available content items. The following built-in selectors can be used out-of-the-box:
563502

564503
**`?fetch=ancestors:id/path`**\
565504
All ancestors of a content item specified by either its _`id`_ or _`path`_ will be retrieved.
@@ -579,7 +518,7 @@ For example, the following API call will attempt to retrieve all the content ite
579518
**Request**
580519

581520
```http
582-
GET /umbraco/delivery/api/v1/content?fetch=children:dc1f43da-49c6-4d87-b104-a5864eca8152
521+
GET /umbraco/delivery/api/v2/content?fetch=children:dc1f43da-49c6-4d87-b104-a5864eca8152
583522
```
584523
{% endtab %}
585524

@@ -619,7 +558,7 @@ Multiple filters can be applied to the same request in addition to other query p
619558
**Request**
620559

621560
```http
622-
GET /umbraco/delivery/api/v1/content?filter=contentType:article&filter=name:guide&skip=0&take=10
561+
GET /umbraco/delivery/api/v2/content?filter=contentType:article&filter=name:guide&skip=0&take=10
623562
```
624563

625564
This technique can also be used to perform range filtering. For example, fetch articles created in 2023:
@@ -650,12 +589,12 @@ An option to sort the results based on the sort order of the content item in eit
650589
**`?sort=updateDate:asc/desc`**\
651590
An option to sort the results based on the last update date of the content item in either _`asc`_ or _`desc`_ order.
652591

653-
Different sorting options can be combined for the `/umbraco/delivery/api/v1/content` endpoint, allowing for more advanced sorting functionality. Here is an example:
592+
Different sorting options can be combined for the `/umbraco/delivery/api/v2/content` endpoint, allowing for more advanced sorting functionality. Here is an example:
654593

655594
**Request**
656595

657596
```http
658-
GET /umbraco/delivery/api/v1/content?sort=name:asc&sort=createDate:asc
597+
GET /umbraco/delivery/api/v2/content?sort=name:asc&sort=createDate:asc
659598
```
660599
{% endtab %}
661600
{% endtabs %}

‎13/umbraco-cms/reference/routing/custom-middleware.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,6 @@ This should return the following:
6262

6363
<figure><img src="../images/custom-middleware-cors-browser-example.png" alt=""><figcaption><p>Browser result image</p></figcaption></figure>
6464

65-
An additional bonus is that this doesn't require any changes in your `Startup.cs` file. It also allows packages to enable Cross-Origin Resource Sharing (CORS) and configure their own policies.
65+
An additional bonus is that this doesn't require any changes in your `Program.cs` file. It also allows packages to enable Cross-Origin Resource Sharing (CORS) and configure their own policies.
6666

6767
Users that currently use `WithCustomMiddleware()` will need to add calls to `RunPreRouting()` and `RunPostRouting()`. This is similar to Umbraco adding additional middleware in future versions.

0 commit comments

Comments
 (0)