REST API v3 proposal

[Danita]

Hi! I'm developing a REST web client to use with ElasticInbox and two important things I've noticed with the current API implementation are:

• Resources url do not follow REST standard accepted practices, which makes it really convoluted to employ REST libraries that expect that a resource would be accesible at /resource/{id}, a collection of them in /resources/, and nested resources in resource/{id}/children/ as many REST implementations do.
• Responses do not follow commonly used JSON response formats, which forces us to do conversions before and after read/write.

I would love to help in the format of patches or pull requests, but I don't know a word of Java. Instead here is what I propose for the next API revision, and I hope some fellow collaborators with help with the code 😄

Labels

Get all labels
GET /{domain}/{user}/mailbox/labels/

Get one label
GET /{domain}/{user}/mailbox/labels/{label_id}

Create label
POST /{domain}/{user}/mailbox/labels/

Edit label
PUT /{domain}/{user}/mailbox/labels/{label_id}

Delete label
DELETE /{domain}/{user}/mailbox/labels/{label_id}

Messages

Get all messages
GET /{domain}/{user}/mailbox/messages/

Get one message (parsed)
GET /{domain}/{user}/mailbox/messages/{message_id}

Get one message (raw)
GET /{domain}/{user}/mailbox/messages/{message_id}?format=raw

Get one message (blob uri)
GET /{domain}/{user}/mailbox/messages/{message_id}?format=blob_uri

Get all messages in label
GET /{domain}/{user}/mailbox/labels/{label_id}/messages/

Get message part by part id or content id
GET /{domain}/{user}/mailbox/messages/{message_id}/parts/{part_id} (part_id format determines response)

Create message
POST /{domain}/{user}/mailbox/messages/

Edit message (also modifying labels and markers)
PUT /{domain}/{user}/mailbox/messages/{message_id}

Delete message
DELETE /{domain}/{user}/mailbox/messages/{message_id}

Mailbox

Purge deleted messages in mailbox
PUT /{domain}/{user}/mailbox/messages/purge

Update label counters
PUT /{domain}/{user}/mailbox/labels/refresh (not sure of verb)

Batch

Bulk operations could be handled at the resource level (PUT /mailbox/messages/{message_id},{message_id}... for edit, DELETE /mailbox/messages/{message_id},{message_id}... to delete) or via a dedicated url when the number of resources is too big to handle as part of the request url (PUT /mailbox/batch/messages/, DELETE /mailbox/batch/messages/) so the id collection to affect could be sent as part of the request body.

Miscelaneous

Data representation

All collections should be represented as an array of javascript primitives (strings, objects, other arrays):

[
    {
        "id" : 0
        "name" : "all"
    },
    {
        "id" : 1
        "name" : "inbox"
    },
    {
        "id" : 2
        "name" : "drafts"
    }
]

Domains and users

I'm not really sure of using /rest/v2/{domain}/{user}/ as a way to address either of them. I think that a structure like the following could also provide a RESTful way to handle CRUD for user and domain resources:

/rest/v2/domains/{domain}/accounts/{user}

Thus:

GET /rest/v2/domains/ (get all domains for this ElasticInbox instance)
POST /rest/v2/domains/ (create a new domain)
GET /rest/v2/domains/{domain} (get info for a specific domain)
GET /rest/v2/domains/{domain}/users/ (list users for a domain)
POST /rest/v2/domains/{domain}/users/ (create a new user for this domain)
GET /rest/v2/domains/{domain}/users/{user} (get info for this user)

...and so on. Thoughts?

Reference: http://shop.oreilly.com/product/9780596801694.do

[rstml]

Hi Daniela, this is a great feedback! I quickly skimmed through it and overall I like it. JSON responses was another topic which we wanted to improve. Let us go through it in details and I'll provide complete feedback within a few days. It shouldn't be too hard to implement too so we may get this into 0.4 release.

[Danita]

Rustam, I'm so glad to hear that 😄 because I was just struggling to fix the following problem and I seem to have reached a dead end: it seems Chrome and Opera go their own way at ordering associative arrays, so it's another point in favor of using object arrays:

http://stackoverflow.com/questions/5020699/how-do-you-stop-chrome-and-opera-sorting-json-objects-by-index-asc

User defined labels cannot be consistently show in the same order in different browsers because of this :( This is Firefox and Chrome side by side, the same response:

[rstml]

Label ID is a random number. You should not rely on this for ordering. Let's continue discussion in #37

[Danita]

Another alternative ElasticInbox could use for data interchange would be Open Data Protocol (OData) http://www.odata.org/ which is an interesting API normalization effort.