From 00311169518acd4bafa980bdb515bc6eac17dceb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ale=C5=A1=20Kalina?= Date: Thu, 26 Sep 2019 17:13:14 +0200 Subject: [PATCH] Update README.md - Edit information about a retry policy - Update samples to reflect the latest naming changes --- README.md | 63 ++++++++++++++++++++++++++----------------------------- 1 file changed, 30 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 86e16ef1..956c7671 100644 --- a/README.md +++ b/README.md @@ -40,18 +40,21 @@ We recommend creating the `DeliveryOptions` instance by using the `DeliveryOptio * `ProjectId` – sets the ID of your Kentico Kontent project. This parameter must always be set. * `UsePreviewApi` – determines whether to use the Delivery Preview API and sets the Delivery Preview API key. See [previewing unpublished content](#previewing-unpublished-content) to learn more. * `UseProductionApi` – determines whether to use the default production Delivery API. -* `UseSecuredProductionApi` – determines whether authenticate requests to the production Delivery API with an API key. See [retrieving secured content](https://developer.kenticokontent.com/docs/securing-public-access#section-retrieving-secured-content) to learn more. +* `UseSecureAccess` – determines whether authenticate requests to the production Delivery API with an API key. See [retrieving secured content](https://developer.kenticokontent.com/docs/securing-public-access#section-retrieving-secured-content) to learn more. * `WaitForLoadingNewContent` – forces the client instance to wait while fetching updated content, useful when acting upon [webhook calls](https://docs.kontent.ai/tutorials/develop-apps/integrate/using-webhooks-for-automatic-updates). -* `EnableRetryLogic` – determines whether HTTP requests will use [retry logic](#retry-capabilities). By default, the retry logic is enabled. -* `RetryPolicyOptions` – sets a [custom parameters](#retry-capabilities) for the default retry policy. By default, the SDK retries for at most 30 seconds. +* `EnableRetryPolicy` – determines whether HTTP requests will use [retry policy](#retry-capabilities). By default, the retry policy is enabled. +* `DefaultRetryPolicyOptions` – sets a [custom parameters](#retry-capabilities) for the default retry policy. By default, the SDK retries for at most 30 seconds. * `WithCustomEndpoint` - sets a custom endpoint for the specific API (preview, production, or secured production). ```csharp IDeliveryClient client = DeliveryClientBuilder .WithOptions(builder => builder .WithProjectId("") - .UseProductionApi - .WithMaxRetryAttempts(maxRetryAttempts) + .UseProductionApi() + .WithDefaultRetryPolicyOptions(new DefaultRetryPolicyOptions { + DeltaBackoff = TimeSpan.FromSeconds(1), + MaxCumulativeWaitTime = TimeSpan.FromSeconds(10) + }) .Build()) .Build(); ``` @@ -117,13 +120,13 @@ See [Working with Strongly Typed Models](../../wiki/Working-with-strongly-typed- ## Enumerating all items -There are special use cases in which you need to get and process a larger amount of items in a project (e.g. cache initialization, project export, static website build). This is supported in `IDeliveryClient` by using `DeliveryItemsFeed` that can iterate over items in small batches. This approach has several advantages: -* You are guaranteed to retrieve all items (as opposed to `GetItemsAsync` and paging when the project is being worked on in Kentico Kontent application) -* You can start processing items right away and use less memory, due to a limited size of each batch -* Even larger projects can be retrieved in a timely manner +To retrieve a large amount of items, for example to warm a local cache, export content or build a static web site, the SDK provides a `DeliveryItemsFeed` to process items in a streaming fashion. With large projects feed has several advantages over fetching all items in a single API call: +* Processing can start as soon as the first item is received, there is no need to wait for all items. +* Memory consumption is reduced significantly. +* There is no risk of request timeouts. ```csharp -// Get items feed and iteratively process all content items in small batches. +// Process all content items in a streaming fashion. DeliveryItemsFeed feed = client.GetItemsFeed(); while(feed.HasMoreResults) { @@ -136,10 +139,10 @@ while(feed.HasMoreResults) ### Strongly-typed models -There is also a strongly-typed equivalent of the feed in `IDeliveryClient` to support enumerating into a custom model. +There is also a strongly-typed equivalent of the items feed. ```csharp -// Get strongly-typed items feed and iteratively fetch all content items in small batches. +// Process all strongly-typed content items in a streaming fashion. DeliveryItemsFeed
feed = client.GetItemsFeed
(); while(feed.HasMoreResults) { @@ -152,11 +155,10 @@ while(feed.HasMoreResults) ### Filtering and localization -Both filtering and language selection are very similar to `GetItems` method, except for `DepthParameter`, `LimitParameter`, and `SkipParameter` parameters. These are not supported in items feed. +Both filtering and language selection are identical to the `GetItems` method, except for `DepthParameter`, `LimitParameter`, and `SkipParameter` parameters that are not supported. ```csharp -// Get a filtered feed of the specified elements of -// the 'brewer' content type, ordered by the 'product_name' element value +// Process selected and projected content items in a streaming fashion. DeliveryItemsFeed feed = await client.GetItemsFeed( new LanguageParameter("es-ES"), new EqualsFilter("system.type", "brewer"), @@ -167,9 +169,8 @@ DeliveryItemsFeed feed = await client.GetItemsFeed( ### Limitations -Since this method has specific usage scenarios the response does not contain linked items, although, components are still included in the response. - -Due to not supported skip and limit parameters, the size of a single batch may vary and it is not recommended to dependend on it in any way. The only guaranteed outcome is that once `HasMoreResults` property is false, you will have retrieved all the filtered items. +* The response does not contain linked items, only components. +* Delivery API determines how many items will be returned in a single batch. ## Previewing unpublished content @@ -318,7 +319,7 @@ For list of supported transformations and more information visit the Kentico Del ## Retry capabilities -By default, the SDK uses a retry policy, asking for requested content again in case of an error. You can disable the retry policy by setting the `DeliveryOptions.EnableRetryLogic` parameter to `false`. The default policy retries the HTTP requests if the following status codes are returned: +By default, the SDK uses a retry policy, asking for requested content again in case of an error. You can disable the retry policy by setting the `DeliveryOptions.EnableRetryPolicy` parameter to `false`. The default policy retries the HTTP requests if the following status codes are returned: * 408 - `RequestTimeout` * 429 - `TooManyRequests` @@ -327,23 +328,19 @@ By default, the SDK uses a retry policy, asking for requested content again in c * 503 - `ServiceUnavailable` * 504 - `GatewayTimeout` -or if HTTP requests throw `HttpRequestException` with inner `WebException` and its exception status is one of the following: - -* `WebExceptionStatus.ConnectFailure` -* `WebExceptionStatus.ConnectionClosed` -* `WebExceptionStatus.KeepAliveFailure` -* `WebExceptionStatus.NameResolutionFailure` -* `WebExceptionStatus.ReceiveFailure` -* `WebExceptionStatus.SendFailure` -* `WebExceptionStatus.Timeout` - -There are two parameters in `DeliveryOptions.RetryPolicyOptions` to customize the default retry policy: `DeltaBackoff` and `MaxCumulativeWaitTime`. +or if there is one of the following connection problems: -The consecutive retry attempts are delayed exponentically where the delay (wait time) is based on the `DeltaBackoff` and the number of attemted retries. For status codes 429 (`TooManyRequests`) and 503 (`ServiceUnavailable`) the wait time is read from a standard `Retry-After` header if present in the response. Should the wait time exceed `MaxCumulativeWaitTime` no further retry is attempted and the policy throws either `DeliveryException`, if response resulted in one of the retried status codes, or the original retried `HttpRequestException` thrown by the request. +* `ConnectFailure` +* `ConnectionClosed` +* `KeepAliveFailure` +* `NameResolutionFailure` +* `ReceiveFailure` +* `SendFailure` +* `Timeout` -The defaults for `RetryPolicyOptions` are `DeltaBackoff` of 1 second and `MaxCumulativeWaitTime` of 30 seconds. Custom values can be set through `DeliveryClientBuilder`. +The default retry policy performs retries using a randomized exponential back off scheme to determine the interval between retries. It can be customized by changing parameters in `DeliveryOptions.RetryPolicyOptions`. The `DeltaBackoff` parameter specifies the back-off interval between retries. The `MaxCumulativeWaitTime` parameter specifies the maximum cumulative wait time. If the cumulative wait time exceeds this value, the client will stop retrying and return the error to the application. The default retry policy also respects the `Retry-After` response header. -The default retry policy is implemented without any 3rd party dependency, but you can create your custom policy, for example using [Polly](https://github.com/App-vNext/Polly), by implementing `IRetryPolicy` and `IRetryPolicyProvider`. The instance of the provider can be set to `IDeliveryClient` implementation through the `DeliveryClientBuilder` class or by registering it to the `ServiceCollection`. +You can create your custom retry policy, for example with [Polly](https://github.com/App-vNext/Polly), by implementing `IRetryPolicy` and `IRetryPolicyProvider` interfaces. The custom retry policy provider can be registered with `DeliveryClientBuilder.WithRetryPolicyProvider` or with the `ServiceCollection`. ## Using the Kentico.Kontent.Delivery.Rx reactive library