No support of rel_uuids

[frastel]

Expected Behavior

Usage of "resolve relations" always works when fetching multiple stories, also when more than 50 stories to be resolved are found.

The official documentation of the content management API says:

Resolved relations are included in the rels property of the response. A maximum of 50 stories can be resolved. > If this limit is exceeded, the story UUIDs are included in the rel_uuids property of the response and can be used > for further API requests (this is handled automatically when using one of Storyblok's official frontend SDKs).

The deprecated PHP SDK did this automatically and we expected that the new SDK does this too.

Current Behavior

When 50 or more stories are found to be resolved, the API response contains a "rel_uuids" and not a "rels" key.
The used "StoriesResponse" ValueObject however makes an assert on the "rels" field und throws an exception when the "rel_uuids" key does exist. There is no way to avoid this behaviour nicely.

Current workaround would be to implement an own StoriesApiInterface, copy&paste a lot of things and use an own StoriesResponse value object.

Steps to Reproduce

1. Fetch > 50 stories which have at least one unique relation to be resolved. The API response contains an "rel_uuids" key than and misses the "rels" field.

[silasjoisten]

This one is a tricky one — and you’re absolutely right to raise it.

I agree that we should support this case more gracefully. A good first step would be to relax the assertion in StoriesResponse and make the rel_uuids field accessible as an optional property. That way, users won’t run into unexpected exceptions and can still handle the fallback logic themselves if needed.

However, I’d prefer not to add automatic fetching of additional related stories in this SDK.

The reason is simple: this would silently introduce additional API requests, which:

• could have side effects on rate limiting or quotas,
• impact performance without the user being aware,
• and may not always be desired (e.g. when working in batch-processing mode or caching scenarios).

Instead, I believe it’s better to expose the rel_uuids explicitly and leave it to the developer to decide whether to follow up with another request. This approach gives full control to the consumer of the SDK while avoiding hidden behavior.

[silasjoisten]

Here is the PR which adds the property for rel_uuids #67

@frastel does this also count for the StoryResponse object? Or is this only for the StoriesResponse?

[frastel]

rel_uuids could also be possible in StoryResponse but we never had this case so far, although we have a very complex structure. One single story with more than 50 relations to be resolved sounds for me like a design flaw but theoretically it would be possible in API responses.

"leave it to the developer to decide"
Mmh this would make it less comfortable for developers which are used to the old SDK.
In my opinion the SDK should have more intelligence and should not just "curl" the responses from Storyblok. There should be some advantages to use the SDK and not to build just plain curl calls.

I just checked other Storyblok SDKs and they also fetch the additional stories automatically like e.g. storyblok/js.

[edodusi]

I agree with you @frastel that the SDK should have intelligence and helpers, on the other hand I'm with @silasjoisten when he says that it should not perform additional requests hiding the logic from the user, because this has an impact on the rate limits and it also alters the response.

However we could discuss the addition of a helper that can be optionally used to fetch the additional relations, leaving the control to the user, so while this issue can be fixed by adding rel_uuids we can also open a feature request and discuss implementation details.

[frastel]

@edodusi You have to understand that this causes pain for developers/customers (like us currently) which are using the deprecated SDK since several months (ok almost two years) and do not have the functionality in the new SDK now.
As you could imagine we have no time for implementing stuff which did the old SDK automatically. Missing parameters and missing "magic" is currently a blocker for us using the new SDK. Its quite a bad situation for us having a deprecated SDK one the side and on the other side a new SDK which has less functionality than the old one.

So it would be great having this helper and use this functionality directly from the SDK.

[edodusi]

@frastel I know the old PHP client did this, and the current JS client has it too, but we decided to remove this feature and it will be deprecated in the JS client in a future release.

This is because we want the clients to be as close as possible to the API reference, they should act as wrappers and it should be predictable how many requests a method will generate. Having a method potentially generating an arbitrary number of requests is a risk, also given the rate limits.

I think we can discuss a helper that wraps on another call to fetch multiple uuids, and this should probably live in an SDK (like the Symfony Bundle) rather than in the client.

We can also improve our documentation to give some examples on how to fetch the additional relations, and I will also raise the issue to our backend team regarding how could we support this scenarios in our API.

Right now, I think @silasjoisten 's PR should close this issue.

[frastel]

Ah, good to know that the automatic resolving of the additional relations is deprecated in general. Thanks for the clarification.

However we would prefer an optional solution for this in the client lib and not in the bundle. Like it was already done with StoriesApiInterface and the possibility to resolve the relations automatically (StoriesResolvedApi and StoriesApi).

We do not use the bundle. Coming from the old PHP SDK our existing code is not quite compatible to the assumptions the bundle makes and we don't have the time to switch to the new SDK AND to the bundle.

[edodusi]

@frastel it's not yet deprecated in the JS client, but it will be in a future release.

I would like to discuss a technical implementation that does not involve an unpredictable numbers of API calls. I strongly believe that this is for the better.