API Consistency

[David Jacobs]

I love Pinboard and want to rely on it even more than I already have to file and forget all interesting things I find online. I'm starting to look into the API so that I can groom and analyze my previous bookmarks (both for organizational and machine learning purposes). One major blocker I have is that the API is essentially a copy of the one from Delicious and, as such, is not complete or consistent. (I understand that this isn't your fault, Maciej.)

Given that CRUD APIs aren't the most difficult thing to implement, what are the chances of us getting a more consistent v2 API? For example, I'd love a format option on all API endpoints, and to be able to update bookmarks in place (think: sanitize all titles and descriptions, etc.).

Cheers,

David

[maciej]

> Given that CRUD APIs aren't the most difficult thing to implement, what are
> the chances of us getting a more consistent v2 API? For example, I'd love a
> format option on all API endpoints, and to be able to update bookmarks in
> place (think: sanitize all titles and descriptions, etc.).

The chances of getting a v2 API in the near future are not high. My
goal is to expand the current set of API calls to cover features on
the site that right now lack API visibility (notes, tweets, user
settings) and to provide some kind of changeset detection, so that
people don't have to poll /posts/all to update things like iPhone
clients. I believe all this can be done within the scope of the v1
API.

I'm comforted to hear that CRUD APIs are not hard to implement! Every
day I learn something new.

>
> Cheers,
> David

[David Jacobs]

