Usability - Productivity - Business - The web - Singapore & Twins

Designing a REST API for eMail

Unencumbered by standards designed by committees I'm musing how a REST API would look like.
A REST API consists of 3 parts: the URI (~ URL for browser access), the verb and the payload. Since I'm looking at browser only access, the structured data payload format clearly will be JSON with the prose payload delivered in MIME format. I will worry about calendar and social data later on.
The verbs in REST are defined by the HTTP standard: , PUT, and DELETE. My base url would be and then continue with an additional part. Combined with the 4 horsemen verbs I envision the following action matrix:n/a
/ configuration options and defaults as JSON n/a
(default config exists, doesn’t need to be created)
Update the configuration settings n/a
Get list of folders in systems ?name= create a folder ?name=update folder definition
(e.g. SmartFolders)
?name= delete a folder
/[folders|labels]/[folderName] get the content of the folder put message(s) in folder n/a n/a
/message retrieve message settings create a new message
ID is auto created
update message settings n/a
/message/[messsageId] retrieve the message n/a
(The messages does exist)
Save the message
Interesting question: should that be allowed for incoming messages?
Delete the eMail
/search ?q= search emails given a search query n/a same as get, but with more options using a JSON query structure n/a
/utils retrieve a list of possible actions request a new utility action action n/an/a
Calendar, ToDos and People actions (including address lookups) will follow later on. The vocabulary looks quite simple, so I suspect I might missing something. One of my thoughts: should I give archives a location or would I consider them "a minor detail of the storage architecture" that shouldn't be exposed in the UI.
Stay tuned!

Posted by on 08 August 2014 | Comments (2) | categories: IBM Notes vert.x


  1. posted by Stephan H. Wissel on Wednesday 13 August 2014 AD:
    Yeah, XML is dead like COBOL.
    And throwing away REST and replace it with POST is smart too (Read the definition: POSTING to HTTP, doesn't make your API REST, it is the use of verbs that makes it).

    As long as you write both ends of a web application - you will be fine. Once you have backend systems that need to talk, XML and its schema definition becomes essential. JSON is lacking the distinction between Elements and Attributes and the robustness of Industry schemas.
    So it works nicely between a client and its server.

    Emoticon biggrin.gif stw
  2. posted by Brendon Upson on Wednesday 13 August 2014 AD:
    In a recent project I've taken a much simpler approach. First, I'm not a fan of HTTP verbs I think that for a filesystem they are ok, but some of the things you want to do don't mirror that analogy well, so I just stick with POST.
    Second, I use the same URL endpoint, so everything is posted to /myendpoint
    Finally I put all the "smarts" in the JSON block. eg "action": "getsystemfolders", "data": [], ... Obviously you then need to be a little careful how you grow your JSON api.

    For sure xml is dead. I've always hated that bloated, verbose, restrictive format.

    My 2c.