Introducing: a client for the PubPub API

[tefkah]

Hi all! I was slightly hesitant to share this, because I wasn't sure how happy PubPub would be with it and whether they might try to limit access, but I thought it'd be better to be cooperative than sneaky, so presenting: a client for interacting with the PubPub API!

After this discussion (#1742) I looked through a lot of the PubPub source code to try and (reverse-)engineer a way to do the same things with PubPub through code as you would in the app, and I'm happy to say I mildly succeeded!

With the current client, you can

• Query pubs
• Create, modify, and delete pubs, including uploading pdfs
• Import documents to pubs!!
• Create, modify, update, and get collections
• Create pages
• Modify your community settings
• Change attributions on Pubs and Collections

You just need an admin PubPub account (no support for more granular permissions yet) and your community URL and ID. You can find your community's ID, as well as the IDs for public Pubs and collections at this website I made (https://pubpub.tefkah.com).

What's not possible yet

• minting dois (should not be too hard)
• doing stuff with users
• modifying or deleting the text of a Pub. You can only add to it by importing at the moment.
• having good fallback when something goes wrong. I think it's important to log out after you are done using the API, as I have had some issues in the past which i think were due to too many sessions happening. At the moment you need to logout manually by calling PubPub.logout though, I would like to implement some kind of error catching thingy that auto-logs out if something goes wrong.

What's intentionally not possible

• Creating and deleting communities. Feels like too much power, and would mostly be a one time thing to do.
• Uploading arbitrary files. In order to upload pdfs or import documents, I need to upload files to the PubPub S3 thing (which also happens when you do this through normal means). At first I had this exposed as a public method, but this would mean you could just dump a whole bunch of files on PubPub's S3, which would not be good manners.

Some of these things (like getting Collections and importing documents) are achieved through quite hacky means (just fetching the relevant page and parsing the data that is passed there) as I could not find any other means of doing so (there is no "get collections" endpoint for instance).
Also, AFAIK there are no very concrete typings or definitions for the endpoints, so most of the input/output types are guesswork on my end and can probably break!

It is quite unstable as I haven't thoroughly tested every method yet, but I can confirm it works though! I was able to import 30 word docs in very little time using it :)

Hope you find it useful, I hope this can lead to more cool integrations with PubPub!

And to @gabestein, if this poses any problem to you please let me know and I will either modify it or take it down!

All the best,

Thomas

[gabestein]

Hey Thomas! Just wanted to say we saw this over the weekend and love that you built it. We can't immediately support or recommend it right at this moment, but we are going to reach out for a chat about how we might be able to. Talk soon!

[tefkah]

Understandable, would love to chat with you all about it! You can schedule a meeting with me here: https://cal.com/tefkah

[daaronr]

Thanks. I'm hoping we can get this working for the Unjournal.
https://unjournal.pubpub.org/
bit.ly/eaunjournal

Atm it's taking us about 3-4 hours to process the many parts of an evaluation of a paper; hoping to automate as as much as possible with the API.

[tefkah]

great, let me know if you need any help! documentation will be added soon, but id like to point out that the PubPub.pub.hacks.import function now allows you to pass a preprocess function, which you can use to process the imported file(s) before it gets uploaded to PubPub.

I use this to e.g. update the labels of references to more accurately match APA, e.g. to turn (Guy, 2020)(Dude, 2021) into (Guy, 2020; Dude, 2021).

if you're interested i could share this example. although it's a bit messy i think it can give a good idea of what's possible with the API