Page MenuHomePhabricator

Decide on the CSS endpoint path
Closed, ResolvedPublic

Description

The first iteration of the PCS CSS endpoint exposes three endpoints:

  • /{domain}/v1/page/css/mobile/app/base: returns a domain-independent CSS stylesheet to be used by the mobile apps for displaying Parsoid HTML
  • /{domain}/v1/page/css/mobile/app/site: returns the contents of MediaWiki:Mobile.css for {domain}
  • /{domain}/v1/page/css/mobile/app/bundle: returns a stylesheet aggregating the /base and /site responses for {domain}

These are not exposing page-specific content, but rather site-specific (or, in the case of /base, fully static) content. Hence, they should not be under /page in the endpoint hierarchy. Can the /page segment simply be removed? Should it be replaced with something else?

Event Timeline

Mholloway triaged this task as High priority.Mar 27 2018, 5:06 PM
Mholloway created this task.

I don't think /page is a fitting hierarchy here given the premise that the CSS depends on the wiki, not on specific pages/titles. I would suggest to put it under /media. I would also (potentially) drop the /app/ portion, so my proposal would be https://{domain}/api/rest_v1/media/css/mobile/(base|site|bundle). Alternatively, we can also use /data/ instead of /media/, but I find /media/ more suitable for this case.

/media still sounds more like content to me.
CSS is more about presentation. How about a /site hierarchy?

/media still sounds more like content to me.
CSS is more about presentation. How about a /site hierarchy?

/page actually makes some sense to me, as the CSS is used for displaying a page, even if it's not page-specific.

/site could work: https://{domain}/api/rest_v1/site/css/(base|mobile|bundle), I guess? That's a bit misleading though, because /base isn't actually site specific, and is mainly serving mobile (Minerva) styles.

If we wanted to reflect concepts on the MW side, we could use /resources: https://{domain}/api/rest_v1/resources/styles/(base|site|bundle) (perhaps with base replaced with mobile). That would also put us in a good position to add /resources/scripts endpoints later, should the need arise.

/media still sounds more like content to me.
CSS is more about presentation. How about a /site hierarchy?

Heh, it sounds like we need to get philosophical here and bike-shed a bit. Ok, I'll bite :) CSS does make part of presentation, but IMHO can be categorised as a media component of the site, I would be against /site/ as it's rather undefined (https://{domain}/api/rest_v1/site/ doesn't really inform the client any more than https://{domain}/api/rest_v1/ does).

/page actually makes some sense to me, as the CSS is used for displaying a page, even if it's not page-specific.

I would really avoid using it, as all end points under it pertain to a specific page, rather than a page.

If we wanted to reflect concepts on the MW side, we could use /resources: https://{domain}/api/rest_v1/resources/styles/(base|site|bundle) (perhaps with base replaced with mobile). That would also put us in a good position to add /resources/scripts endpoints later, should the need arise.

I would prefer to avoid main hierarchy proliferation, and a similar point can be made for /resources/ as I made for /site/ above.

I can live with /media or /data. Which one do you prefer?

Let's go with /media then if there are no other objections.

Change 423474 had a related patch set uploaded (by Mholloway; owner: Mholloway):
[mediawiki/services/mobileapps@master] Update CSS endpoint paths

https://gerrit.wikimedia.org/r/423474

Change 423474 merged by jenkins-bot:
[mediawiki/services/mobileapps@master] Update CSS endpoint paths

https://gerrit.wikimedia.org/r/423474

Sorry for coming in late here. But I do have an objection with using media. We have another api named media so that’s kind of confusing

How about just site/css?

Sorry for coming in late here. But I do have an objection with using media. We have another api named media so that’s kind of confusing

The other endpoint is not the top hierarchy, so /page/media and /media/css is pretty different looking

I get that it’s in a different hierarchy but it’s odd to have the only api that delivers media not under the media hierarchy.

Also media is very specific. And there are literally no other APIs that will go under that hierarchy. So if we don’t want to have a proliferation of top level hierarchies this seems like a path we shouldn’t introduce.

I’m open to other options besides site, though site is at least generic and I can see us using that for other site specific APIs.

I just think that having recently released the media end point this is not a great name

@mobrovac Given @Fjalapeno's objections to /media, OK with falling back to /data as the top level of the hierarchy for this?

@mobrovac Given @Fjalapeno's objections to /media, OK with falling back to /data as the top level of the hierarchy for this?

Yup, +1 on /data. @Fjalapeno, as I wrote in T190849#4088156, I wouldn't go with /site because it does not convey any extra useful information to the client in my mind.

Change 423518 had a related patch set uploaded (by Mholloway; owner: Mholloway):
[mediawiki/services/mobileapps@master] CSS: Use 'data', not 'media', as the base of the endpoint path hierarchy

https://gerrit.wikimedia.org/r/423518

Change 423518 merged by jenkins-bot:
[mediawiki/services/mobileapps@master] CSS: Use 'data', not 'media', as the base of the endpoint path hierarchy

https://gerrit.wikimedia.org/r/423518

Mholloway closed this task as Resolved.Apr 2 2018, 8:28 PM