request for comments: api/v2

[naveen]

we've been talking internally about v2 of the api for a couple of
weeks now

we're doing a high level pass of things that work well and things we'd
like to see changed. we wanted to share a few of these sooner rather
than later so as to get your feedback

- JSON-only: will be a great way to simplify everything: interface,
testing, documentation, etc.

- OAuth-only: believe it or not, this is how the v1 api started -- and
then we backed off because we saw so much demand for a basic http auth
version. at the very least, how do you guys feel about a two-pass
system (use our auth exchange system to handoff login for oauth
tokens)? that is, all methods except the initial token exchange will
be oauth-enforced. because of the token exchange (which v1 already
supports [1]), your app will not have to do a complicated dance into
and out of a web view if it doesn't want to (or has a technically
difficult time doing so)

- ...?

you've all thrown out great ideas the last few months so i'm really
curious what other things you're thinking about. please follow up in
this thread with any and all comments!

naveen

1. See 'auth exchange' on this page: http://groups.google.com/group/foursquare-api/web/oauth

[Zac Bowling]

The XML lovers will hate the JSON only.

Twitter learned this and still gets an several emails a day to add XML to their search API. :-)

Zac Bowling

--
To post to this group, send email to foursqu...@googlegroups.com

http://groups.google.com/group/foursquare-api

To unsubscribe, reply using "remove me" as the subject.

[Raphael Caixeta]

and the people who don't know how to properly do OAuth will hate the
lack of http auth

On Apr 2, 6:18 pm, Zac Bowling <zbowl...@gmail.com> wrote:
> The XML lovers will hate the JSON only.
>
> Twitter learned this and still gets an several emails a day to add XML to
> their search API. :-)
>
> Zac Bowling
>

[Geoff]

I'm fine with JSON only, but I know others probably won't want to move
away form XML.

I wouldn't hate moving to OAuth, but it'll take a fair amount of
rewriting on my part, just because of how baked-in Basic Auth is right
now.

[Nic Werner]

+1 for JSON-only being ok. Each API I've worked with has had some
different form of JSON or XML and I survived. There are so many
libraries available to parse the HTTP response that this is no longer
an issue.

- Nic

[Abraham Williams]

+1 on both. The less you have to maintain the better it will be and the sooner new awesome stuff gets rolled out.

Abraham

--
To post to this group, send email to foursqu...@googlegroups.com

http://groups.google.com/group/foursquare-api

To unsubscribe, reply using "remove me" as the subject.

--
Abraham Williams | Community Advocate | http://abrah.am
PoseurTech Labs | Projects | http://labs.poseurtech.com
This email is: [ ] shareable [x] ask first [ ] private.

[Christopher Burris]

JSON only means that I'd have to largely have rewrite my entire app (python based using xml.dom.minidom - which is fine if v2 brings some cool goodies... ) Since nobody is paying me to maintain barriosquare you could see that I'd rather be drinking than converting code to JSON instead of XML.

I'm cool with OAuth only as that's how my app works now...

Is there a trend for RESTful APIs to going to JSON instead of XML?

I just groan on having to convert the entire thing (it's selfish, I know..)

... will you support mix-match of API versions? So we can continue using the old xml versions but code in JSON for new API features?

[TJ]

-2; my app is http auth & XML, and i'm not sure JSON will work
properly on dumbphone mobile webs

|tj

[TJ]

oh, nevermind about the dumbphone part. my understanding was a bit
different than reality.

i guess i wouldn't mind; i learned a bunch of stuff in order to write
my app with XML, so JSON won't kill me. if this means we get access
to things like leaderboard & city changes i'm in. i hope both
versions will be supported in parallel for a few weeks?

[sabernar]

-2

JSON wasn't reliable for v1 (malformations would cause parsers to crap
out), so early on we had to switch to XML. You're forcing everyone
who used XML and basic auth to rewrite everything. Any custom APIs
that people developed will have to be completely rewritten.
Personally, I think that if you're going to completely ditch half the
API, we should have more notice. I don't know when you're planning to
come out with v2, but wouldn't it be normal to deprecate those things
for v2 and then ditch them completely in v3?

-S

[Brian Papa]

My vote is for progress. The Foursquare team's time would be wasted on supporting old stuff or options that would make only 20% of developers happy. Make cool new stuff and make 80% of developers happy instead. :) Every platform has API options for JSON and OAuth (aren't some even Foursquare-specific?) so it shouldn't be that hard for devs to incorporate.

Do JSON only and OAuth only for /v2. Continue to keep the lights on for /v1 for some amount of time, maybe a year. If apps pointing to /v1 can't upgraded in a year's time, then to be honest I wonder how interesting such a rarely upgraded app would be in the first place. To be nice, track which apps continue to hit /v1 stuff that's deprecated, and reach out to those devs outside of the mailing list.

