Idea summary
What is the problem to solve?
Drupal 8.0 shipped with a REST API. Unfortunately, it's in a state where it's very difficult to set it up (configuration is hard) and use (DX is hard).
Who is this for?
(Evaluators, site visitors, content authors, site managers, (advanced) site builders, developers, core developers, site owners, other?)
Result: what will be the outcome?
As part of the #2757967: API-first initiative, let's discuss the idea of adding an api.profile
to core. The API profile would ship with default REST and serialization modules, services and permissions configured.
How can we know the desired result is achieved?
(Usability test, a metric to track, feedback)
Comments
Comment #2
cilefen CreditAttribution: cilefen commentedComment #3
yoroy CreditAttribution: yoroy at Roy Scholten commentedComment #4
yoroy CreditAttribution: yoroy at Roy Scholten commentedAdding the "idea template" to the issue summary. Short answers to the 4 questions will help us compare and weigh ideas for their relative impact. Thank you!
Comment #5
yoroy CreditAttribution: yoroy at Roy Scholten commentedWould this need some kind of "Hello world" example or docs to make sense of what's inside? Because this would be headless by design, how would people know what you can do with this?
Comment #6
dawehnerWe used to have a similar discussion in #2873748: Contenta CMS: An API-first Distribution which resulted into Contenta. I think having Drupal being seen as API first rather than some external brand would be huge. The brand value of distributions are still low compared to Drupal itself, and it will take a long time to change that.
I think an API first distribution would be great, at least as a general goal in mind.
There are even first steps of things to get to that goal by cherry picking certain aspects of reservoir and contenta to begin with.
An example is a documentation hub for all things related to API. The api first distribution could be labeled as "Decoupled documentation" or something like that and serve as a way to collect community resources.
As a next step linking to the Contenta consumers building the recipe website, the out of the box initiative is proposing, could be a nice way to communicate to people: Hey Drupal can be used in many ways ...
And then over time we could maybe even add jsonapi and leverage that in the profile.
That's just my train of thought.
Comment #7
e0ipsoCurrently all the distributions that focus around decoupled Drupal rely on heavy use of contrib modules. I'm sure that plays a big role here, just like it did with the Out-of-the-box Inititive:
Both Reservoir and Contenta CMS are based on:
While there are issues open to add the first two into core, there seems to be no active intention to bring Open API (and Schemata). Bringing all these into core quickly will certainly add some risk. Bringing it in a controlled pace (over the course of 1,5+ yr) may mean that we miss this train. The ability to iterate fast is the main reasoning why the community did this in contrib land with Contenta CMS.
I think Daniel is spot on with:
This seems clear to me that we have a hard problem in the marketing space. I am no expert in the matter, but I assume that we can do better than put everything in core to solve this marketing problem. Maybe we could reach out to the marketing people at our companies to brainstorm on this.
Maybe Drupal.Org could have some sort of highlighted distributions that sit right next to the Drupal core download in https://www.drupal.org/download. For a distro to sit there we could require a set of quality standards (that could even mean that it follows the same restrictions as Drupal core with the core committers and maintainers).
This is my idea (as an example of a different path forward), but I'm sure that marketing experts will have much better ideas on a strategy for this.
Comment #8
e0ipsoIf I'm not mistaken http://cms.contentacms.io/help/tutorials is what @dawehner was referring to in:
(it is also obvoius that help is needed to add more articles that you know about in these two issues: #187 and #189)
Comment #9
lauriiiI agree that it would be great if we could promote vetted installation profiles on Drupal.org or on the installer. There's already issue to discuss that #2818085: Promote and allow downloading of vetted install profiles from the installer.
In my opinion, it would be still beneficial to discuss the idea of adding an API installation profile to the core itself. The current standard installation profile is built monolithic sites in mind. This includes the list of modules enabled and the configuration.
Having API installation profile in core would help us double down on API first ideology since it'd force us to weight all decisions from the API first POV. Having an API installation profile would also force us to consider what features are required to build a simple API driven application. We know there's a list of modules that are missing. We could create a plan which one of those will be included in core, and maybe some of the missing dependencies could be recommended in the UI.
I think there's potential to go further than customizing the enabled modules and configuration. Similar to Contenta, we could customize the UI to be more opinionated based on the fact that we know the site is mainly used for creating APIs.
Comment #10
andypostHaving maintenance mode downloader makes sense, iirc core can be reinstalled from profile's config
Comment #11
Wim LeersVery well put!
Contenta got that idea (and much of the code) from Reservoir — yay for FLOSS making it easy to adopt others' ideas. It's kinda cool to see something being repeated back at you :)
So definitely +1 to
I was gonna say that I think we should check with @e0ipso to ensure we don't get in the way of Contenta (Reservoir has been deprecated: https://github.com/acquia/reservoir/tree/deprecation). But based on his comment in #7, it seems like he's very much in favor! Do you still feel that way, @e0ipso?
I don't think it makes sense to "quickly" pull in OpenAPI and Schemata. The foundations in Symfony's serialization system (which Drupal's REST and JSON:API both rely on) does not care about schemas at all, hence OpenAPI and Schemata have a hard time to get to stability. We should fix those foundations before we can pull them into core. But until then, this installation profile could just actively recommend installing those contrib modules for sites that want to have API docs?
#10 I think you meant , where by the latter you are referring to https://www.drupal.org/node/2897299 — yes, we'd want to ship with some default configuration probably.
Comment #12
nod_