Skip to content

Latest commit

 

History

History
546 lines (424 loc) · 13.4 KB

api.md

File metadata and controls

546 lines (424 loc) · 13.4 KB
Raw

API 🎨

Summary

Group method endpoint
Server Info GET /
Main endpoints
├ Private message to user POST /api/v1/notify
├ Broadcast message to subscribers POST /api/v1/broadcast
└ Botframework-SDK entry-point POST /api/v1/messages
Admin endpoints
├ Server Routes GET /api/v1/admin
├ User index GET /api/v1/admin/users
├ User detail GET /api/v1/admin/users/{user}
├ Topic index GET /api/v1/admin/topics
├ Topic creation POST /api/v1/admin/topics
├ Topic detail GET /api/v1/admin/topics/{topic}
├ Topic subscription PUT /api/v1/admin/topics/{topic}
├ Topic removal DELETE /api/v1/admin/topics/{topic}
└ Topic subscription cancelation DELETE /api/v1/admin/topics/{topic}/{user}

Private notification to user

POST /api/v1/notify

Parameters

Name Required Type Description
user Required string Name of the recipient for the notification
message Required string or Activity or RichCard (*) The notification
mention Optional boolean Append a mention to the user (@user) (only for string messages)

* message allows 3 formats, read more

Response Codes

  • 202 Accepted: notification has been submitted to Microsoft's endpoint.
    Returns the used conversationKey for traceability.
  • 400 Bad Request: request body doesn't fulfill the requirements.
    Returns the expected parameter list.
  • 404 Not Found: requested user isn't registered in db.
    Returns the given user for traceability.

Examples

# 202
curl -s -H "content-type: application/json"\
 -d '{"user": "[email protected]", "message": "hi there"}'\
 localhost:3978/api/v1/notify | jq
{
  "conversationKey": "6afb0bc0-6ba7-11eb-98a1-211142846850|livechat"
}
# 202
curl -s -H "content-type: application/json"\
 -d '{"user": "[email protected]", "message": "hi there", "mention": true}'\
 localhost:3978/api/v1/notify | jq
{
  "conversationKey": "6afb0bc0-6ba7-11eb-98a1-211142846850|livechat"
}
# 400
curl -s -H "content-type: application/json"\
 -d '{"user": "[email protected]"}'\
 localhost:3978/api/v1/notify | jq
{
  "code": "BadRequest",
  "message": "required: 'name', 'message'"
}
# 404
curl -s -H "content-type: application/json"\
 -d '{"user": "[email protected]", "message": "who are you"}'\
 localhost:3978/api/v1/notify | jq
{
  "code": "NotFound",
  "message": "user not found: '[email protected]'"
}

up

Broadcast notification to subscribers

POST /api/v1/broadcast

Parameters

Name Required Type Description
topic Optional* string Name of the topic: every user subscribed to this topic will receive the notification
topics Optional* string[] List of topics names: every user subscribed to these topics will receive the notification
message Required string or Activity or RichCard (*) The notification
mention Optional boolean Append a mention to the user (@user) (only for string messages)
createTopicIfNotExists Optional boolean Ensure topic is created if wasn't registered on db

* message allows 3 formats, read more

Response Codes

  • 202 Accepted: 1+ notifications have been submitted to Microsoft's endpoint.
    Returns every used conversationId for traceability.
    Note: empty list would mean that there are currently no subscribers to the given topic.
  • 400 Bad Request: request body doesn't fulfill the requirements.
    Returns the expected parameter list
  • 404 Not Found: requested topic isn't registered in db.
    Returns the given topic for traceability.

Examples

# 202
curl -s -H "content-type: application/json"\
 -d '{"topic": "banana", "message": "broadcasting to banana subscribers"}'\
 localhost:3978/api/v1/broadcast
{
  "conversationKeys": [
    "6afb0bc0-6ba7-11eb-98a1-211142846850|livechat"
  ]
}
# 202
curl -s -H "content-type: application/json"\
 -d '{"topic": "banana", "message": "broadcasting to banana subscribers", "mention": true}'\
 localhost:3978/api/v1/broadcast | jq
{
  "conversationKeys": [
    "6afb0bc0-6ba7-11eb-98a1-211142846850|livechat"
  ]
}
# 202
curl -s -H "content-type: application/json"\
 -d '{"topic": "tangerine", "message": "anyone there?"}'\
 localhost:3978/api/v1/broadcast | jq
{
  "conversationKeys": []
}
# 202
curl -s -H "content-type: application/json"\
 -d '{"topic": "tangerine", "message": "anyone there?", "createTopicIfNotExists": true}'\
 localhost:3978/api/v1/broadcast | jq
{
  "conversationKeys": []
}
# 400
curl -s -H "content-type: application/json"\
 -d '{"topic": "banana"}'\
 localhost:3978/api/v1/broadcast | jq
{
  "code": "BadRequest",
  "message": "required: 'topic', 'message'"
}

up

Botframework-SDK entry-point

POST /api/v1/messages

