support RESTful Web API

Ticket

support RESTful Web API+status
support RESTful Web API+priority
support RESTful Web API+tag
support RESTful Web API+commit
 

 

support RESTful Web API+solution

Outlined here:

 

Mapping REST to Decko is quite simple, because Decko only has one type of resource: the card.  The API maps standard REST actions to standard card actions in a straightforward way.

 

Learn more about REST (Representation State Transfer). 

 
 

 

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=edit # read in specified view if exists, "new" form if not. GET /?view=new # new card form 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:

 

  1. name - default
  2. codename - begins with ":"
  3. 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 extension>" to the end of any requests to specify the response file format.

 

CGI Variables

Including:

 

  1. view args - eg layout, view, item, size, keyword
  2. action args - (not sure what those are yet)
  3. 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.

 

GET Variants

 

POST /name -> GET /create/name
PUT /name -> GET /update/name
DELETE /name -> GET /delete/name
# and, for consistency...
GET /name -> GET /read/name

 

 

 

 

I guess there are two remaining questions:

 

1. do we infer new card view from ?type=X

2. should the new view of a type card be the new view of an instance of that type.

 

At the moment, both seem a bit hacky to me, and indeed would require minor code hacks, because they don't fit our current patterns. In general we use new view when (a) explicitly told to, or (b) going to a card with a name we don't recognize. Seems clean to keep it that way. #2 seems to introduce a class/instance confusion we don't have elsewhere.

 

I don't feel super strongly about this and I may have leaned a different way before, but now that the code is cleaner, I'm more resistant to hacks than ever.

--Ethan McCutchen.....2013-09-15 21:14:23 +0000

 

 

 

 

 


Not a lot of spec here, but most of the support and plumbing for this exists and works. Recently split off to a branch for lack of complete specifications. On branch json_xml

  --Gerry Gleason.....2013-03-02 12:25:31 +0000


I think we have the core of this API working now, at least in the HTML realm. There is a good bit of work to be done in other formats, but I think we should track those in other tickets, eg, improve JSON rendering

--Ethan McCutchen.....2013-04-25 16:41:42 +0000