Profile registration

[ethanresnick]

This is (finally!) the PR that will allow people to register profiles and have them showcased on the JSON:API website, with a url on jsonapi.org.

It includes:

• On the existing extensions page, submitted profiles are listed, grouped by category, using categories listed in each profile's yaml front-matter. (The list of available categories is set in _config.yml.) The extensions page now also has a description of the registration process and a link to a Markdown template, which authors can fill out with their profile's specification and submit with their PR.

• There's a new profile.html layout file, which is used to show off the user-submitted profiles. The profile specs live in the _profiles directory/collection. (Lots of HTML from the page.html was pulled out into files in the _includes directory so that it could be reused as snippets in this new profile.html layout.)

• There's an example cursor-based pagination profile. (If people are interested in implementing this profile — @wimleers? — I'd love to get implementation/design feedback on it before shipping it. But this feedback isn't blocking 1.1.)

[gabesullice]

Haven't had a chance to read it all, but so far this looks great!

[dgeb]

@ethanresnick I have a couple general concerns:

• Allowing registrations by name, such as /profiles/cursor-pagination/, provides an official level of approval that we won't be able to reverse. This seems especially dangerous when combined with an expedient review process that doesn't include a quality review.

• Even in the initial version, I'm not sure that profiles should be listed under /extensions. Perhaps we should just have a top-level /profiles index? And I'm not sure whether to keep the "Extensions" menu item at all. Perhaps linking to "how to create a profile" from /profiles would be adequate?

[ethanresnick]

Allowing registrations by name, such as /profiles/cursor-pagination/, provides an official level of approval that we won't be able to reverse.

Is there an alternative to registration by name? The only ones I can think of seem worse (e.g., randomly assigning ids). Moreover, I'm pretty confident that we can decouple whether a profile has a nice URL from whether it seems to carry official approval. Right? After all, the profile's URL isn't shown until the pretty late in the profile discovery process — once the user is on the page for the profile's spec — so there are plenty of UI opportunities before then for us to highlight choice profiles and downplay poor ones. Or, for profiles where we don't want to takes an editorial view about their quality, we could even (if we really wanted to) randomize the order in they appear on the site, e.g.

Even in the initial version, I'm not sure that profiles should be listed under /extensions. Perhaps we should just have a top-level /profiles index?

Are you saying to the URL of the page in this PR should be /profiles instead of /extensions? If so, I'm 100% on board with that, and can update it accordingly.

And I'm not sure whether to keep the "Extensions" menu item at all. Perhaps linking to "how to create a profile" from /profiles would be adequate?

I'm not sure I understand this. If we didn't have a top-level menu item, how would people find registered profiles? Are you saying you don't want to show the list of registered profiles on the site? If so, why?

[dgeb]

Are you saying to the URL of the page in this PR should be /profiles instead of /extensions? If so, I'm 100% on board with that, and can update it accordingly.

Great, sounds like we're in agreement 👍

I'm not sure I understand this. If we didn't have a top-level menu item, how would people find registered profiles? Are you saying you don't want to show the list of registered profiles on the site? If so, why?

I was just saying that we drop the Extensions menu item and replace it with Profiles. And I would prefer that the content at /profiles focus on listing the registered profiles rather than discussing the registration process. We can provide a short section at the top that links to more details about profile registration. So I'm proposing a shuffle of the content you have currently, not the removal of any of it.

[dgeb]

Moreover, I'm pretty confident that we can decouple whether a profile has a nice URL from whether it seems to carry official approval. Right? After all, the profile's URL isn't shown until the pretty late in the profile discovery process — once the user is on the page for the profile's spec — so there are plenty of UI opportunities before then for us to highlight choice profiles and downplay poor ones.

One option here would be to have two classes of profiles - "official" and "community". Each would reflect their "class" in the directory, but not in the URL (otherwise a community profile could never be "promoted"). In this way we could allow profiles to prove themselves as community profiles first, and then eventually promote the most useful and popular ones.

Follow up: I think the major weakness to my proposal is that we have to kind of "prejudge" the quality of community profiles to decide if they're solid enough to grab a significant URL. Maybe a good approach here would be to prefix all profile URLs with an index, such as the PR number used to add them. This approach is taken in the emberjs/rfcs repo - the only downside is that it requires a manual edit step upon merging.

[ethanresnick]

I was just saying that we drop the Extensions menu item and replace it with Profiles.

