[Question] What would you expect from a userstyles API ?

[KaKi87]

Hello @tophf,

As I'm planning to create a new userstyles sharing platform as a replacement for the currently leading but slowly dying userstyles.org, I was wondering if I could get your feedback, on what specs would you want, for an API, which could, at some point, be integrated into the Stylus extension.

This integration would include inline search and automated updates, maybe more if you have ideas.

Thanks !

---

Related message by narcolepticinsomniac#7875 on the Open Styles Discord guild :

Inline search was implemented by tophf, so I imagine he'd be fairly particular. You could always open an issue and ask him

[tophf]

I don't have any experience in API design so I'll just tell what Stylus needs (and uses now).

• An endpoint for the inline search needs to be fast and provide a screenshot or even a few, style name, description, author name and link or id, created/updated date, upvotes/rating, daily/weekly/total installation counts, a flag isConfigurable might be useful.

  The search API input parameters would be a) the host name, b) text to search for, both a and b may be specified or only one of the two, c) updated/created date range limits - after and before - one or both, d) the page size - max number of results to return, e) the page number.

  An alternative would be to expose an index file that the extension downloads. We do it currently with USO-archive, here's their index: link.

• An endpoint to get the style code/text. Stylus parses it locally so the text is enough.

  As for an update check, the server should also respond to a HEAD request and return the file's hashsum in etag header just like other popular servers do e.g. github.

[KaKi87]

This is so much interesting, thank you, a lot.

Can you explain how does this index file work ?

[tophf]

It's trivially an array of all style descriptions, see also isResultMatching.

[KaKi87]

I understand.

What is you favorite option between an index and an API ?

[tophf]

If the index file is small (a few MB gzipped) then it's a) much simpler because we only need to download it once when the search UI is shown and b) much faster afterwards as it's literally instantaneous. If you don't import styles from USO your index won't be big for quite a while.

[KaKi87]

Alright, do you think an Etag for the index itself would be useful to check for updates ?

[tophf]

We check styles individually as they may come from different servers. Theoretically you could implement an endpoint that receives an object/array consisting of id:hash (or id:etag) pairs and returns a similarly formed response about their updatability.

[KaKi87]

Yes, I was actually talking about checking if the index itself was updated, e.g. a userstyle was added or removed.

[tophf]

Checking etag on the index would be helpful only if the content on your site is updated like once a day. But if the site gets popular it may be updated every minute.

[Mottie]

I don't know if we still have the OpenUserCSS integration in place, but that might be a place to start?

Also, OpenUserCSS already has a lot of work put into it, but the owner ran out of time/motivation. Maybe you can message him and pick it back up, that is if you don't want to start from scratch.

[narcolepticinsomniac]

Holy hell @Mottie, we made the 'wonderful people' section in that README. I'm glad we're both finally getting the kinda recognition we deserve. =)

Pretty sure I only ever pointed out all the flaws with that site, which never even got fixed.

Maybe you can message him and pick it back up, that is if you don't want to start from scratch.

Fixing all the bugs may very well be easier than starting from square one. If so, it's GPL3, so that's not a huge issue. Maybe the domain would be nice, if he even still owns it, but it could always be switched up.

If the goal is to maximize submissions, you also might consider supporting traditional moz-format, and advanced settings. It'd be easier to migrate traditional styles, and for the presumably significant amount of users who still write non-usercss styles, it's far easier to simply export and paste to publish. I suppose, ideally, even those could be converted to usercss for install.

[narcolepticinsomniac]

Pre-redesign USO might also be worth a look to somebody.

[KaKi87]

@tophf Tank you very much for your feedback, I'm closing this issue since you answered my original question. 🙂

[KaKi87]

@Mottie

I actually would like to start from scratch.

Before writing a single line of code for this project :

• I've sent emails to some devs ;
• Submitted GitHub issues, like this one ;
• Created a feedback form for userstyles users and developers

All of this, to gather all devs and users expectations for this platform, while I'm writing draft specs summarizing feedback submissions.

Once the feedback gathering will be done :

• I will write the final platform specs ;
• Publish those in all community places I can ;
• Ask for final approval ;

If I do get final approval, the development will start right away, if not, the project will be canceled.

The point is, I want to create this platform with everybody's requirements in mind, in the first place, so it will have the highest possible probability of success.

Thanks.