Other thing I'd like to see, and this is just silly and doesn't have much to do with /v2, but it'd be super handy if the API doc page had an alphabetized list of links to anchors on the page. I always either get lost scrolling or fail to command + F through because I forget the exact method name.

[Christopher Burris]

As part of v2 I'd like to see push-type notification to allow other non-iphone apps and api consumers to get notified when friends checkin, etc. :-)

Sure, come up with a clear migration path to a v2 which supports JSON only, keep the lights on v1 for at least a year - don't alienate those developers who have invested the time since the beginning with foursquare.

[Abraham Williams]

If your application requires a huge amount of work to switch from XML to JSON you are doing something wrong. You should be able to switch out your parser, modify you code to work with the new parser and be good to go. 

Abraham

[Christopher Burris]

Yeah, I'm probably doing something wrong. My app was a kludge to fill a void and then I hacked more functionality on to it... so yeah... probably doing something wrong. :-)

[Abraham Williams]

Rofl! Well at least you are honest about it :-P

[Jeremy Kelley]

Late to the conversation, but consider this another +1 for JSON.

As for OAUTH, I'm ambivalent.  Right now, we're using basic auth for Kingpin, but OAUTH has been on our todo since the beginning so we'll be finishing up that functionality ... eventually.  I spent a couple of hours last week adding sniper shots, instead.  That seemed more important to the gameplay.

I think a lot of folks will feel about OAUTH like I do.  If I have to talk it to access the API, I will.  Otherwise, I'll probably spend my efforts adding features.

-j

Jeremy Kelley <jer...@phodder.com> cell: 979.820.8202
CEO, Co-Founder of Phodder
Makers of Mobile Applications and Solvers of Interesting Problems

[wubbahed]

+1 on a method to allow us to register callbacks related to checkins.
(either for an individual or for a place)

[TC]

+1 for JSON.

I'll also take this opportunity to formally request venue name
matching to register "real" checkins, instead of generic checkins when
there is no Venue ID. Instead, if Venue ID is null, require city be
passed in to avoid false positives in your matching.

[Will Carter]

I totally agree with everything brian said.

Sent from my iPhone mobile device

[Danny Pier]

Currently doing XML... but JSON won't kill me.

In fact, I'd gladly sacrifice XML for a retrievable association
between badges and a checkin id :)

-dp

[TAKEUCHI POMU]

Hi naveen,

> - JSON-only

+0: I prefer xml, but it's not a big issue.

> - OAuth-only

+1: Considering security, its better to deprecate basic auth.

> - ...?

- I strongly want new API to support these...
- registering new account
- retrieving shorten url like "http://4sq.com/5ojxJ0" from venue id
- retrieving count of "YOUR VISITS" displayed in venue page
- retrieving data for "STATS" displayed in
http://foursquare.com/stats/$username

Regards,

Pomu TAKEUCHI

2010/4/3 naveen <nave...@gmail.com>:

[roderic]

I agree with Takeuchi Pomu. If you are using basic auth to get your
oauth keys then you seem to be giving up a bit in your security
policy. One of the great things about oauth is that you only give you
password to 4sq and NOT "joe blow's client". I'm against basic in that
sense.

However, I haven't inserted my oauth flow in my client yet so I'm sure
I'll be loving basic in about 2 days.

Still +1 for oauth.

And I agree with what Abraham was saying. If you have to rewrite your
whole app because of the network messaging protocol you may need to
abstract some of that out a bit more.

+1 for JSON

On Apr 3, 9:26 am, TAKEUCHI POMU <pomu0...@gmail.com> wrote:
> Hi naveen,
>
> > - JSON-only
>
> +0: I prefer xml, but it's not a big issue.
>
> > - OAuth-only
>
> +1: Considering security, its better to deprecate basic auth.
>
> > - ...?
>
> - I strongly want new API to support these...
>  - registering new account
>  - retrieving shorten url like "http://4sq.com/5ojxJ0" from venue id
>  - retrieving count of "YOUR VISITS" displayed in venue page

>  - retrieving data for "STATS" displayed inhttp://foursquare.com/stats/$username
>
> Regards,
>
> Pomu TAKEUCHI
>
> 2010/4/3 naveen <naveen...@gmail.com>:

[DanielR]

Two thoughts:

1. OAuth. Right now I'm developing an proof-of-concept using the HTTP
Basic Auth. This allows me to explore my app idea without having to
register for an OAuth token (which I plan to do once I finish).
Removing the Basic Auth would add overhead to starting a new
Foursquare app.

