[WIP] API Update

[pascalfree]

Hi,

It seems, that the Semantic Scuttle API is not up to date with the current delicious API. Some new features (like hashes) are especially useful for client synchronisation.
With this pull request I want to update the API to be fully compatible with delicious again. It is not finished, but I want to share the progress to allow early feedback.

Status:
So far, these API functions have been updated:

• all new arguments of posts/all, including ?hashes
• All changes in posts/get. See comment below

Differences:
This is a list of functions, which are not fully implemented, because I'm unsure, whether they are usefull:

• Delicious limits the total possible number of bookmarks returned by ´posts/all´ to 100000. I did not implement any limit.

Compatibility:
The changes in the API are mostly backward compatible, as new features are added. I will list the incompatibilities here:

1. Default Limit: By default only 1000 Bookmarks are returned with posts/all. Clients expecting all bookmarks to be returned will not show all Bookmarks (if there are >1000).
2. Empty results in posts/all: An empty result (no bookmarks) now returns <result code="no bookmarks"/> instead of an empty <posts>-tag.
3. In posts/get default date has changed and UTC is used instead of server timezone
4. In posts/get the dt in posts attribute does not contain the time anymore (just the date)

About the XML header:
In delicious the header of the response is <?xml version="1.0" encoding="UTF-8" ?>
In semantic scuttle it is <?xml version="1.0" standalone="yes" ?>
I'm not sure if this is intended or even important. However, I used the header of delicious here.

Cheers,
David

[pascalfree]

Hi,

I've now tested most of the API functions. The delicious API docs are not always consistent with the implemented delicious API itself. This is an overview of what I found:

posts/update

Description	API docs	delicious	semantic scuttle
Response for empty inbox	inboxnew="0"	inboxnew=""	inboxnew="0"
Undocumented attributes in response	-	code="200" message="success"	-

posts/delete

Description	API docs	delicious	semantic scuttle
delete by md5 hash	not documented	?md5=...	not implemented
error response	-	<result code="The url or md5 could not be found."/>	<result code="item not found"/>
response if no parameter is given	-	<result code="url or md5 required"/>	<result code="something went wrong"/>

posts/all

Description	API docs	delicious	semantic scuttle
privacy status	not documented	redundant: private="no" shared="yes"	not compatible
empty attributes	is ommited in example	extended=""	ommited

posts/add

Description	API docs	delicious	semantic scuttle
tag separation	comma	comma	space
Description argument	required	optional	required
missing url argument response	-	<result code="error adding link"/>	<result code="URL missing"/>
link exists response	-	<result code="item already exists"/>	<result code="bookmark does already exist"/>
change date: replace=yes&dt=...	-	no effect	changes date
replace without setting date: replace=yes	-	keep original date	replaces date of creation with

posts/get [Done]

implemented versions are bold

Description	API docs	delicious	semantic scuttle
default date	"most recent"	Today, starting UTC midnight (excluding midnight)	Today starting now (not usefull)
url and hashes argument	yes	yes	not implemented
allow multiple tags (space-sep., logical AND)	yes	yes	not implemented
argument &meta=yes	yes	yes	not implemented
attribute tag_separator=comma	yes	yes
others attribute in response	yes in example	no	yes
format of dt attribute in <posts>	2014-05-31	2014-05-31	2014-05-31T12:11:00Z
additional keys in attributes of <posts>	none	bookmark_key="some_hash" inbox_key="some_other_hash" network_key="more_hash"	none
privacy status	not documented	redundant: private="no" shared="yes"	not compatible

posts/recent

Description	API docs	delicious	semantic scuttle
privacy status	not documented	redundant: private="no" shared="yes"	not compatible

posts/dates

Description	API docs	delicious	semantic scuttle
tag(s) attr. in <dates>	tag=	tags=	tag=

Other functions

posts/public

This function does not exist anymore in delicious (and docs)

posts/suggestion

Not implemented in semantic scuttle

tags/get

semantic scuttle returns tags with underline _ instead of spaces

tags/rename

Seems broken in delicious. Semantic scuttle works according to docs

tags/delete

Seems broken in delicious. Not implemented in semantic scuttle

What now?

Many of the changes would not be backward compatible. So I think it would be best to offer the new API at a different location (e.g. api/v1/) and leave the original API unchanged for existing clients.

Also I will inform delicious about the differences between their documentation and their implementation that I've found.

EDIT: The timezones don't seem to be a problem at all. Everything is stored in UTC. I removed the corresponding lines from the problem and will undo my "fixes".