Back to top

API Documentation

Amida Messaging Microservice

A restful microservice allowing messaging between multiple users.

All API endpoints must be prefixed with the api keyword: for example, /api/message/list not just /message/list. Request headers should indicate a Content-Type of application/x-www-form-urlencoded and should include an Authorization field with value Bearer <auth_token>.

Content-Type: application/x-www-form-urlencoded
  Authorization: Bearer <auth_token>

Users of the messaging service must be registered on an instance of the Amida Auth Microservice. The required auth_token is obtained by authenticating against the Auth Microservice and receiving a JSON Web Token.

The request body should be sent x-www-form-urlencoded.

Response Status Codes

Success

All successful requests return responses with the following error codes:

  • GET, PUT and DELETE return 200 on success

  • POST returns 201 on success

Error

Error responses have standard HTTP error codes

For example, when attempting access messages with an invalid auth_token:

Status: 401 Access denied

Messages

Send a message

Create new Message
POST/message/send

Send a message to any number of recipients.

Example URI

POST /message/send
URI Parameters
HideShow
to
[string] (required) 

an array of strings with each string corresponding to a recipient username

from
string (optional) 

sender’s username

subject
string (optional) 

subject of the sent message

message
string (required) 
Request
HideShow
Headers
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/x-www-form-urlencoded
Body
{
    to: ["johnDoe", "janeDoe"]
    subject: "This API Rocks!",
    message: "This message is longer than it appears...",
}
Response  201
HideShow

Errors

  • Unauthorized (401) - no access token specified or invalid access token Authorization header
Body
{
  "isDeleted": false,
  "isArchived": false,
  "id": 3,
  "to": [
    "johnDoe",
    "janeDoe"
  ],
  "from": "test@test.com",
  "subject": "First Message Subject",
  "message": "First Message Message",
  "owner": "test@test.com",
  "createdAt": "2017-11-22T20:30:06.451Z",
  "readAt": "2017-11-22T20:30:06.451Z",
  "updatedAt": "2017-11-22T20:30:07.108Z",
  "originalMessageId": 3,
  "parentMessageId": null
}

Retrieve a message

Retrieve a message
GET/message/get/{messageId}

Retrieve a message using it’s unique ID.

Example URI

GET /message/get/messageId
URI Parameters
HideShow
messageId
integer (required) 

unique ID of the message to be retrieved(url)

Request
HideShow
Headers
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/x-www-form-urlencoded
Response  200
HideShow

Errors

  • Unauthorized (401) - no access token specified or invalid access token Authorization header
Body
{
  "id": 3,
  "owner": "test@test.com",
  "originalMessageId": 3,
  "parentMessageId": null,
  "to": [
    "user1"
  ],
  "from": "test@test.com",
  "subject": "First Message Subject",
  "message": "First Message Message",
  "createdAt": "2017-11-22T20:30:06.451Z",
  "readAt": "2017-11-22T20:30:06.451Z",
  "isDeleted": false,
  "isArchived": false,
  "updatedAt": "2017-11-22T20:30:07.108Z"
}

Reply to a message

Reply to an existing message
POST/message/reply/messageId

Reply to an existing message.

Example URI

POST /message/reply/messageId
URI Parameters
HideShow
messageId
integer (required) 

unique ID of the message being replied to(url)

to
[string] (required) 

an array of strings with each string corresponding to a recipient username

from
string (required) 

sender’s username

subject
string (required) 

Subject of the sent message

message
string (required) 
Request
HideShow
Headers
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/x-www-form-urlencoded
Body
{
    to: ["johnDoe", "janeDoe"]
    subject: "This API Rocks!",
    message: "This message is longer than it appears...",
}
Response  200
HideShow

Errors

  • Unauthorized (401) - no access token specified or invalid access token Authorization header
Body
{
  "isArchived": false,
  "id": 10,
  "to": [
    "user1",
    "test@test.com"
  ],
  "from": "test@test.com",
  "subject": "First Message Subject",
  "message": "First Message Message",
  "owner": "test@test.com",
  "createdAt": "2017-11-22T21:05:23.225Z",
  "readAt": "2017-11-22T21:05:23.225Z",
  "isDeleted": false,
  "parentMessageId": 5,
  "originalMessageId": 5,
  "updatedAt": "2017-11-22T21:05:23.228Z"
}

Retrieve a collection of messages

Retrieve a collection of messages
GET/message/list

Retrieve the current user’s messages with the option of including additional query parameters.

Example URI

GET /message/list
URI Parameters
HideShow
from
string (optional) 

only return messages from a given sender using the sender’s username(url)

limit
integer (optional) 

corresponds to the specific number of messages to be returned from the result of the query (url)

summary
boolean (optional) 

indicating summary=true as a url request parameter will force the request to return only subject, from and createdAt fields(url, optional)

archived
boolean (optional) 

indicating archived=true as a url request parameter will force the request to return only archived messages(url)

Request
HideShow
Headers
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/x-www-form-urlencoded
Response  200
HideShow

Errors

  • Unauthorized (401) - no access token specified or invalid access token Authorization header
