RESTful Web API
(DRAFT)
Basic API
GET / # index. if given "name" as CGI variable, acts just like GET /name
GET /name # read if exists, "new" form if not GET /name?view # read in specified view if exists, "new" form if not. # note: if name is a cardtype, and view is "new", response is form for for new card of that type GET /?new # new card form # note: unlike the other examples, "new" is not a variable. POST / POST /name # create new card PUT / PUT /name # update card DELETE / DELETE /name # delete card (move to trash)
Variants
Names
Cards can be identified in three ways:
- name - default
- codename - begins with ":"
- id - begins with "~"
Names can be given in CGI params or in path. Error if 2 different names are given. Note that if a nonexistent codename or id is given in a normal GET request, response is 404 (not "new")
Formats
You can add ".format" to the end of any requests to specify the response format. (Need to discuss exception handling for various formats)
CGI Variables
Including:
- view args - eg layout, view, item, size, keyword
- action args - (not sure what those are yet)
- model args for PUTS and POSTS - eg name, type, content
Currently those model args come as card[name], card[type], etc. We need to decide if that is still valuable (for example, in separating them from view/action args and how to specify nested cards, which will probably be some variant on that pseudo-hash structure.
Most of this grew out of the discussion at Packs+api+action.
I'm not super comfortable with the handling of #new yet. It solves a number of problems we didn't have worked out before (blank form, backwards compatibility, etc), but treating "name" as the cardtype seems a little awkward.
When there's a ticket for implementing this, link to it from cardedit doesn't create a new card.
--John Abbe.....Mon Mar 07 18:13:10 -0800 2011
Am I getting it right that:
GET /<name>?<view>is shorthand for:
GET /<name>?view=<view>
I get the awkward, as "new" as being treated kind of like a view even though it isn't. Similarly,
GET /Pointer?newis shorthand for
GET /?type=Pointer(Articulated the latter way, "view=new" is assumed if there's no name. If there is a name before the ? then you get that card if it exists and the "type=" is ignore)
Do we care about being backward-compatible here? (I'd definitely prefer yes, but open if there's a good reason not to.) In any case, we probably want to handle everything or nearly everything on web address for everything, yes? Deprecate some old syntax such as /card/new and /new/ ?
--John Abbe.....Tue Mar 08 00:39:45 -0800 2011
I think we will be able to support the old paths with routing modules (optional), so that for Wagns where this is important, they can add these modules or route configuration.
--Gerry Gleason.....Tue Mar 08 11:48:35 -0800 2011
We had a lot of back and forth about this, and I'm actually really happy about the updated way that we're handling views, including "new". It's pretty much a direct mirror of the inclusion syntax / shortcuts:
{{ cardname | viewname }}
GET /cardname?viewname
{{ cardname | view: viewname }}
GET /cardname?view=viewname
"new" actually is already a view, and I think we should support the same meaning in inclusions as we do here.
{{ typename | new }}
GET /typename?new
In the case of the inclusion, it should support an inline new card form.
As for this:
GET /?type=Pointer
That one seems weird to me. If just "GET /" is the index, then it seems like you may want to require an explicit "new" view to get the new card interface. Edge case. Don't feel strongly about supporting it, but definitely do not want to make it a standard.
--Ethan McCutchen.....Tue Mar 08 12:16:23 -0800 2011
The nice thing about the updated API is that there is never a second slash involved, which should make it easier to support the old routing. I agree that it should be optional, but it should probably initially be the default. And we'll want to deprecate it.
--Ethan McCutchen.....Tue Mar 08 12:18:55 -0800 2011
the only thing I see on web address for everything that will need special attention are the tabs.
The first step is to make it so that every tab's content is available as a view of a card. This is already possible for View and Related and mostly there for Edit. The Changes tab could be done with something like a "history" view. The Options tab will be replaced by the Settings tab, which I'm guessing will, like the Related tab, be entirely card-configured.
But having access to the content doesn't necessarily give us access to the tab.
We may end up adding CGI variables (and corresponding inclusion variables?) to address this. But it would be putting the cart before the horse to propose those now, because there were already numerous suggestions for alterations to open view at Wagn Hoe (which I don't want to get into here or now), and there will likely be more coming out of the ui/ux work being done on connectipedia. Once that is solidified, it may make sense to discuss more API variables, but I don't think there will be anything to alter the core API structure.
--Ethan McCutchen.....Tue Mar 08 12:35:10 -0800 2011