What should the Poderopedia API look like?

[Miguel Paz]

Hello everyone:

We are starting to think of what our Poderopedia API must have, do and provide. For starters 

1. We are working on the basic premise that a good API is one that it`s creators use for rolling out improvements and services for their own projects. 

2. The API should be easy to use and must be based on proven standards already approved by the community

3. Here is the information you will be able to extract from Poderopedia

-Basic info of a person, company or institution (basic bio, avatar, industry, country, website, social media)

-News oriented profile

-Hard data sheet of connections (father of, son of, brother of, married with, owner of X company, stock owner of Y company, General Manager of Z company, Board Member of A company, Member of B private club, related to D religious group, financer of E Political Party, Government possitions, relation to think tanks, relation to non profits, etc.)

-Visualization map of those connections

-Documents related to the person, company or institution (we are using Documentcloud`s doc viewer integrated to Poderopedia)

-Sources of information 

All the information above is marked with PoderVocabulary, the controlled vocabulary used as metadata by Poderopedia

Questions and comments:

1. Should we develop a full-service API or different API `s for separate services?

2. HTTP method and RESPONSE format: So far we are leaning to HTTP / GET and RESPONSE / XML and JSON. If you have comments or advice on this topics please send it to the discussion group. We can all benefit from your prior experience and knowledge

3. API`s that we like a lot (for services provided, how they are delivered and the documentation):

-Documentcloud API: http://www.documentcloud.org/help/api

-NYT Articles Search API: http://developer.nytimes.com/docs/article_search_api/
-NYT Semantic API: http://developer.nytimes.com/docs/semantic_api

-NYT Congress API: http://developer.nytimes.com/docs/congress_api

[Poderopedia grupo de discusión / discussion group]

Dan Nguyen from ProPublica just suggested this:

Here's a few good resources:

37Signals "API design for humans" http://37signals.com/svn/posts/3018-api-design-for-humans/

the API docs for Campaign Monitor http://www.campaignmonitor.com/api/account/#getting_countries

Slides form Joshua Bloch of Google, http://lcsd05.cs.tamu.edu/slides/keynote.pdf

I think you'll find the overarching theme is: have great documentation.

Not everyone's a fan of the Twitter API, but their documentation is very well laid out: http://37signals.com/svn/posts/3018-api-design-for-humans/

[Poderopedia grupo de discusión / discussion group]

Travis Swicegood, from Texas Tribune says:

I've been enjoying API: A Strategy Guide from O'Reilly.  I haven't finished it, so I don't know how strongly it finishes.  Might be less practical than you're looking for.  Ben Ramsey has given many talks on REST principles (here's one from a few years ago[2]).  I'd spend some time looking into that.  The new Twitter APIs are RESTful and tend to be much better than their existing one.

To mirror what Dan said, documentation is a big part of an APIs success.  Considering writing at least high-level documentation for your API prior to spending a lot of time implementing it.  The parts you have a hard time explaining or have to spend a lot of time on are parts to consider refactoring.

Also like Dan, I didn't read the whole email -- I just saw that you wanted this discussion somewhere else. :-)

[1]: http://shop.oreilly.com/product/0636920021223.do

[2]: http://files.benramsey.com/talks/2007/phpworks/phpworks07-rest.pdf

[Poderopedia grupo de discusión / discussion group]

_Clément Renaud says:

@all

Thanks for sharing those interesting sources.

I have made a write-up about API design on our research center website, but it still largely to be improved. 

The article is here : http://sharismlab.com/blog/2012/07/21/how-to-write-an-api-for-your-web-app/

All comments are welcome, of course !

cheers

El viernes, 20 de julio de 2012 13:48:50 UTC-4, Miguel Paz escribió:

[Alvaro Graves]

http://www.slideshare.net/jmusser/what-makes-a-great-open-api

Alvaro Graves-Fuenzalida
Web: http://graves.cl - http://ManzanaMecanica.org Twitter: @alvarograves

--
Has recibido este mensaje porque estás suscrito al grupo "Poderopedia grupo de discusión / discussion group" de Grupos de Google.
Para publicar una entrada en este grupo, envía un correo electrónico a poderope...@googlegroups.com.
Para anular tu suscripción a este grupo, envía un correo electrónico a poderopedia-us...@googlegroups.com

Para ver este debate en la Web, visita https://groups.google.com/d/msg/poderopedia-users/-/aZ6__D1WWrEJ.

Para obtener más opciones, visita https://groups.google.com/groups/opt_out.
 
 

[Miguel Paz]

Awesome! 

2012/7/20 Alvaro Graves <alv...@graves.cl>

--

Miguel Paz  @miguelpaz

Poderopedia.com @poderopedia

Irene Ariztía 548, piso 4, Santiago, Chile

t +56 (2) 6397123 m +56 (9) 78535429

[Terry Jones]

Hi Miguel

A few quick comments following your mail to the FOO list:

 - Don't do XML at all to begin with (and preferably not at all). You can add it if people ask for it, but don't be surprised if no one does.

 - Consider using JSONRPC. That way parameters to your calls are in JSON payloads, which can eliminate some issues with encoding and may make the back-end side simpler & more uniform. Downside is that interacting with your API from the command line with curl, wget etc becomes more awkward.

 - In your JSON responses, be careful not to make decisions that will be severely limiting in the future (and which will require compatibility changes or support of multiple API versions where that could be avoided). E.g., if you have a list of results, don't return a JSON list like [ result1, result2, .... ] but instead return { 'results': [result1, result2, ... ] } which is much more future-proof as you can add more fields to the returned object without breaking anything.

I'll comment further if more comes to mind.

Terry Jones

CTO, Fluidinfo

[Miguel Paz]

Thanks Terry

I just saw your Cookbook too.

Great input

[B Lorica]

Hi Miguel,

#foocamp alum and API aggregator, John Musser, founder of ProgrammableWeb has some new slides up, that I thought you may want to scan:  http://www.slideshare.net/jmusser/what-makes-a-great-open-api 

Ben

[Miguel Paz]

Thanks Ben!