kontent-ai / delivery-sdk-ruby Goto Github PK

Motivation

To improve response times Delivery API might provide stale content. Stale means that there is a more recent version, but it will become available later. This information is important for developers who implement caching because stale content should have a short TTL. Developers can inspect the value of the X-Stale-Content response header. 1 indicates that content is stale. If the header is not present or it has a different value, content is not stale.

Proposed solution

Extend response models with information whether content is stale. For consistency it is recommended to use a has stale content bool property with the proper case type.

Hello, I have noticed you are incorrectly parsing the modular content of content items queries.

The model of a listing response differs from the model of a single content item. Modular content is always on the first level of response, therefore if the list is queried it can no longer parse modular content from the level of the particular content item.

Currently, it is being parsed in the same way which results in incorrect behavior of retrieving links from such items.

To give an idea about the problem, I have fixed it on my branch. commit

https://github.com/Kentico/Home/wiki/Guidelines-for-SDK-developers#analytics

Brief bug description

I am trying to follow this tutorial: https://kontent.ai/blog/creating-a-kentico-cloud-ruby-on-rails-application to integrate Kentico Kontent into an existing Rails v6.0 application.

I have installed both of these gems:
gem 'delivery-sdk-ruby'
gem 'render_async'

I added the snippet below to my ApplicationController and replaced with my Delivery API Project ID.

PROJECT_ID = '<your-project-id>'.freeze
@@delivery_client = KenticoCloud::Delivery::DeliveryClient.new project_id: PROJECT_ID

At this point, I am receiving the following error message: 'NameError: uninitialized constant ApplicationController::KenticoCloud'.

I tried to dig into the dancing_goat example from this repo and noticed a few discrepancies:

• It's using gem 'kontent-delivery-sdk-ruby', which shows the following error message when attempting to install: 'Could not find gem 'kontent-delivery-sdk-ruby' in any of the gem sources listed in your Gemfile.'
• The delivery_client is being assigned with Kentico::Kontent::Delivery::DeliveryClient.new instead of KenticoCloud::Delivery::DeliveryClient.new. Which is correct?

What am I missing to get this integration up and running?

Motivation

Feature is required thus, no method providing project languages is present. User can now get all his project languages.

Proposed solution

Introduce a method providing all project languages

Additional context

Should be released 01.25.2021
endpoint-{deliveryApi}/{projectId}/languages

{ "languages": [ { "system": { "id": "00000000-0000-0000-0000-000000000000", "name": "Default project language", "codename": "default" } }, { "system": { "id": "8fab3c4c-2ba4-47a9-8e53-df8e6154054f", "name": "First Lanugage", "codename": "first_language" } }, { "system": { "id": "24d5aaa6-a0db-4e20-8c11-6eb272bbe168", "name": "Second Language", "codename": "second_language" } } ], "pagination": { "skip": 0, "limit": 0, "count": 3, "next_page": "" } }

https://github.com/Kentico/Home/wiki/Guidelines-for-SDK-developers#naming-conventions

Motivation

Introduces new system property 'workflow_step' representing codename of the workflow step, an item is assigned to. Items can be filtered out based on this property

Proposed solution

Introduce new property to system object of items. Components should not contain this property.

Additional context

Motivation

Define how to deploy a new version of GEM.

Proposed solution

Extend Travis CI configuration of the Deploy step.
Use the tag release trigger.

That allows all people to create a new version to the gem.

Additional context

• https://docs.travis-ci.com/user/deployment/rubygems/
• https://travis-ci.org/Kentico/delivery-sdk-ruby

Fix the failing builds in Travis:

• https://travis-ci.com/Kentico/delivery-sdk-ruby/builds

https://github.com/Kentico/Home/wiki/Guidelines-for-SDK-developers#required-endpoints

/types/{type_codename}/elements/{element_codename}

Motivation

According to Kontent.ai documentation, the "project" is renamed to "environment" to correspond with the project/environment structure in Kontent.ai UI. So all, that is related to environments, should be also renamed in SDK.

Proposed solution

Rename all mentions about "project" to "environment" (primarily projectId -> environmentId).

Additional context

Delivery REST API documentation

https://github.com/Kentico/Home/wiki/Guidelines-for-SDK-developers#required-endpoints