This endpoint will be used by Azure (or the BotEmulator if you're working locally).
Does only accept POST method and already includes Microsoft's authentication.

up

User index

GET /api/v1/admin/users

Query params

None

Response Codes

  • 200 Ok: list of user keys

Examples

# 200
curl -s localhost:3978/api/v1/admin/users | jq
[
  "[email protected]",
  "[email protected]"
]

up

User detail

GET /api/v1/admin/users/{user}

Query params

None

Response Codes

  • 200 Ok: user instance
  • 404 Not Found: requested user isn't registered in db.
    Returns the given key for traceability.

Examples

# 200
curl -s localhost:3978/api/v1/admin/users/jane.doe%40megacoorp.com | jq
{
  "user": "[email protected]",
  "subscriptions": [
    "orange",
    "banana"
  ]
}
# 404
curl -s localhost:3978/api/v1/admin/users/fake.person%40nowhere.com | jq
{
  "code": "NotFound",
  "message": "user not found: '[email protected]'"
}

Topic index

GET /api/v1/admin/topics

Query params

None

Response Codes

  • 200 Ok: list of topic names

Examples

# 200
curl -s localhost:3978/api/v1/admin/topics | jq
[
  "banana",
  "apple",
  "orange"
]

up

Topic creation

POST /api/v1/admin/topics

Parameters

Name Required Type Description
name Required string Name of the topic

Response Codes

  • 200 Ok: registered topic (could already exist).
    Returns the topic (equivalent to a GET request)
  • 400 Bad Request: request body doesn't fulfill the requirements.
    Returns the expected parameter list

Examples

# 200
curl -s -H "content-type: application/json"\
 -d '{"name": "tangerine"}'\
 localhost:3978/api/v1/topics | jq
{
  "name": "tangerine",
  "subscribers": []
}
# 400
curl -s -H "content-type: application/json"\
 -d '{}'\
 localhost:3978/api/v1/topics | jq
{
  "code": "BadRequest",
  "message": "required: 'name'"
}

up

Topic Detail

GET /api/v1/admin/topic/:topic

Query params

None

Response Codes

  • 200 Ok: topic instance.
  • 404 Not Found: requested topic isn't registered in db.
    Returns the given name for traceability.

Examples

# 200
curl -s -H "content-type: application/json"\
 localhost:3978/api/v1/admin/topics/orange | jq
{
  "name": "orange",
  "subscribers": [
    "[email protected]",
    "[email protected]"
  ]
}
# 404
curl -s -H "content-type: application/json"\
 localhost:3978/api/v1/admin/topics/xxx | jq
{
  "code": "NotFound",
  "message": "xxx"
}

up

Topic subscription

PUT /api/v1/admin/topics/{topic}

Parameters

Name Required Type Description
user Required string Name of the forced subscriber to topic

Response Codes

  • 200 Ok: nice
    Returns the topic (equivalent to a GET request)
  • 400 BadRequest: request body doesn't fulfill the requirements.
    Returns the expected parameter list
    • 404 Not Found: requested user isn't registered in db.
      Returns the given user for traceability.

Examples

# 200
curl -s -X PUT -H "content-type: application/json"\
 -d '{"user": "[email protected]"}'\
 localhost:3978/api/v1/admin/topics/tangerine | jq
{
  "name": "tangerine",
  "subscribers": ["[email protected]"]
}
# 400
curl -s -X PUT -H "content-type: application/json"\
 -d '{}'\
 localhost:3978/api/v1/admin/topics/tangerine | jq
{
  "code": "BadRequest",
  "message": "required: 'user'"
}
# 404
curl -s -X PUT -H "content-type: application/json"\
 -d '{"user": "[email protected]"}'\
 localhost:3978/api/v1/admin/topics/tangerine | jq
{
  "code": "NotFound",
  "message": "user not found: '[email protected]'"
}

up

Topic removal

DELETE /api/v1/admin/topics/{topic}

Response Codes

  • 200 Ok: nice;
    Returns the topic list (equivalent to a GET index request).
  • 404 Not Found: requested topic doesn't exist in db.
    Returns the given topic for traceability.

Examples

# 200
curl -s -X DELETE -H "content-type: application/json"\
 localhost:3978/api/v1/admin/topics/tangerine | jq
[
  "banana",
  "apple",
  "orange"
]
# 404
curl -s -X DELETE -H "content-type: application/json"\
 localhost:3978/api/v1/admin/topics/UNKNOWN | jq
{
  "code": "NotFound",
  "message": "topic not found: 'unknown'"
}

up

Topic subscription cancelation

DELETE /api/v1/admin/topics/{topic}/{user}

Response Codes

  • 200 Ok: nice; independently of actual operation - e.g. the user wasn't subscribed to the given topic in first place.
    Returns the topic (equivalent to a GET request).
  • 404 Not Found: requested user or topic aren't registered in db.
    Returns the given resource for traceability.

Examples

# 200
curl -s -X DELETE -H "content-type: application/json"\
 localhost:3978/api/v1/admin/topics/tangerine/jane.doe%40megacoorp.com | jq
{
  "name": "tangerine",
  "subscribers": []
}
# 404
curl -s -X DELETE -H "content-type: application/json"\
 localhost:3978/api/v1/admin/topics/tangerine/fake.person%40nowhere.com | jq
{
  "code": "NotFound",
  "message": "user not found: '[email protected]'"
}
# 404
curl -s -X DELETE -H "content-type: application/json"\
 localhost:3978/api/v1/admin/topics/fake/jane.doe%40megacoorp.com | jq
{
  "code": "NotFound",
  "message": "topic not found: 'fake'"
}