Updated docs for API version 2

[maciej]

Hi everyone!

I've put up two draft documents today, the first an overview:

https://pinboard.in/api/v2/overview/

And the second an API call reference.

https://pinboard.in/api/v2/reference/

Please post your comments, criticisms, and suggestions here. For the moment you should ignore the example links, since they are just placeholders.

Here's a short list of changes I incorporated from people's helpful feedback last time around:

* Added /delta/notes and /delta/tabs

* Add an ability to save tab sets, and rename them

* Added a URL parameter to GET /bookmarks/

* Added "read" and "tagged filter to bookmarks

* Added a /url/ endpoint 

* Add a way to star bookmarks

One thing on my list that's still not in the docs is a /random/ endpoint. I'll put that in the next update. 

Let me know what to fix/change/clarify!

Maciej

[Maksim Lin]

Thanks Maciej, this looks great!

Iin my excitement, of course I immediately tried to ping the test server but it looks like it's not up yet?

curl https://api.test.pinboard.in/v2
curl: (6) Could not resolve host: api.test.pinboard.in

Thanks,

Maks.

----

Maksim Lin 

Freelance Android & Flutter Developer
GDG and Flutter Melbourne Co-Organiser, Flutter GDE

www.manichord.com

--
You received this message because you are subscribed to the Google Groups "Pinboard" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pinboard-dev...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/pinboard-dev/25229ad5-f290-4cbf-80d3-7a9c52ce3f57n%40googlegroups.com.

[shamelessly mkp]

This looks fantastic so far! There are two features I'd like to suggest, however:

1. Recognize HTTPS urls as already being bookmarked if it was bookmarked in HTTP form
   
2. Allow for an API call that can pull a list of all tags, the number of bundles they've been added to, and the names of those bundles, if applicable. While it's true that the API calls as drafted will allow you to get this information, it provides it in a way that requires significant manual manipulation of data on the part of the user - to illustrate:

Say that I have a Pinboard tag named "character:harry.potter". I know that tag should have been added added to the bundles "fic-by-character", "characters:c", "fandom:harry.potter", and "representation:survivors.of.abuse". I don't know for certain whether or not I've already added it to each. I can go check manually one by one, but that takes time, means that I have to keep track mentally of all the bundles it should be in and whether or not I've checked the bundle in question yet, and doesn't catch any bundles it's been mistakenly added to.

Ideally, if I used a GET call along the lines of GET /tags/bundles/, I would then get a list of all of my tags. The "character:harry.potter" tag would be followed by names of all the bundles it currently belongs to. I now know whether or not I've added the tag to all of the bundles it belongs to, and that it has only been added to the bundles it belongs to.

As drafted, I would have to:

1. first: run the GET /bundles/ call to make sure I had a full and accurate list of all bundle names
2. second: run the GET /bundles/name/ for bundle #1
3. third: take the results and paste into excel
4. fourth: use the text-to-columns feature to separate the tag names
5. fifth: transpose data from column format to row format
6. sixth: in a separate column, add the bundle name to all rows
7. (repeat steps 2 through 6 for all bundles)
8. seventh: sort and search for the tag in question and check each row it shows up in for the bundle name
9. eighth: ???
10. ninth: profit

in order to get the same results as before.

I understand that this is likely not a typical use case, but as you can see, such a feature would be helpful to users who tag all bookmarks very rigorously.

An additional or potentially alternate feature would be an API call that allows you to define for an individual tag, a list of bundles it belongs to - either as a replacement for all currently assigned bundles or as an addendum.

--

mkp

tumblr: shamelesslymkp | pinboard: shamelessly_mkp

*she/her/hers

--

[Erik Thauvin]

Looks good, Maciej.

I have a few questions/suggestions though...

First, I noticed that POST /bookmarks/ returns the site_url which seems to contain the bookmark ID, but does not return a separate id item like the other API calls. You probably don't want us to parse the URL to retrieve the ID, if you ever changed the URL format, thrid-party clients would break.

On the subject of IDs, I'm perplexed about them. In v1, you could update/delete a bookmark using its URL. Unless I'm mistaken, in v2, if you don't already have the bookmark ID, you would need to first GET /bookmarks/ to retrieve the ID, then update/delete the bookmark.

Is there really a need to specify IDs since duplicate URLs are not allowed?

Cheers,

E.

[Paul Denning]

https://pinboard.in/api/v2/reference/#auth

shows 401 and 403 for invalid password, pick one.

Paul

[maciej]

This is excellent feedback and I support it in principle. However, I'm also worried about there's a small subset of users that make really expensive calls on the database, which I think is what would happen with complete bundle support.

So rather than design everything up front, I'd like to do this iteratively so I can have a chance to catch bottlenecks and get a sense of what needs optimizing, and then add more support for niche uses.