/taxonomies
/taxonomies/{taxonomy_group_codename}

I am not sure if it is by design or just not thought of

My case

1. The link resolver returns this url {{ site.pages | where_exp: 'page', 'page.data.system.id == link_id' | map: 'url' | first | relative_url }}

2. Nokogiri escapes special characters

3. Result cannot be further processed by a templating language such as Liquid

Naive solution: Once the content/link is resolved, call doc.to_xhtml instead of doc.inner_html which is not escaping the anchor href attribute value.

Motivation

I noticed that the SDK is published under a personal account. From a long-term perspective, it'd be better to have it published under an organizational account.

Proposed solution

Create an organizational account (registered to [email protected]) and publish the gem using this account.

Motivation

This SDK can be consumed from other Kontent solutions and it would be nice to be able to track and distinguish their usage. E.g., X-KC-SOURCE header to determine the package and version.

Proposed solution

class DeliveryQuery having accessor for custom headers.

Expected result

Have the section in the official KenticoCloud documentation (as it is for i.e. PHP)

Additional context

We would like to have the section filled for the Ruby SDK.
We need information/links to the page:

• Link to the repository
• Link to the package in package manager (gem)
• Links to the documentation (readme) to be able to fill Supported features
• Provide the link to the sample application
• Provide link(s) to the blog post about the Ruby

https://github.com/Kentico/Home/wiki/Guidelines-for-SDK-developers#rate-limitation

Currently, the resolved links don't contain the modular content and nested links cannot be resolved.

I understand that circular/too many levels of nesting might be problematic but I think that is a problem for the consumer to solve.

dotenv is specified as a development dependency but it is being loaded during runtime from request_manager.rb. This causes the app to crash.

Motivation

Allow developers to fetch all content item variants from the new \items-feed endpoint. This offers developers a way to export an entire project no matter the size.

Proposed solution

The content is is provided in small chunks together with a continuation token for the next chunk. The continuation token is sent in X-Continuation header both for request and response. Should the response from Delivery API contain the token, there are additional items to fetch. If the request does not contain the continuation header, Delivery API will return the first chunk.
Filtering parameters are same as for items endpoint but paging and depth are not supported.
The response has also the similar structure to items endpoint but paging object is missing and modular_content contains only components.

Implementation details for consistency: (name casing should be adapted according to the rest of SDK)
Add a new method to DeliveryClient with a name GetItemsFeed(). The method should support the same filtering parameters as GetItems() except for depth, skip and limit and return a content items variants feed.
The feed contains a bool property HasMoreResults that is true if the first batch was not yet fetched or there are more items to fetch (indicated by a continuation header in the previous response). The feed also contains a method FetchNextBatch() that would retrieve the next response from \items-feed endpoint.

Additional context

See .NET SDK for reference code

https://github.com/Kentico/Home/wiki/Guidelines-for-SDK-developers#requesting-latest-content

Motivation

From February 1st, 2020 Delivery API will start enforcing rate limits to ensure fair usage by as many clients as possible. These rate limits should be high enough to work for most clients by default. However, in particular cases Delivery API might respond with 429 Too many requests. These responses will also contain the Retry-After header indicating how long the client should wait before making a follow-up request.

Proposed solution

Implement a retry policy that handles 429 Too many requests and retries the HTTP call using information from an optional Retry-After header. It can contain a date after which to retry or the seconds to delay after the response is received. We recommend a retry policy with exponential backoff and a jitter strategy to overcome peaks of similar retries coming from many clients. The retry policy should handle the following status codes:

• 408 Request Timeout
• 429 Too many requests
• 500 Internal Server Error
• 502 Bad Gateway
• 503 Service Unavailable
• 504 Gateway Timeout

Please note that both 429 Too many requests and 503 Service Unavailable responses might contain an optional Retry-After header.

Additional context

• https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
• https://github.com/Kentico/kontent-delivery-sdk-net/blob/master/Kentico.Kontent.Delivery/RetryPolicy/DefaultRetryPolicy.cs

Motivation

Allow users to render paging navigation for a list of content items.

Proposed solution

When the item listing request URL includes the includeTotalCount query string parameter, the response contains the total number of content items matching the search criteria. As a result, the client needs only one API call to fetch all information necessary to display a list of content items and the paging navigation.