For context, I kept the menu item as "Extensions" because I thought the term "Profiles" would be unfamiliar to someone new to JSON:API. Basically, I wanted someone who'd just discovered the JSON:API site to see "Oh, there's this nice spec that covers common cases, and also all these off-the-shelf extensions".

Once people are familiar with the spec and know what a profile is, I don't think label "Extensions" will confuse them — plus, we say as the first sentence on that page "JSON:API can be extended with profiles" — so I figured that directing the label at new users made more sense. Thoughts on this approach?

I would prefer that the content at /profiles focus on listing the registered profiles rather than discussing the registration process. We can provide a short section at the top that links to more details about profile registration.

I'm not necessarily opposed to this, but I don't really understand what problem it would be solving. Can you explain the motivation? My biggest goal is to keep the registration process easy to discover, and I think having the link to it in the main Extensions page's left nav is a pretty prominent place for it.

Maybe a good approach here would be to prefix all profile URLs with an index, such as the PR number used to add them. This approach is taken in the emberjs/rfcs repo - the only downside is that it requires a manual edit step upon merging.

I think that could work. My one concern is that it could be tricky to author a profile when you don't know what its URL is gonna end up being. E.g., in my cursor pagination example profile, there are hardcoded references to various error URLs in the spec, but those URLs wouldn't exist at spec authoring time with this approach. So either the editors would have to edit all those URLs upon merging too, or encourage authors to use the {% include profile_url.md page=page %} helper in their spec text... but that seems very cumbersome.

(Also, as an aside, I'd love for the index to be a different path segment, rather than a hyphen-separated prefix — e.g. /profiles/123/cursor-pagination instead of /profiles/123-cursor-pagination — although that would complicate the merge step further.)

Another possible approach would be to use the author's github name as a namespace. So, the URL (and directory structure) would be, e.g., /profiles/dgeb/cursor-pagination. This has the huge advantage of no merge step and predictable URLs for authoring, since Github usernames are already a managed namespace for us. But idk how you or others feel about having the username in the URL; personally, I see pros and cons. Thoughts?

[gabesullice]

I kept the menu item as "Extensions" because I thought the term "Profiles" would be unfamiliar to someone new to JSON:API.

+1

I would prefer that the content at /profiles focus on listing the registered profiles rather than discussing the registration process. We can provide a short section at the top that links to more details about profile registration.

I'm not necessarily opposed to this, but I don't really understand what problem it would be solving. Can you explain the motivation?

I think I agree with @dgeb. The vast majority of users will be searching for applicable profiles and how to use them, not how to register new ones. If you (1) understand profiles (2) want to author one, I think you're already familiar/motivated enough to go looking for a link.

Another possible approach would be to use the author's github name as a namespace. ... But idk how you or others feel about having the username in the URL; personally, I see pros and cons. Thoughts?

This is where my mind went as well. Having a deterministic namespace prior to authoring the profile is desirable. However, I think it's important that there be a namespace, but not that their be a strict definition of what the namespace must be.

The language could be something like this: "a profile URL must take the form /profiles/{namespace-id}/{profile-short-name} where {namespace-id} is a URL safe string which uniquely identifies either the author, organization or project registering the profile." After that, provide a recommendation that one use a Github username/org, email, personal/company TLD, etc.

For example, I'd like to author profiles that we've developed with lots of community involvement. I would not like to tie that profile to my name because I don't deserve all the credit. So, in my case, I'd like to be able to submit a profile like /profiles/drupal/fancy-filters instead of /profiles/gabesullice/fancy-filters.

[dgeb]

I talked with @ethanresnick and we agree with the basic form of your proposal @gabesullice

The language could be something like this: "a profile URL must take the form /profiles/{namespace-id}/{profile-short-name} where {namespace-id} is a URL safe string which uniquely identifies either the author, organization or project registering the profile."

We're going to strongly recommend that the author use either their username or an org to which they belong (which are both easy to verify of course) for a namespace. Exceptions can be allowed for unusual cases.

We also discussed introducing a new Guide section to consolidate a number of sections covering usage of the spec - like Recommendations and Examples. We can also provide directions for creating and registering profiles in that section. But this can be done after this PR is merged as a general content reorg - so no need to block.

[ethanresnick]

Ok y'all, I've updated the PR per the comments above and my discussion with @dgeb. See the most recent commit.

[ethanresnick]

Beautiful. Rebased to keep only the relevant/distinct commits and merged.