Ultimately I absolutely want to support full and creative use of bundles (and the other features). And whether a query is 'expensive' or not is not a user problem, but my problem. All of this stuff can be optimized and made fast. But it's just easier to do it stepwise.

So let me keep things as they are right now, and potentially add additional API functionality later.

As for idea #1, mapping https:// to http://, I think it's a good idea but I will have to take a look at the details, which means examining what I have stored already and how the new policy would affect it. There's always exceptions and weird cases and I don't want to break stuff for anyone.

Thanks again for the great feedback!

M

[maciej]

Hey, thanks for the feedback!

As far as the return value for POST /bookmarks/ (or any other call), please ignore the examples right now, they are out of date. The POST call will return both the URL and the bookmark identifier, with only the second guaranteed not to change.

As far as deleting a bookmark when all you have is the URL, that's an excellent point, and one where too much REST-fulness might be silly. 

What I propose to do is add a https://api.pinboard.in/v2/bookmarks/delete call that will works just like its v1 counterpart, with a POST call that takes either a bookmark ID or URL argument. What do you think?

[shamelessly mkp]

As likely one of those subset of users, and as someone who works in cloud computing, I completely understand. I still hope it's a feature you're eventually able to implement, but I can also see how it would be difficult to implement without risking significant service impact to other users.

I also just thought of something that might complicate getting https to also be recognized as http - I know that I, at least, have ended up duplicating a lot of bookmarks because I bookmarked the https url not realizing I'd already bookmarked the http url, and those bookmarks - being made at different times - often have mismatched metadata. That might.. cause problems.

--

mkp

tumblr: shamelesslymkp | pinboard: shamelessly_mkp

*she/her/hers

To view this discussion on the web visit https://groups.google.com/d/msgid/pinboard-dev/3cc9d21a-3730-42b9-9c9c-d0b67396817fn%40googlegroups.com.

[Erik Thauvin]

Hi Maciej. Thanks for the quick response.

On Saturday, May 22, 2021 at 11:57:41 AM UTC-7 maciej wrote:

Hey, thanks for the feedback!

As far as the return value for POST /bookmarks/ (or any other call), please ignore the examples right now, they are out of date. The POST call will return both the URL and the bookmark identifier, with only the second guaranteed not to change.

Perfect.

 

As far as deleting a bookmark when all you have is the URL, that's an excellent point, and one where too much REST-fulness might be silly. 

What I propose to do is add a https://api.pinboard.in/v2/bookmarks/delete call that will works just like its v1 counterpart, with a POST call that takes either a bookmark ID or URL argument. What do you think?

That would work optimally for my library (https://github.com/ethauvin/pinboard-poster). Makes a lot of sense to me.

One other potential ID-related issue that I've been thinking about could occur when trying to add an existing bookmark. Looks like you intend to return a 301 redirect. Will the existing bookmark ID be also included in the JSON error response?

Cheers,

E.

[Kristof Adriaenssens]

Thanks for the update on the v2 API. It looks good.

Someone else said already that the test server mentioned in the documentation is not available. It would be great to get an update in the group when it's available for testing.

I also have a suggestion about test users. It would be great if you could provide a free test user to app builders.

So far I've been paying for an additional pinboard user with the only purpose of getting through the Apple App Store review process for "bookmarker for pinboard" (macOS Safari extension, free of charge).  Of course the test user could be limited in several ways (number of bookmarks,...).

Kristof

Op di 18 mei 2021 om 22:41 schreef maciej <mcegl...@gmail.com>:

--

[Maksim Lin]

Hi Maciej,

Would you have any updates on when the test server with the new API may be available?

Thanks,

Maks.

To view this discussion on the web visit https://groups.google.com/d/msgid/pinboard-dev/CAMcZszV2gm0-umNJZn4vf8UTc_2j3PCFgNKSpuoCiMaNFGtbiw%40mail.gmail.com.

[Paul Denning]

Change the 403 to 401 in the shaded Error Codes table at

https://pinboard.in/api/v2/reference/#auth

--
You received this message because you are subscribed to a topic in the Google Groups "Pinboard" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/pinboard-dev/z1Tp8FZ13xU/unsubscribe.
To unsubscribe from this group and all its topics, send an email to pinboard-dev...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/pinboard-dev/8dbae3bf-f0e0-4b16-b53d-b7f9d755e810n%40googlegroups.com.

[Maksim Lin]

Hi Maciej,

Wanted to ask if there is any news on the new v2 API?

Would you have an idea of when at least the v2 API test server will be
available?

Thanks,
Maks.
----
Maksim Lin
Freelance Android & Flutter Developer
GDG and Flutter Melbourne Co-Organiser, Flutter GDE
www.manichord.com