To return the total number of content items, the includeTotalCount parameter must have value 1 or true or no value at all.

The total number of content items is returned in the pagination section of the response in the total_count property. Please note that if the user does not ask for the total item count, this property is not present.

Add support for the includeTotalCount parameter and also provide the total number of content items, if available. Also, please provide a warning in documentation comments that asking for the total number of content items might increase the response time and, therefore, users should use it only when they need it.

Additional context

For a reference implementation please have a look at https://github.com/Kentico/kontent-delivery-sdk-net/blob/master/Kentico.Kontent.Delivery/QueryParameters/Parameters/IncludeTotalCountParameter.cs

Motivation

The Gem ID is being defined in 2 files:

• delivery_query.rb
• delivery-sdk-ruby.gemspec - also the filename of the file should be changed to "kontent-ai-delivery"

Proposed solution

• Unify everything, but the repository name to kontent-ai-delivery.
• Try try to load this information from gem spec.
• Rename delivery-sdk-ruby.gemspec to kontent-ai-delivery-sdk.gemspec

Additional context

Add any other context, screenshots, or reference links about the feature request here.

Delivery API ensures that modular content has the same order of items as on the web UI.

Currently, the order is broken due to iterating over the common modular content source from get_links and get_inline_items.

When the depth is not correctly set and we try to access a linked_item the gem raise a unhandled exception.

undefined method '[]' for nil:NilClass

that occurs in lib/delivery/resolvers/linked_item_resolver.rb at

def resolve_item(codename)
  item = @modular_content.values.find { |i| i['system']['codename'] == codename }
  ContentItem.new JSON.parse(JSON.generate(item)), @content_link_url_resolver, @inline_content_item_resolver, self
end

The codename is not inside the modular_content so the find method return nil

It's easily fix by increasing the depth size of the request but that would be better to raise a custom exception.

Test environment

• Ruby 2.7
• kontent-delivery-sdk-ruby 2.0.22

Motivation

Customers want to use their own domains in asset links instead of the default Kontent asset URL. This way the links on their webpage will look more trustworthy, and since the custom links will be visible in search engine results, it also helps SEO optimization.
We will implement the support for custom asset domains in the Kontent app BE and Deliver, but for the whole solution to work, we also need the support in the SDK.

Proposed solution

We would like to add a new item to SDK configuration - custom asset domain. The customer would be able to set the domain. When the customer gets the item/variant that contains an asset (in Asset element or Rich text element), the custom domain will be used in the link instead of the default Kontent domain. The rest of the URL will stay the same.
Example: https://test15641652.assets.com/3727c9f0-9ea0-0068-2d4f-e6cdb4acff9d/1e040cde-e4be-4dac-a006-d406e40abf56/cat3.jpg instead of https://qa-assets-eu-01.freetls.fastly.net/3727c9f0-9ea0-0068-2d4f-e6cdb4acff9d/1e040cde-e4be-4dac-a006-d406e40abf56/cat3.jpg

Additional context

Release date: the BE part of the solution is done, you can release the SDK changes as soon as they are ready.

Feel free to be inspired by already implemented JS SDK:

• issue kontent-ai/delivery-sdk-js#333
• merged PR kontent-ai/delivery-sdk-js@2e5ae06

Motivation

The deliver will soon support sending collection information within the item.system property.
Feature release ETA: 25.11

Proposed solution

See .Net SDK solution here.

Additional context

Example of system property with collection:

"system": {
      "id": "f25f38d3-a453-41fe-bc2e-804258b5dbda",
      "name": "My first item",
      "codename": "my_first_item",
      "language": "default",
      "collection": "default",
      "type": "article",
      "sitemap_locations": [],
      "last_modified": "2020-11-16T18:43:11.9212466Z"
    }

Type of collection system property: string
Collection property is required with a default value default.

Components and linked items in modular_content property also have collection in system property.

Motivation

New Kontent feature - Asset renditions, will be released soon (beginning of December with) and it will be available through DeliveryAPI. We should have them covered in SDKs as well.

Proposed solution

When the asset element is retrieved from Deliver, the referenced assets can now contain user-defined renditions and it is easy for the developer to apply the rendition query string to the URL of the original asset so that the customized image can be rendered in the UI.

