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 horsemen verbs I envision the following action matrix:
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!
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 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/a | n/an/a |
Stay tuned!
Posted by Stephan H Wissel on 08 August 2014 | Comments (2) | categories: IBM Notes vert.x