Contenta CMS: An API-first Distribution

Note: I've beeing also working on one: https://github.com/dawehner/api_first
We should totally colaborate

Thanks for taking the time to create this issue!

Things we need to agree on

1. Use default content or not?

If we add default content we can get front-end devs started in "one click" with quality content and a beautiful design. They can start writing React, Angular, Ember client examples right away. This way we can provide best practises in each of the consumer side examples. Additionally, someone can spin up the distro with content and show a CTO: Look! This is Drupal out of the box. and show an iPad app, Android, React, …

However people that want this for their project need to remove all the default content stuff. We should be able to revert to a clean slate with a single click (restore to factory default settings).

2. What modules are we going to use?

I believe that we should follow an opinionated setup. Promoting the use of REST, JSON API and GraphQL will make maintainability harder. Then we'll end up with people saying: Oh! Too bad! I want to use JSON API and Angular, but I can only see React examples for the JSON API setup.
The only Angular example for this distro is for GraphQL….

Obviously this leads this distro to be a JSON API distro, or a GraphQL distro, etc.

I believe that the best goal that we'll achieve is that we show people: Hey! This works, it's doable. Decouples sites with Drupal are easy!.

I'm a big advocate on being opinionated on this. I vote for JSON API, because it's the only think that I can really help with.

3. What default configuration will we provide?

Not sure if I can think of anything at this moment beyond: enable modules, provide the config for the (hypothetical) default content, and JSON API overwrites.

4. Create a read-only public API server

We host an instance of this distribution somewhere public so client side developers can develop against it, without even knowing Drupal!

We need some hosting company's free/FOSS tier to be offered. Wink, wink.

Thoughts?

We have still not decided that this will be JSON API specific.

Also, I vote that we call this distribution "Contenta!", because it's all about content distribution.

https://translate.google.com/?hl=en&um=1&ie=UTF-8&hl=en&client=tw-ob#ca/...

I can seen an advantage to enabling REST and GraphQL, in addition to JSON API, so that others can write clients that utilize the same install. At the very least, I think the distro should provide these modules in a disabled state so that they can be easily used, if desired, instead of JSON API. This also makes it a little bit more obvious to people new to Headless Drupal what solid Contrib options are available.

I think the idea of @hampercm is totally nice, as long we document why we use one particular subset. Using this distribution as a tool for documentation purposes is IMHO a good idea in general.

@hampercm, @dawehner what would be a reasonable list of modules to ship with the distro? These are some of the contenders:

1. JSON API
2. REST (will come with core anyways)
3. GraphQL
4. Relaxed Web Services
5. Services

My take is that for us to include these in the distro, it would be ideal to have involvement from the maintainers of those modules in this project.

More clarification after talking to Chris @ DrupalCon.

I feel that all the API solutions we include should meet the requirements:

• Can generate an API.
• Can generate automatic documentation.
• The maintainers of those modules think that it's a good idea to include these projects in this distro.

If the requirements are not met, we can include them anyways and work with me maintainers to achieve feature parity.

1 default content - distribution will require few users to setup, guess could be done in install hook
2 modules - probably you will need https://www.drupal.org/project/better_normalizers

#1 Agree that we should provide a mechanism for reverting/cleaning out generated content. If we use the migrate API, we can bring in the content and revert the migration with a fairly low amount of work on our end. We should provide an option when installing the profile to disable the install of content, so that people who work with this distro a lot don't have to have the second step of reverting content.

I think I agree with @andypost of using default_content as mechanism to ship with default content. It seems to become the de facto standard for these kind of things, and unlike migrate, you really just need to ship with the exported JSON files.

We should provide an option when installing the profile to disable the install of content, so that people who work with this distro a lot don't have to have the second step of reverting content.

That sounds like a really nice goal! Let's ensure to always do small steps while not loosing focus.

#2) I agree with being opinionated on out approach here, but I agree with @hampercm that we should provide an easy mechanism to enable/disable the modules we pick. I think providing disabled modules and potentially providing the documentation to switch providers we could have success. However, there could be an argument to provide a parent/sub profile relationship similar to lightning it would be multiple inheritance. This would allow us to have: contenta_jsonapi, contena_graphql, all extending the parent_contenta. Granted this would require the core patch for such inheritance.

Let's ensure to not try to do too many things at the same time :)

I could see a contenta_demo module being very helpful.

Yeah more modules instead of complex installation profiles! I really like this idea.

How is this an idea for core if the objective is to build a distribution? That's essentially contrib, no?

+1 to all of @e0ipso's comments in #16!

I definitely thing RelaxedWS would be a solid fit for this distro. "Services" seems a bit less of a fit, since it is more about developers writing custom code to create a custom API, rather than delivering content from the Drupal entity system using a "canonical" API, which is what I had been envisioning as the purpose of this distro. That being said, I do still see possibilities where that would be useful to have in addition to a "canonical" API.

