Designing the WISER APIs

Facilitated by Oz Basarir, WiserEarth

Oz will discuss the purpose and design of the Wiser platform APIs (Application Programmer Interfaces) that enable the Wiser platform to provide services to other web sites.

Session Notes

Oz discussed the story behind the API development at http://www.wiserearth.org/

Wiserearth has a databse of 112000 organization world wide. The site provides a place for smaller orgs especially to establish a web presence.

The API came out of a need to provide the data of Wiserearth to websites that can repurpose the data and present it to their users through a different interface.

The API is a RESTful design, it provides database search, and read access to data for the public. General use would be to search with parameters, and receive a list of organizations. For each organization, you use the read api to fetch org details.

Restrictions

You can't retreive all 112k organizations. The search is limited to (?) max. Emails are never returned, but all other data is available. A person is limited to 100 requests.

Oz discussed the technical details, but see the website instead.

Documentation

The original documentation was not to developers' satisfaction, and this caused Oz a lot of customer support. The lessons learned are to provide the best documention from the start. Have it reviewed by others to avoid assumptions. Base the layout of documentation on familiar, highly regarded APIs like Facebook or Flickr.

Good documentation and support will help grow your developer community. Oz created an online group space for developers at http://www.wiserearth.org/group/API. He finds that holding developer meetings too are well received. Developer contests were discussed as another way to attract more developers.

Write documentation not for yourself, they then had lots of questions, and lots of time spent supporting developers.

Use a wiki for writing documentation

How much documentation do you need?

Virtues of a programmer: Laziness hubris impatience

What to include in documentation going out the door • How to use it • Why to use it o Cases o Potential cases o Clients, line by line code you can take and use (give people confidence that it really works) Consider a section like a FAQ, but FAR(equests)

How do you keep documentation and API changes in sync? o Get more help: product manager, program director o You have to communicate what you’re doing on an ongoing basis o Regular status meetings with both internal an external stakeholders, EDs also want to be on call o Minutes taken and put on wiki, Wiser API dev group, now meeting every 2 weeks

Not only documentation, but also create intelligence about how people use it o Create dashboard o Partially QA responsibility o It it still working o What kind of analytics

Best practices o Ebay API is a mess, overlapping functions o Flickr API is a strong example

Packaging Getting the word out Building community Sharing among internal sites

How to architect Web application frameworks are moving towards connecting data with user in a much more straightforward way Controller is more straight forward, API has a separate set of controllers that control that set of calls

You want to be able to generate XML and Jason output from the same set of actions,

Creating developer communities o Contests are good marketing o Team development might be better at community o Use your developers, integrate their feedback o Seth Godin: make a big announcement, not a little announcement o Contests increase community base o Building and creating a community

Process of his experience building API Process of building

Goals around API? Several nonprofits gathered, requests Community demand