Additional context

This is the updated Deliver contract for referenced assets of asset element:

• New renditions property is present and it is a dictionary with a single key (for now) equal to the "default" preset codename. Presets are not a real entity for now but are part of the long-term vision of asset renditions.
  • the property will only be present for image-like objects (those which have both width & height properties set by the system)
  • when no renditions are defined for the linked asset, the empty object/dictionary is returned in the rendition property
  • if the asset is of non-image type (e.g. .pdf) the property won't be present (same as width & height in that case)
• Ideally, to ease the adoption for the users, it would be nice to introduce support for "defaultPreset" which would automatically apply the query parameters of the rendition in preset specified by the global config.
  • Feel free to get inspired by the already implemented support in JS or .NET SDKs
• Note, that this only applies to assets in the asset element. There is no support for renditions in inline RTE images, yet.

{
    "name": "name-of-the-uploaded-file.jpg",
    "type": "image/jpeg",
    "size": 90895,
    "description": "Description of what the asset represents.",
    "url": "https://assets-us-01.kc-usercontent.com/975bf280-fd91-488c-994c-2f04416e5ee3/3e76909f-599f-4742-b472-77fd4b510e92/sources.jpg",
    "width": 1000,
    "height": 666,
    "renditions": {
      "default": {
        {
          "rendition_id": "d44a2887-74cc-4ab0-8376-ae96f3f534e5",
          "preset_id": "a6d98cd5-8b2c-4e50-99c9-15192bce2490",
          "width": 200,
          "height": 150,
          "query", "w=200&h=150&fit=clip&rect=7,23,300,200"
      }
    }
}

Motivation

The reason for new filtering operators is to give the users of our API better tools for getting just the content they need.

Proposed solution

Add the new filtering operators mentioned in the Kentico Kontent product changelog.

Additional context

You may look at the implementation for .NET for a reference (i.e. EmptyFilter).

elements return an OpenStruct object which means all element codename keys are transformed to symbols. So if you iterate over them and eg want to get links or assets you need to convert the key to string yourself which is not intuitive and annoying.

The symbol can be easily converted to a string to work with the internal data structure.

codeclimate/test-reporter#418

Motivation

Currently, this repository does contain E2E tests that depend on the testing project (faf446d2-0544-0039-bb43-5d6ef816661a).

Proposed solution

Add an abstract layer between Rest Client and Kentico Cloud Delivery client. Use Rest client by default and also provide a way (as a part of the configuration/constructor) to be able to define the implementation for HTTP requests.

Rewrite all E2E tests to be Isolated (if possible even unit tests).

Create one E2E complex test that request data from the Sample Dancing Goat project (975bf280-fd91-488c-994c-2f04416e5ee3) to have a check when some data change in the sample project.

Additional context

This allows having the data for the tests as a part of this repository and outside collaborators would be able to extend them + we would not be reliable on the

Bundle-audit is flagging Nokogiri to be too low of a version in my project. However, when attempting to upgrade to 1.11.0, it fails because the kontent-delivery-sdk-ruby is locking the version as seen below:

kontent-delivery-sdk-ruby (~> 2) was resolved to 2.0.12, which depends on
      nokogiri (>= 1.8.4, ~> 1.10.0)

Can this be updated as Nokogiri has been updated?

Link to Nokogiri security issue: GHSA-vr8q-g5c7-m54m

Motivation

The feature exists in existing SDKs:

• https://github.com/Kentico/delivery-sdk-net#resilience-capabilities
• https://github.com/Kentico/delivery-sdk-php#using-the-deliveryclient
• https://github.com/Kentico/kentico-cloud-js/blob/master/packages/delivery/DOCS.md#client-configuration

It helps circumvent intermittent network issues.

Proposed solution

rest-client doesn't seem to have this logic implemented, so it needs to be created from scratch, probably using some static class when querying

Motivation

Currently, we don't have the status of the code coverage automatic way.

Proposed solution

Set up the CI (Travis) to count the test coverage and submit them to the Code Climate.
Add the badge to the Readme.

Additional context

• https://docs.codeclimate.com/docs/configuring-test-coverage
• https://docs.codeclimate.com/docs/travis-ci-test-coverage