RESTful API Resources

Justin Clift jclift at redhat.com
Mon Nov 12 10:21:37 UTC 2012


On 10/11/2012, at 1:42 AM, Jason Guiditta wrote:
<snip>
> I am not convinced 'access the api from a web browser' is much of a
> use case for an api.  The api really is primarily geared toward being
> consumed by machines/software.  Can you tell me, aside from perhaps
> developer testing, why we would use the api from a web browser?

It opens up options for developer education and documentation.

People can write lowest-barrier-to-entry docs for stepping newbies
through things, which they can follow along just by using their
browser:

  To do foo
  *********

    1. First you need to register your new foo.

         http://www.example.org/api/1/foo/register  <-- clickable link


    2. Then you need to set the details of it

         http://www.example.org/api/1/foo/list   <-- clickable link
         http://www.example.org/api/1/foo/x/set  <-- use link from list

    3. Launch your foo

         http://www.example.org/api/1/foo/list   <-- clickable link
         http://www.example.org/api/1/foo/x/launch  <-- use link from list

Of course they'll also do it properly from code too, but there is
definitely value in giving lowest barrier to entry options, if it's an
easy thing to do.

(if it's a pita though, it's likely not worth it) ;)


> Opinion on that aside, I would also say we could easily support _both_
> if we felt there was a real need for the second case, with no change
> to the api itself.  One way to implement this would be to have the
> controller continue to use the content type, but have a middleware
> dropped in from of the app that would set that content type based on
> its presence or absence.  If absent, then extract the version from the
> url, should be pretty simple.  Routes file just gets an alias (or a
> few) as needed.

Yeah.  "easily" is kind of what I was hoping for. ;)

+ Justin

> -j

--
Aeolus Community Manager
http://www.aeolusproject.org




More information about the aeolus-devel mailing list