[Discuss] api? rest maybe?

[warlord at MIT.EDU (Derek Atkins)]

"Daniel C." <dcrookston at gmail.com> writes:

> On Wed, May 22, 2013 at 2:41 PM, Eric Chadbourne
> <eric.chadbourne at gmail.com> wrote:
>> Hi All,
>>
>> I've written a little web application and a friend of mine has asked for an
>> api.  I don't know much about this subject though rest looks understandable.
>> Any suggestions for something to read?  All clues welcome.
>
> REST should be fine.  I may be old school, but I personally would
> consider implementing a REST API to be "making it fancy".  When I
> write one-off web apps and I want to add an API, I just publicly
> expose some of the functionality (with proper security measures in
> place, of course) via a page that expects a POST and which returns
> some formatted text.  For example if I want an API for a personal
> finance "app" (fancy word for a mish-mash of scripts) I might have the
> following "API calls" (really just web pages that are more
> programmer-friendly):
>
> - login.php: post credentials to this to get authenticated
> - transaction.php: you can POST to this with a couple of fields that
> define the transaction amount, a short description and optionally a
> category.  It prints out a simple success or failure message.
> - balance.php: GET only, returns your current balance as an integer in text form
>
> If I'm already using these filenames for the "normal" UI then I might
> prepend them with api_.

I'm not sure why you consider REST to be fancy?  IMHO REST itself is
pretty old school; it's been around as an architecture for more than a
decade.  The concept is that you have an object-oriented model for
manipulation of data.

Depending on your application you might consider a RESTful CRUD model
(Create Read Update Delete).  As an example, Ruby on Rails by convention
uses CRUD+REST for both APIs and Human/WebPage interaction.

For the personal finance app idea, I'd ask you "when you want to get the
balance, what are you getting the balance of?"  Your current example
assumes you only have a single account, but most people have multiple
accounts.  A restful way of doing that would be to have a GET on
/account/<accountID>/balance that would return the balance for the
specified account.  Or you could just do GET /account/<accountID> to get
all the account attributes, of which balance would be one of them.

> -Dan

-derek
-- 
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       warlord at MIT.EDU                        PGP key available