Body
[
  {
    "id": 5,
    "owner": "test@test.com",
    "originalMessageId": 5,
    "parentMessageId": null,
    "to": [
      "user1",
      "test@test.com"
    ],
    "from": "test@test.com",
    "subject": "First Message Subject",
    "message": "First Message Message",
    "createdAt": "2017-11-22T21:05:07.391Z",
    "readAt": "2017-11-22T21:05:07.391Z",
    "isDeleted": false,
    "isArchived": false,
    "updatedAt": "2017-11-22T21:05:07.508Z"
  },
  {
    "id": 7,
    "owner": "test@test.com",
    "originalMessageId": 5,
    "parentMessageId": null,
    "to": [
      "user1",
      "test@test.com"
    ],
    "from": "test@test.com",
    "subject": "First Message Subject",
    "message": "First Message Message",
    "createdAt": "2017-11-22T21:05:07.625Z",
    "readAt": null,
    "isDeleted": false,
    "isArchived": false,
    "updatedAt": "2017-11-22T21:05:07.625Z"
  }
]

Archive a message

Archive an existing message
PUT/message/archive/{messageId}

Archive an existing message.

Example URI

PUT /message/archive/messageId
URI Parameters
HideShow
messageId
integer (required) 

unique ID of the message to be archived

Request
HideShow
Headers
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/x-www-form-urlencoded
Response  200
HideShow

Errors

  • Unauthorized (401) - no access token specified or invalid access token Authorization header
Body
{
  "id": 9,
  "owner": "test@test.com",
  "originalMessageId": 5,
  "parentMessageId": 5,
  "to": [
    "user1",
    "test@test.com"
  ],
  "from": "test@test.com",
  "subject": "First Message Subject",
  "message": "First Message Message",
  "createdAt": "2017-11-22T21:05:23.225Z",
  "readAt": null,
  "isDeleted": false,
  "isArchived": true,
  "updatedAt": "2017-11-22T21:39:14.943Z"
}

Unarchive a message

Unarchive an existing message
PUT/message/unarchive/{messageId}

Unarchive an existing message.

Example URI

PUT /message/unarchive/messageId
URI Parameters
HideShow
messageId
integer (required) 

unique ID of the message to be unarchived

Request
HideShow
Headers
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/x-www-form-urlencoded
Response  200
HideShow

Errors

  • Unauthorized (401) - no access token specified or invalid access token Authorization header
Body
{
  "id": 9,
  "owner": "test@test.com",
  "originalMessageId": 5,
  "parentMessageId": 5,
  "to": [
    "user1",
    "test@test.com"
  ],
  "from": "test@test.com",
  "subject": "First Message Subject",
  "message": "First Message Message",
  "createdAt": "2017-11-22T21:05:23.225Z",
  "readAt": null,
  "isDeleted": false,
  "isArchived": false,
  "updatedAt": "2017-11-22T21:42:12.617Z"
}

Soft delete a message

Soft delete an existing message
DELETE/message/delete/{messageId}

Sets the isDeleted field of a message to true.

Example URI

DELETE /message/delete/messageId
URI Parameters
HideShow
messageId
integer (required) 

unique ID of the message being archived

Request
HideShow
Headers
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/x-www-form-urlencoded
Response  200
HideShow

Errors

  • Unauthorized (401) - no access token specified or invalid access token Authorization header
Body
{
  "id": 9,
  "owner": "test@test.com",
  "originalMessageId": 5,
  "parentMessageId": 5,
  "to": [
    "user1",
    "test@test.com"
  ],
  "from": "test@test.com",
  "subject": "First Message Subject",
  "message": "First Message Message",
  "createdAt": "2017-11-22T21:05:23.225Z",
  "readAt": null,
  "isDeleted": true,
  "isArchived": false,
  "updatedAt": "2017-11-27T17:11:19.844Z"
}

Message Threads

Retrieve a message thread

Retrieve a message thread
GET/message/get/{originalMessageId}

Retrieve a message thread by the ID of the original message.

Example URI

GET /message/get/originalMessageId
URI Parameters
HideShow
originalMessageId
integer (required) 

the originalMessageId shared by all messages in the thread(url)

Request
HideShow
Headers
Authorization: Bearer ACCESS_TOKEN
Response  200
HideShow

Errors

  • Unauthorized (401) - no access token specified or invalid access token Authorization header

  • Not found (404) - no messages with the originalMessageId found

Body
[
  {
    "id": 3,
    "owner": "test@test.com",
    "originalMessageId": 3,
    "parentMessageId": null,
    "to": [
      "user1"
    ],
    "from": "test@test.com",
    "subject": "First Message Subject",
    "message": "First Message Message",
    "createdAt": "2017-11-22T20:30:06.451Z",
    "readAt": "2017-11-22T20:30:06.451Z",
    "isDeleted": false,
    "isArchived": false,
    "updatedAt": "2017-11-22T20:30:07.108Z"
  },
  {
    "id": 4,
    "owner": "test@test.com",
    "originalMessageId": 3,
    "parentMessageId": 3,
    "to": [
      "test@test.com"
    ],
    "from": "user1",
    "subject": "First Message Subject",
    "message": "Reply message content",
    "createdAt": "2017-11-22T20:35:06.451Z",
    "readAt": "2017-11-22T20:37:06.451Z",
    "isDeleted": false,
    "isArchived": false,
    "updatedAt": "2017-11-22T20:36:07.108Z"
  }
]

Generated by aglio on 26 Feb 2019