[V5] Init Content API RFC

[alexandrebodin]

Introduce the Content API changes for v5

You can read it here

[strapi-cla]

All committers have signed the CLA.

[roelbeerens]

I'm not sure where to comment on the RFC, so I'll add my comments here:

The simplified API response is a welcome feature 🥰. I do however have my concerns about the usage of 'documentId'. It isn't clear to me this response will also be used for the GraphQL response, but last I checked, using something like Apollo with caching, requires an 'id' field. Maybe this is configurable, but next to that, I don't really see the benefits of using something other than 'id'.

Rest looks super solid!

[ComfortablyCoding]

As mentioned above I would also advocate for keeping id as id instead of renaming it to documentId. id is a term everyone is already familiar with and understand what it is for (uid of a record).

I would say we keep ID for the uid of every record and the some other field (entryId sounds good to me) for indicating the id for the base record.

[alexandrebodin]

Thank you all for your comments 🚀 We have an updated version coming next week that thanks to your notes 🔥

[alexandrebodin]

Hello there 👋 There RFC was just updated to clarify certain differences between internal & meta attributes & show the different options that we have. If you can share what you think of each of them for your own DX that would be great 💯

[ComfortablyCoding]

The updated version looks a lot better now!

Given the option return formats I prefer option 2, but with it being meta not internal

Reasoning

• recognizable property from v4
• "internal" can be seen as something that should not be touched or access normally which is not the intention.
• common indicator of meta data of a record which most of the data being stored there will be.
• i dont see it being nested one level deep as an issue. i actually prefer it this way
• do not see a user confusing what is defined on the model and what is being shown in the meta. A lot of education has already been done via v4 on what meta is and what it contains.
• can also put in the metadata information mentioned later on in the spec, having all this "meta" info in one place makes the most sense to me.

Looking forward!

[Boegie19]

This gives me an other question. no matter what option you do. how would you for come name conflicts on the DB layer. Only way I see this working is by prefixing the user generated content.

Also lets say we go for option 3. would that mean none can start a string with a _ or $ since if you where to allow for that that would mean you can still have conflicts.

[alexandrebodin]

This gives me an other question. no matter what option you do. how would you for come name conflicts on the DB layer. Only way I see this working is by prefixing the user generated content.

Also lets say we go for option 3. would that mean none can start a string with a _ or $ since if you where to allow for that that would mean you can still have conflicts.

Depending on the option we go with for the DX here we will of course adapt the DB layer to use prefixes when necessary. It would of course mean we forbidden those prefixes to be used (which is already the case)

[Boegie19]

Other question I see no where in the RFC how you would reference a specific entry in the document.

[alexandrebodin]

Other question I see no where in the RFC how you would reference a specific entry in the document.

the document is a virtual thing fetching a document will always return the content of a single entry. (Based on filters provided or default filters)

if you do (just an example) ?locale=en&state=draft you will get the draft entry for the english locale and by default you would get your default locale and the published version of your document.

[Boegie19]

Other question I see no where in the RFC how you would reference a specific entry in the document.

the document is a virtual thing fetching a document will always return the content of a single entry. (Based on filters provided or default filters)

if you do (just an example) ?locale=en&state=draft you will get the draft entry for the english locale and by default you would get your default locale and the published version of your document.

I think you should also be able to request by id since how would you get a record where a new one has been posted over so it no longer is first in any combination of keys also there needs to be an endpoint that lists all enteries in a document.

[alexandrebodin]

Hello everyone.

Thank you all for your comments 💯

We will go ahead and update this RFC to reflect the option we are going to move forward with and merge it in the upcoming days.

After carefully considering the different Options, Option 1 is the most viable one for v5 and is the one we will be moving forward with.

Here are the main driving deciders

• It provides the better DX for end users
  • Removes as much nesting as possible
  • Simpler query syntax & selecting
  • Less magic = less error prone
• By managing reserverd words & pre-reserving words we can prevent conflicts for upcoming features and until another major comes along where we can introduce new sets of reserved words.
• Offers the possiblility to incrementally add new features by reserving a specialized prefix for all new feature (e.g strapi_)
• Allows introducing Option 2 or 3 without breaking changes by reserving a prefix & a meta/internal key if it becomes a requirement

[martinbeentjes]

I have been using Strapi for a short while now, and the nesting of attributes has been somewhat a hassle. Luckily, with ChatGPT nowadays the generation of all data classes (I consume in Kotlin) made it easier.

For a smooth migration, I think the best option is to supply a request parameter that allows for choosing the format. That way, all consumers of content can prepare for a new version and then a v5.3.x for example can migrate the version to be the new one by default.

---

What I am missing, how would the localizations be added under $.localizations here, just as flattened as the root level? Or is that to be defined?