An API (Application Programming Interface) consists of a set of callable methods. On the Web this means tipically you can access information and methods directly calling a certain URL. A very good API from which we could take inspiration is the Flickr API. The Flickr API provides a bunch of very useful methods (such as flickr.activity.userComments, flickr.activity.userPhotos, flickr.contacts.getPublicList, flickr.groups.browse, flickr.people.findByUsername, flickr.people.getPublicGroups, flickr.photos.geo.getLocation, flickr.photosets.comments.getList, see complete list) and we could provide similar methods.

Why do we need an API for CS ?

An API exposes some callable methods. With these methods, independent services can request to obtain informations and do something with it. In general, API expose information for consumption (ex: fetch your photos and display them wherever and however you want), but sometimes can also gives methods to directly change stored information (ex: change my mission text) but this is much more rare and in general this is not useful, nor used.

CS is a no-profit association so it does not profit from excluding other services from information, like for instance ebay does (see eBay files suit against auction site Bidder's Edge which was copying all ebay profiles and setting up a similar services bootstrapping its network with ebay users). Anyway there are evident copyright issues here as well. For instance the photo a CS member has uploaded is not intended for external use, surely it is not possible for a company to print it and sell it or run a commercial with it. Same for text users insert on CS web site. So, unless a new content licence (like creative commons) is adopted, all content on CS should be considered as "all rights reserved". This probably sucks but it is the default copyright of everything you find on the Web.

correct me if I'm wrong --Phauly 15:07, 13 March 2007 (EDT)

An API can be very useful to the CS project on several points :

• Users that have no admin rights can use the API to implement some features they would like to see in CS, without compromising integrity of the site or its DB, and implementing a proof-of-concept demo, testing it etc. before submitting the code to administrators.

• A lot a websites succeeded cause it provided a good API, some examples are Wordpress, Flickr, Google Maps etc. Providing an API can lead a lot of people to develop some code useful to CS (directly or not), for example someone could code some wordpress widget to display his list of CS friends, etc. It will lead to some improvements we cannot even imagine!

• Similar to preceding point, but more powerful, a good API can lead to external project to make mashup (examples) with CS stuff in it. Imagine a blog travel where you can create geotagged post about your travel steps, with your flickr photos, and your CS host. It is possible, it's already done by some website, except of course for the CS part, but with an API, it will be possible!

Issues

Server loads. It is of fundamental importance to limit the number of calls a user can make per minute (or at least monitor them at the beginning). With an API it is extremely easy to, for istance, write a program that every second asks the list of all my friends. Such a program will be able to put the serve on its knees. All API providers (Flickr, Google Maps, ...) provide a limit to the amount of calls you can make per minute (or day). All of them asks you to get a unique key to make your calls so that it is possible to know which users is making the calls and monitor the number of calls.

API

Informal needs

What information can we provide? What needs does an external developer have?

Individual purposes (for a given user)

• List of my CS friends
• All informations on my relation ship with a given friend (level, CS/travel/Surfing days, etc.)
• List of references i've written
• List of references about me
• List of coutries i lived in / i travelled / i want to go / i'm going
• List of languages i talk (with skills)
• List of friends of friends (with level as criteria)

Searching purposes

It will be very powerful to provide a way for external websites to implement a search of CS users.

Others purposes

• List of people who speak a language at a certain skill level.
• List of people who visited / lived / want to go / are going to a given country.
• A random CS user with criteria (country or language)
• Relationship and references between two CS users

API Specification

The best way to provide an API is through REST. In a nutshell it means that methods are called directly with HTTP calls of URLs. Examples can be found on Flickr API. For example calling this URL http://api.flickr.com/services/rest/?method=flickr.contacts.getPublicList&api_key=cd227ee972c49005a7a539fee08d6ccd&user_id=12037949754%40N01 you get this XML

 <rsp stat="ok">
	<contacts page="1" pages="1" per_page="1000" perpage="1000" total="278">
        <contact nsid="36521960554@N01" username="/nico" iconserver="1" iconfarm="1" ignored="0"/>
        <contact nsid="59501100@N00" username="27" iconserver="1" iconfarm="1" ignored="0"/>
        ....

which is a list of contacts of user beej whose user_id is 12037949754%40N01) expressed in XML. REST make API methods easy to call. They usually return plain XML so that the result is easy to parse and integrate in your own application or site. You can experience with more Flickr API calls at http://www.flickr.com/services/api/explore/

Examples for inspiration

FaceBook API http://developers.facebook.com/ The Facebook Platform allows you to add social context to your app utilizing the following data from Facebook: Profiles Friends Photos Events

For instance someone coded a Ridesurf application usable with Facebook logins since it leverages the facebook API, called Zimride http://www.mashable.com/2007/04/15/zimride/

Example of some Mashup or integration that can be created with a good API

It can be external websites, affiliated or not with CS, or new features for CS website (in this case, there is no need of the API, hack the DB directly) :

• A site to select people who talk a language i want to learn, and want to learn a language i talk
• A site to describe CS experiences, with a map that show travels with blog and pics, and CS host
• A feature to discover or contact a person who know someone who know too
• A blog/site widget which shows how friends you have made with CS, how many times you have hosted and be guest