I also think that addressing the Information Architecture and Content Administration experience is important, since that would be a big factor for people choosing to use this Drupal distro over a proprietary or custom solution. It would be an opportunity to drive adoption of Drupal among people who haven't used it before. I know that @Wim Leers has explored some possibilities in this area. These types of improvements could be taken on after an MVP release.

How is this an idea for core if the objective is to build a distribution? That's essentially contrib, no?

I think that @timodwhit used the "Add child issue link" from #2757967: API-first initiative and that created the issue here. How / where should we move it @yoroy?

For content types: Article and Page? Two vocabularies: tags and article type?

I feel strongly towards coordinating efforts with #79582: Add example content to the experimental out-of-the-box demo install profile. They have the content model defined there already. Current status (at the time of writing) is that we're waiting on gathering content that is license compatible. See https://docs.google.com/document/d/1WdVkScJGs-wHKujvNvwKba_sSuHiHmL69EOa....

Discussed with @e0ipso in IRC, it makes sense to have this plan stay in the ideas queue here.

Looks like this is beyond the idea phase and more about planning things. Carry on :-)

The Out of the Box Experience team has defined the following user stories: https://docs.google.com/spreadsheets/d/1gtiQOm6D3r9w23kYzEcoLP9FloTLU9TA...

Maybe we can collaborate there since we're moving towards a common goal: have a rich content model populated with high quality content.

It is very difficult to coordinate efforts across many different projects. For that reason, and for technical simplicity, I'd like to propose something.

We could build different distributions, no inheritance (that is very painful), but they all build the same thing:

• Same content model.
• Same default content.
• Same admin look and feel.
• Distro logo and branding.
• Similar demo applications (?).
• …

That way we can start with contenta_jsonapi and figure much of this stuff, so when the contenta_rest team rallies around of this distro they don't have to go through all the same pains when building this with REST core. What other distros will gain is that by copying the Contenta way of doing things they don't have to figure out what to build, but focus on the how to build it. A huge benefit of that would be that it would help to compare the different approaches: REST, JSON API, GraphQL, …

Votes? Amends? Thoughts?

I like the idea to not overabstract with introducing the concept of install profile inheritance. This idea is partially about exploration, so some weird strictness caused by inheritance just causes headaches.

I agree that they should be similar to be able to compare the approaches.

@dawehener, what is the best way to merge our efforts for the install profile? It looks like your profile is a clone of Thunder which comes with testing but potentially more config than we desire. Mine is based off of standard and still potentially more config than we desire. I have a small working contenta profile locally but definitely needs some eyes.

Well yeah I started from thunder in order to have some of the goodness they provide, but honestly I don't care about those :)

For content types: Article and Page? Two vocabularies: tags and article type?

On the longrun I would like us to use the magazine idea as proposed on #2759849: Create a new user-facing core theme as part of a Drupal demo. This not only let's us stop bikeshedding about what the data model should look like, but it also helps people to compare different approaches to build sites (Decoupled vs. build in Drupal).

Ooh, reusing the default content model would be super nice indeed. I would not have guessed that Out of the Box and API-first initiatives would have such interesting overlapping needs :-)

@yoroy yeah. Hopefully devs using React, Angular, … will also build the decoupled front-end inspired by the designs in the Out of the Box Experience. IMO that would be very helpful for everyone.

#1 Agree that we should provide a mechanism for reverting/cleaning out generated content. If we use the migrate API, we can bring in the content and revert the migration with a fairly low amount of work on our end. We should provide an option when installing the profile to disable the install of content, so that people who work with this distro a lot don't have to have the second step of reverting content.

We developed a similar module to default_content but leveraging the migrate API
https://www.drupal.org/project/migrate_default_content

It leverages the same concept of just dropping some YAML files but it doesn't support exporting existing content yet.
Since is based on migrate API it fully supports reverting the content.

@timodwhit I feel that you didn't touch on my biggest point:

It is very difficult to coordinate efforts across many different projects.

I won't be able to maintain the contenta_services flavor, I wouldn't know how. Should we have many maintainers for a single project? It feels like too many fingers in a pie. In addition to that is the fact that there is no shared code to maintain, so I don't really see your This could reduce the overhead of maintenance across 1-5 distros. The only tie would be that we build the same product in different techs, each project a single (or a couple) of maintainers.

On a separate note, I'd say that all the flavors would share the common goal of: giving an easy way to demo decoupled Drupal. We could go even further by: trying to give an easy way for front-end devs to choose a particular back-end decoupled flavor.

@e0ipso, I think that makes good sense in some respects.... I would propose a similar approach to experimental modules where we have base contenta and then inside that experimental modules to install different variations of it. Those would be experimental until maintainers of those projects bring in their desired changes etc. Contenta_jsonapi would be a module inside contenta that configures the jsonapi according to specs and those defined by jsonapi maintainers, etc for best out of the box experience.

