wissel.net

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

Make your own mail client

This article is part of a mini series. Read them all:

  1. Adventures with vert.x, 64Bit and the IBM Notes client
  2. Running vert.x with the OpenNTF Domino API
  3. Designing a REST API for eMail
  4. Rendering a Notes view as JSON REST service - on your client
  5. Put an angular face on your inbox
  6. Poking around the iNotes HTTP API (Part 1)
  7. Poking around the iNotes HTTP API (Part 2) - Fun with Rhino
  8. Poking around the iNotes HTTP API (Part 3) - retrieve message meta data
  9. Mail archive with Apache CouchDB / IBM Cloudant - Part 1
  10. Disecting a mail UI
  11. Vert.x and Domino

Designing a REST API for eMail

Hero image for 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
URI GET PUT POST DELETE
/ configuration options and defaults as JSON n/a
(default config exists, doesn’t need to be created)		 Update the configuration settings n/a
/folders
/labels		 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 2 comments categories: IBM Notesvert.x

Add your comment…

Comments

  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.