2. Friends' tips. Given an ID of one of my friend's, I want to be able
to see all of their tips. Essentially, I have friends whose tastes I
trust, and I want to 'follow' them to know whenever they find a new
place to check out. This is kinda Twitter-like but with the location
of the venue built into the app already.

3. Filter nearby tips by friends. FourSquare as it stands now gathers
tips for each venue, but I want to see only the ones from my friends.
I suppose I could still do this in software if you don't think this is
a good idea.

I'm pretty excited about numbers 2) and 3). Feel free to contact me if
you would like to chat more about them. : )

-- Daniel

[Dave Ingram]

On 02/04/10 23:14, naveen wrote:
> we've been talking internally about v2 of the api for a couple of
> weeks now
>
> we're doing a high level pass of things that work well and things we'd
> like to see changed. we wanted to share a few of these sooner rather
> than later so as to get your feedback
>
> - JSON-only: will be a great way to simplify everything: interface,
> testing, documentation, etc.
>

Definite +1

> - OAuth-only: believe it or not, this is how the v1 api started -- and
> then we backed off because we saw so much demand for a basic http auth
> version. at the very least, how do you guys feel about a two-pass
> system (use our auth exchange system to handoff login for oauth
> tokens)? that is, all methods except the initial token exchange will
> be oauth-enforced. because of the token exchange (which v1 already
> supports [1]), your app will not have to do a complicated dance into
> and out of a web view if it doesn't want to (or has a technically
> difficult time doing so)
>

+1 for not handing over login details, +� for exchanging user details
for oauth tokens as a necessary evil.

> - ...?
>
One of the things I'd love is a mass venue-fetching API method -- once a
user starts using my service, the first thing we do is fetch a list of
all of the venues they have visited. This can very very quickly eat
through the API ratelimit, and isn't very friendly. Being able to
specify a list of venue IDs that I want information for would be
fantastic, e.g. /venue_batch?vids=123,456,789,12313

In fact, some sort of general batching API could be very handy, for any
time we want to fetch a lot of data at once (e.g. venue info or user
info). I can't think of any other examples at the moment (e.g. check-in
history is already paged) but I'm sure there may be others.

Dave

[Tim]

In addition to the discussions on OAuth and XML, I have various other
comments.

- JSON and ID numbers -
I do wonder however why you must cast your id numbers to integers. PHP
(and no doubt other languages) cope badly with large integers and
unless I really need to perform arithmetic on these numbers, I will
keep them as strings. Of course the json_decode function in PHP will
cast BIGINTs to floating points and introduce potential problems. The
fix I have been using for the Twitter API is to string-replace each
JSON response before decoding (an unnecessary overhead) I can't think
of many cases for performing arithmetic on user and venue IDs, so it
would help a lot of IDs were cast as strings in your JSON responses. -
yes it would add two bytes per value, but would make me and many other
developers happy, I'm sure.

- JSONP -
Do you have any plans to support a JSONP callback parameter and
support some unauthenticated queries? This will open up the API to a
whole other world of front end developers relying on cross-domain
JavaScript techniques.

- Friend email addresses -
I think you may come under fire for this at some point. "Showing my
email to friends" also appears to mean "show my email to authenticated
apps". Either you need to either state this more clearly to the
public, or introduce a finer-grained privilege system like Facebook,
or remove this field from the feeds.

- Feature request - Lists -
For the app I'm developing I need to get checkins from a subset of
venues by a subset of people. There appears no easy way to make this
awkward intersection, other than grab lots of data and filter it
myself. I'd love to see the Foursquare equivalent of Twitter lists, or
perhaps just more extensible query methods for grabbing more flexible
data sets.

Keep up the great work.

[janole]

I'm using JSON in my client, so I wouldn't mind dumping XML ;-)

But please keep Basic Auth for v2. It makes the whole process of
developing a client so much easier and leaner. If you offer a username/
password based token exchange, the whole idea of OAuth (not disclosing
your password) is void anyways, isn't it?

I've been implementing most parts of OAuth myself for my Twitter
client Gravity, because there are no libs available for the Symbian
platform. The benefit of this is that you actually see the overhead
necessary for each & every API call - and that does matter on a mobile
platform.

Ole

--
Jan Ole Suhr
su...@mobileways.de
On Twitter: http://twitter.com/janole

[Jeremy Kelley]

API v2 request - the ability to create new users

I know you want to guard this functionality to minimize bogus
accounts, but when writing a foursquare client, it would be very nice
to be able to do this in the client w/o having to load the foursquare
website.

I imagine it could be a multi-step process of submitting the proper
information, replying back with a URL to a captcha and then submitting
a session token and the user's captcha input.