I think you mistook me for being patronizing, which I definitely wasn't trying to be. I guess it's interesting to me that the site is so well done and a pleasure to use until it comes to the API (which I know you didn't design), which I don't think would take too much work to standardize. Anyway, if this happens, or if there's anything I can do to help out, let me know. Pinboard is awesome.

David

[Stephen Darlington]

Hi,

If there’s no v2 API coming soon, then this definitely qualifies as a wish-list item, but I think it’s quite an important one.

Right now if a user puts line breaks in the notes field, the XML sent by the API looks like this:

<post href="http://www.reghardware.com/2012/01/26/iptv_week_netflix_vs_lovefilm_review/" time="2012-01-26T19:47:45Z" description="Netflix vs Lovefilm • reghardware" extended="Some notes.

Some more text." tag="test" hash="ccdab9c273ce6b422b7c9bf9cbec71d6" meta="9c2ae7bd41be4a676dbbf17f8f33e51c" shared="no" />

To be explicit: the return characters are placed directly in the attribute. Unfortunately, according to the XML spec:

“a whitespace character (#x20, #xD, #xA, #x9) is processed by appending #x20 to the normalized value”

(See section 3.3.3, http://www.xml.com/axml/testaxml.htm)

Anyone using a standard XML parser will find the returns converted into spaces. This happens in my iOS client and at least two of my competitors apps (my guess is all of them, but I don’t have a copy of all of them).

I don’t think this can be fixed without breaking the API. I’m no XML expert, but I suspect any field that can have returns in would have to be present as CDATA rather than an attribute?

Cheers,
--> Stephen

> --
> You received this message because you are subscribed to the Google Groups "Pinboard" group.
> To post to this group, send email to pinboa...@googlegroups.com.
> To unsubscribe from this group, send email to pinboard-dev...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/pinboard-dev?hl=en.
>

------------------------------------------------------------------------
Stephen Darlington (www.zx81.org.uk)
"Thesaurus thief let off with reprimand, censure, rebuke, castigation..."
------------------------------------------------------------------------

[maciej]

Ugh, yeah, that's ugly. Just when I think I've run out of reasons to
hate the original Del API.

I'm starting to think that a new API is unavoidable. I'll post a
draft design here for comments in a day or two.

Kind regards,

Maciej

On Jan 29, 4:56 am, Stephen Darlington <step...@zx81.org.uk> wrote:
> Hi,
>
> If there’s no v2 API coming soon, then this definitely qualifies as a wish-list item, but I think it’s quite an important one.
>
> Right now if a user puts line breaks in the notes field, the XML sent by the API looks like this:
>

>   <post href="http://www.reghardware.com/2012/01/26/iptv_week_netflix_vs_lovefilm_r..." time="2012-01-26T19:47:45Z" description="Netflix vs Lovefilm • reghardware" extended="Some notes.

>
> Some more text." tag="test" hash="ccdab9c273ce6b422b7c9bf9cbec71d6" meta="9c2ae7bd41be4a676dbbf17f8f33e51c"  shared="no"  />
>
> To be explicit: the return characters are placed directly in the attribute. Unfortunately, according to the XML spec:
>
> “a whitespace character (#x20, #xD, #xA, #x9) is processed by appending #x20 to the normalized value”
>

> (See section 3.3.3,http://www.xml.com/axml/testaxml.htm)

>
> Anyone using a standard XML parser will find the returns converted into spaces. This happens in my iOS client and at least two of my competitors apps (my guess is all of them, but I don’t have a copy of all of them).
>
> I don’t think this can be fixed without breaking the API. I’m no XML expert, but I suspect any field that can have returns in would have to be present as CDATA rather than an attribute?
>
> Cheers,
> --> Stephen
>
> On 29 Jan 2012, at 02:06, maciej wrote:
>
>
>
>
>
>
>
>
>
>
>
> >> Given that CRUD APIs aren't the most difficult thing to implement, what are
> >> the chances of us getting a more consistent v2 API? For example, I'd love a
> >> format option on all API endpoints, and to be able to update bookmarks in
> >> place (think: sanitize all titles and descriptions, etc.).
>
> > The chances of getting a v2 API in the near future are not high.  My
> > goal is to expand the current set of API calls to cover features on
> > the site that right now lack API visibility (notes, tweets, user
> > settings) and to provide some kind of changeset detection, so that
> > people don't have to poll /posts/all to update things like iPhone
> > clients.   I believe all this can be done within the scope of the v1
> > API.
>
> > I'm comforted to hear that CRUD APIs are not hard to implement!  Every
> > day I learn something new.
>
> >> Cheers,
> >> David
>
> > --
> > You received this message because you are subscribed to the Google Groups "Pinboard" group.
> > To post to this group, send email to pinboa...@googlegroups.com.
> > To unsubscribe from this group, send email to pinboard-dev...@googlegroups.com.

> > For more options, visit this group athttp://groups.google.com/group/pinboard-dev?hl=en.

[Aristotle Pagaltzis]

* Stephen Darlington <ste...@zx81.org.uk> [2012-01-29 14:00]:

> To be explicit: the return characters are placed directly in the
> attribute. Unfortunately, according to the XML spec:
>
> “a whitespace character (#x20, #xD, #xA, #x9) is processed by
> appending #x20 to the normalized value”
>
> (See section 3.3.3, http://www.xml.com/axml/testaxml.htm)
>
> Anyone using a standard XML parser will find the returns converted
> into spaces. This happens in my iOS client and at least two of my
> competitors apps (my guess is all of them, but I don’t have a copy of
> all of them).

Note that this applies only to literal linebreak and tab characters.

The editor of the XML spec Himself has called this broken as designed:
http://golem.ph.utexas.edu/~distler/blog/archives/000564.html#c002306

> I don’t think this can be fixed without breaking the API. I’m no XML
> expert, but I suspect any field that can have returns in would have to
> be present as CDATA rather than an attribute?

It can be done inside the attribute as long as you emit a &#10; NCR in
place of an actual linebreak character.

Regards,
--
Aristotle Pagaltzis // <http://plasmasturm.org/>

[robot pukeko]

Hi Maciej,

I was wondering if the new API you mention is on it's way, or whether you're considering adding additional functionality to the v1 API, as you've also mentioned elsewhere?

It would be great to be able to see when links have been sent to Pinboard from different clients, or pulled from Twitter favourites, for example.

Thanks,

Steve

> > To unsubscribe from this group, send email to pinboard-dev+unsubscribe@googlegroups.com.