Some module to share the configuration indeed works as well.

I started using the document on https://docs.google.com/document/d/1WdVkScJGs-wHKujvNvwKba_sSuHiHmL69EOa...
to build such a module: https://github.com/dawehner/recipes_magazin

+1 to this idea.

I am currently working on a proof of concept for best practices decoupling Drupal & Angular with JSON API. I would love to support this distro by building on top of it and helping test / relay back gaps etc.

Currently I am building this POC using a simple custom D8 site, but I could quickly switch over to using this distro once there is a set repo where its development is taking place (it seems like timodwhit and dawehner's repos still need to be consolidated at this point).

I think we are on the same page with regards to sharing code via a custom module, rather than inheritance of profiles. :+1:

I'm not sure I follow the general question. Can you elaborate a little bit further?

@timodwhit: I think I mentioned this above, I agree that it isn't MVP but it might be quickly apparent that the Swiss Army knife of drupal needs some paring down.

Precisely!

@e0ipso: The Out of the Box Experience team has defined the following user stories: https://docs.google.com/spreadsheets/d/1gtiQOm6D3r9w23kYzEcoLP9FloTLU9TA...

Maybe we can collaborate there since we're moving towards a common goal: have a rich content model populated with high quality content.

+1 to that.

@e0ipso: Hopefully devs using React, Angular, … will also build the decoupled front-end inspired by the designs in the Out of the Box Experience.

That would be ideal in my opinion, but I can see this as a significant development effort. Also, there would be a sense of duplication of effort with the other initiatives, but that may simply be unavoidable. I can see this being a big plus for Drupal in the long run.

Also a +1 for the single-distro approach. It seems like multiple distros would result in fragmentation and duplication of effort.

Other thoughts:
Related to the distro name "Contenta" I've noticed via a quick Google search that several companies use that as their name, or a part of it. Is that a point of concern?

Out of the Box team would like to finalize the content model (content types + vocabularies) for the sample content. Have look if you want: #2818741: Content model for sample content in Out of the Box Initiative

Even though there was no movement in this issue many things have been happening:

1. We have been coordinating with the Out of the Box Initiative team to agree on a content model. #2818741: Content model for sample content in Out of the Box Initiative
2. We have been investigating the best way to get data in the system. We will do a custom migration.
3. We have been decided on an admin theme under development that is mobile first and based on materialcss.
4. We have been discussing some of the features:
   • There will be a contrib dependency that will bring the content model and all the content itself.
   • Upon uninstalling that contrib all the demo content types and the content go away leaving a clean slate.
   • We will build everything having in mind other possible flavors of the distribution: contenta_graphql, contenta_services, …
   • There will be a contrib dependency that will bring the content model and all the content itself

All these discussions have been happening ad-hoc between the active contributors in this front:

• dawehner
• e0ipso

If you want to be pinged in #drupal-contribute (IRC) please express that intention here. We'll be giving weekly updates about the distro on the API-First meetings that happen on Monday.

In the mean time there are some interesting resources:

• https://www.drupal.org/project/recipes_magazin
• https://github.com/drupal-http-apis

Please join the discussion at https://drupal.slack.com/messages/C5A70F7D1!

I would love to learn how to use this to demonstrate how to make a api-only site that is consumed by web components.

@cosmicdreams
Do you want to join the slack channel and propose some ideas how this could look like?

Quick heads-up: I have been working on a basic demo app for Drupal + GraphQL + React here: https://github.com/fubhy/drupal-decoupled-app

In case anyone wants to work on a React + GraphQL demo within the Contenta space I'd be happy to give a hand.

With Paragraphs becoming a more and more popular module, caring about Content, i would like to know if Contenta is open to add Paragraphs to its reference case?

@miro_dietiker would the use case for paragraphs be to construct layouts, or just as revisionable entity references? Bear in mind that 2 different consumers will use the same API, but will have different layouts.

Also, Contenta is a Drupal distribution that helps you get started with decoupled Drupal. However it's still Drupal, and you can install any module you need.

It seems to me that if such a project doesn't pick up a case like Paragraphs and provide explicit answers, people that build on top of paragraphs, seeking for answers how to deal with it, will be lost.

Sure, using ERR as a plain example and demonstrating how to output child components is a valuable first step.

Some of the more advanced use cases would be to use nested paragraphs to establish content layout. It would be very interesting to see that case covered by example.

When it comes to layout and layout related functionality I'd love if contenta tried to focus on the core layout system + Panels / Panelizer and provide a workflow against that. One thing that greatly interested me was: https://www.drupal.org/project/panels_rest_expose providing ability to expose complete layout control with all components.

@miro_dietiker
There is an interesting discussion going on regarding a content model for something like a text of the recipe, see https://github.com/contentacms/contenta_jsonapi/issues/66

#2849726: Add an API-First installation profile to core is a similiar discussion going on.

👋

I think we're well into the rejoice step now!