[UFO Chicago] Creating an api for an exsisting project

[Brian Sobolak]

Jeremiah Benham wrote:
> I found this project I am interested in. It does not yet have an api. We
> want to create an api to load plugins and expand functionality and allow
> users to define what plugins or how much bloat they want with it. Its
> entirely written in c and is a GTK+ frontend to lilypond. Its kind of
> like what LyX is to LaTeX. I know some of you would say just use $EDITOR.
> I can very well do that. The thing is I am thinking of other people that
> are frightened to try out *nix because it does not have a things like a
> musical score editor.  While it does have lilypond and many other
> typesetting programs based off of LaTeX most musicians have it set in
> their mind that score editing should be like $PROPRIETARY_EDITOR.
>
> So what books or websites would you guys recomend? I did some google
> searching but will probably just end up looking at some other project
> and see how they did it and then do it in a similar fashion I guess.
>

Most excellent that you are making a contribution by scratching an itch
you have.

Is the idea that with a proper plug-in framework, others can write
$PROPRIETARYEDITOR?  Or is the goal to make it easier for yourselves to
write an editor, but it won't be proprietary since it's written against an
API?  Or??? I guess beyond the API, I don't see what the goal is for the
project.

I think Python would do a good job as an API language, esp. since it plays
nice with C.  It's a pretty decent language to work in too, and has a lot
of support in Chicago if you get stumped.

As for API design, I think pretty much any API except one you design is
going to suck.  Using someone else's API almost always makes you think
"huh?" a minimum of 3-4 times.  It makes the best sense to the person who
wrote it, and declining levels of sense to everyone else.

Here are a few things to think about (imho):

1) Big or small?  I think proprietary companies tend to aim for the "BIG"
side of of things.  If you've ever worked with Office VBA or Java you know
what I mean - there are 15 methods for just about everything.  Small might
be HTTP, which has a very small and incredibly flexible API through GET
and POST frameworks.

2) Function vs object?  I find most object-oriented APIs to be tough to
learn because you have to hard-wire your brain around a hierarchy.  If you
have a set of functions, you can pick and choose the order for yourself.

3) If you have to do any data formatting, XML is all the rage these days. 
Tread carefully.  I've seen so many examples of programmers building
useless "flexibility" into XML that have later turned out to be serious
problems.

4) Yes, but can you dance to it?

5) Spend as much time on the documentation on the API as you do on the API
itself.  The Office API, has reams of documentation that tells you nothing
about what you need to know.  A lot of API users are perfectly happy with
cut and paste solutions from the documentation, and it will greatly
improve the chances of your product being successful.

I don't remember seeing articles discussing API writing outside of
snore-ville articles in Dr. Dobbs.  This is an interesting essay though
that probably won't give you a lot of answers, but is worth reading
anyway:
<http://www.paulgraham.com/hundred.html>

Of course, this would be a great thing to talk about Thursday if you can
make it. :-)

brian

--
Brian Sobolak
http://www.planetshwoop.com/