-j

> --
> To post to this group, send email to foursqu...@googlegroups.com
>
> http://groups.google.com/group/foursquare-api
>
> To unsubscribe, reply using "remove me" as the subject.
>

--

[Niels van der Rest]

- JSON-only:
With the right abstractions, it shouldn't be too much effort to
maintain a codebase that can output both JSON and XML. I'm working on
(and with) an API that supports both JSON and XML, and the most time-
consuming part is updating documentation, since you'll need to provide
sample output for both formats :)

But JSON is easier to use in Javascript clients and there are plenty
of libraries nowadays to parse JSON in a non-browser environment. So I
wouldn't mind if v2 is JSON only.

- OAuth only:
Shouldn't cause too many problems for people to implement and provides
better security for the end user. So this is a definite yes!

- Query for UID:
Currently I'm working in a scenario where I often only know the user's
Twitter name as seen in the user's profile page URL, and the API only
supports the UID parameter for most methods. So I'd like to see
something simple like /v2/uid?q=twittername which returns only the
corresponding UID for that Twitter name. I've seen similar requests in
other topics, but I couldn't determine if this feature is planned for
v2, so that's why I'm suggesting it here.

Although I have yet to start using the API, it looks pretty solid and
complete, judging from the documentation. Unlike some other API's I've
worked with ;)

Keep up the good work!

Niels

[naveen]

thank you for all your great comments over the last week!

a few notes:

+ when v2 comes out, v1 will still continue being active for a while.
we won't turn it off immediately -- we're not that mean :)

+ definitely thinking about push and callbacks

+ it's true the auth-exchange from basic to oauth is not a purely
secure model, but it'll give some clients (especially mobile) the
ability to use oauth without having to do the complicated jump-to-
browser-and-then-back-again

+ and https for this, yes.

+ to reiterate a point from an earlier thread: IDs will be strings
(not integers)

all other points and requests have been noted and are on the list!

[elstudio]

Super!

+1 for JSON-only
+1 for OAuth-only

+ Opening up tagging by the API. Add tags to a venue. Pretty please!

+ Opening up category edit to the API -- add a venue to a new
category. Or just add category option to proposeedit.

+ How about returning the same OAuth tokens on repeat logins -- much
the way that Twitter login works? That will make it possible to find a
user by OAuth token on the app side. And on the Foursquare side it
prevents that long list of apps that have requested credentials. You'd
get one entry per app, not one entry per login like we have now.

[rakf1]

JSONP callback parameter please.

[Dave Ingram]

On 04/02/10 23:14, naveen wrote:
> we've been talking internally about v2 of the api for a couple of
> weeks now
>

> ...
>
> - ...?
>

Another feature request or two:

- "Last updated" timestamp for venues, which may be returned when
checking in (so apps that behave and cache venue data know if/when they
should update their cache)
- Some way of finding out about venue merges via the API... maybe
return a 302 to the new venue (e.g.
http://api.foursquare.com/v2/venues?vid=456) and/or a response body just
containing a "merged" key with the new ID (e.g. {"merged": 456}).

Dave

[Naveen Ayyagari]

+1 on the Last updated for venues to facilitate caching

An extension to that is last_updated for user objects for the same caching reasons. (i.e. contact info,badges, mayorships can be cached)

I guess ill also chime in and say OAuth only is fine with me; as is JSON only. JSON is a little hard on J2ME(BlackBerry) as there are not a lot of mature JSON parsers available, but its workable.

--Naveen Ayyagari (Not Foursquare naveen)
@knight9
@SocialScope

[Mike Yassa]

I've just started a very small trend analysis project, calling the /
venues method with a number of set geocoordinates every hour. One
thing that would be very useful is being able to return only venues
that have the herenow property greater than zero. Is there already a
better way to get this information?

Thanks,

Mike

On Apr 3, 12:14 am, naveen <naveen...@gmail.com> wrote:
> we've been talking internally about v2 of the api for a couple of
> weeks now
>

[Lepton]

I dunno about OAuth only. I am not sure OAuth is a great system, for
example, in "auth exchange', you say:

"We provide this mechanism under the assumption that if a user has
installed your application on their hardware they, trust it enough to
pass through their authentication information to foursquare. Please
do not use this mechanism for a web application."

That's the thing. The user us giving the password to the app,
therefore the main thing about OAuth - keeping the password from the
app and only giving it to FourSquare - is defeated. There is still the
advantage of not permanently storing the password in the device, but
the authorization is still in the device, by that I mean a person who
stole the phone can still do authorized things.

I don't see OAuth as bad, but isn't it a lot of work for no real
benefit over basic auth, at least in mobile devices.