Saga Documentation 0.9.434-4

Users & Bots

List of resources expected to be used in user/consumer facing SAGA clients as well as in internal admin/authoring systems.

Table of Contents

Users

A user has a real world identity and the ability authenticate with SAGA. Each user has a unique immutable ID, a username, policies that describe the users permissions in SAGA. A user has a list of properties. that describe its current state, such a location, inventory items, heartbeat, score and so forth.

POST /users/register

Used by a client to create a user. Minimum requirement is a unique username. Optional values are password to provide login ability, email for email registration and displayname for a human readable name.

If the system allows unverified users the response contains an accessToken as well as a refreshToken to receive a new accessToken. Otherwise the response is simply {ok:1} and the user needs to verified.

Triggers Event: /users/events/create

POST

{
  "username":"the username",
}

RESPONSE

{
  "username": "username",
  "accessToken": "eyJ0eXAiOiJKV1QJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6InRheWxvcmhlbGxhbSIsImV4cGlyZXMiOiIyMDE1LTA5LTA4VDIwOjM0LjIzMloifQ.LeC0U0w2nAc_Ld0d3j_5wVBsq",
  "refreshToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0eXBlIjoicmVmcmVzaCIsIl9pZCI6IjVjYmUyZDY1YmMwMjdhMDdjOTg2MTUxYSIsInVzZXJuYW1lIjoiZm9vYmFyIiwiZGF0ZSI6IjIwMTktMDQtMjJUMjE6MDg6NTMuMDU3WiJ9.xoH59FuOL4WmtVeHxuPunoerlNVai9mmhVnaRJyByYY"    
}

POST with password

{
  "username":"the username",
  "password":"the password",
}

RESPONSE

{
  "username": "username",
  "accessToken": "eyJ0eXAiOiJKV1QJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6InRheWxvcmhlbGxhbSIsImV4cGlyZXMiOiIyMDE1LTA5LTA4VDIwOjM0LjIzMloifQ.LeC0U0w2nAc_Ld0d3j_5wVBsq",
  "refreshToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0eXBlIjoicmVmcmVzaCIsIl9pZCI6IjVjYmUyZDY1YmMwMjdhMDdjOTg2MTUxYSIsInVzZXJuYW1lIjoiZm9vYmFyIiwiZGF0ZSI6IjIwMTktMDQtMjJUMjE6MDg6NTMuMDU3WiJ9.xoH59FuOL4WmtVeHxuPunoerlNVai9mmhVnaRJyByYY"    
}

POST with email and password

{
  "username":"the username",
  "password":"the password",
  "email":"the email",
  "displayname":"the displayname"
}

RESPONSE

{
  "email": "foo@bar.com",
  "username": "username",
  "accessToken": "eyJ0eXAiOiJKV1QJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6InRheWxvcmhlbGxhbSIsImV4cGlyZXMiOiIyMDE1LTA5LTA4VDIwOjM0LjIzMloifQ.LeC0U0w2nAc_Ld0d3j_5wVBsq",
  "refreshToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0eXBlIjoicmVmcmVzaCIsIl9pZCI6IjVjYmUyZDY1YmMwMjdhMDdjOTg2MTUxYSIsInVzZXJuYW1lIjoiZm9vYmFyIiwiZGF0ZSI6IjIwMTktMDQtMjJUMjE6MDg6NTMuMDU3WiJ9.xoH59FuOL4WmtVeHxuPunoerlNVai9mmhVnaRJyByYY"    
}

POST with email, password and displayname

{
  "username":"the username",
  "password":"the password",
  "email":"the email",
  "displayname":"the displayname"
}

RESPONSE

{
  "email": "foo@bar.com",
  "username": "username",
  "accessToken": "eyJ0eXAiOiJKV1QJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6InRheWxvcmhlbGxhbSIsImV4cGlyZXMiOiIyMDE1LTA5LTA4VDIwOjM0LjIzMloifQ.LeC0U0w2nAc_Ld0d3j_5wVBsq",
  "refreshToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0eXBlIjoicmVmcmVzaCIsIl9pZCI6IjVjYmUyZDY1YmMwMjdhMDdjOTg2MTUxYSIsInVzZXJuYW1lIjoiZm9vYmFyIiwiZGF0ZSI6IjIwMTktMDQtMjJUMjE6MDg6NTMuMDU3WiJ9.xoH59FuOL4WmtVeHxuPunoerlNVai9mmhVnaRJyByYY"    
}

POST with email, password, displayname, and tags

{
  "username":"the username",
  "password":"the password",
  "email":"the email",
  "displayname":"the displayname",
  "tags":["tag1","tag2"]
}

RESPONSE

{
  "email": "foo@bar.com",
  "username": "username",
  "accessToken": "eyJ0eXAiOiJKV1QJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6InRheWxvcmhlbGxhbSIsImV4cGlyZXMiOiIyMDE1LTA5LTA4VDIwOjM0LjIzMloifQ.LeC0U0w2nAc_Ld0d3j_5wVBsq",
  "refreshToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0eXBlIjoicmVmcmVzaCIsIl9pZCI6IjVjYmUyZDY1YmMwMjdhMDdjOTg2MTUxYSIsInVzZXJuYW1lIjoiZm9vYmFyIiwiZGF0ZSI6IjIwMTktMDQtMjJUMjE6MDg6NTMuMDU3WiJ9.xoH59FuOL4WmtVeHxuPunoerlNVai9mmhVnaRJyByYY",
  "tags": ["tag1","tag2"]
}

POST with email, password and properties

When registering a user you can supply a list of properties the user will be initialized with. name and value tuples provided in property_list will be transformed into the common properties structure. This can be combined with tags.

{
  "username":"username",
  "password":"5tr3ng3r",
  "email":"foo@bar.com",
  "property_list":[{"name":"level","value":1},{"name":"code","value":"565"}]
}

RESPONSE

{
  "email": "foo@bar.com",
  "username": "username",
  "accessToken": "eyJ0eXAiOiJKV1QJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6InRheWxvcmhlbGxhbSIsImV4cGlyZXMiOiIyMDE1LTA5LTA4VDIwOjM0LjIzMloifQ.LeC0U0w2nAc_Ld0d3j_5wVBsq",
  "refreshToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0eXBlIjoicmVmcmVzaCIsIl9pZCI6IjVjYmUyZDY1YmMwMjdhMDdjOTg2MTUxYSIsInVzZXJuYW1lIjoiZm9vYmFyIiwiZGF0ZSI6IjIwMTktMDQtMjJUMjE6MDg6NTMuMDU3WiJ9.xoH59FuOL4WmtVeHxuPunoerlNVai9mmhVnaRJyByYY",
  "properties":{
    "level": {
      "_id": "5c77795cc181020053c37c9a",
      "name": "level",
      "type": "user",
      "value": 1,
      "parent_id": "558072df07057872e31ee84b",
      "updatedAt": "2019-02-28T06:02:04.071Z",
      "createdAt": "2019-02-28T06:02:04.071Z",
      "sortable_id": 47149016,
      "__v": 0
    },
    "code": {
      "_id": "5c77795cc181080053c37c90",
      "name": "code",
      "type": "user",
      "value": "565",
      "parent_id": "558072df07057872e31ee84b",
      "updatedAt": "2019-02-28T06:02:04.071Z",
      "createdAt": "2019-02-28T06:02:04.071Z",
      "sortable_id": 47149016,
      "__v": 0
    }
  }
}

POST /users/generate/basic

Used to create a not explicitly named user object. The post body can contain an optional "prefix" entry to prefix a username. Response contains an accessToken as well as a refreshToken to receive a new accessToken

Triggers Event: /actions/users/create

POST

{ }

RESPONSE

{
  "username": "5fafb95b-7126-4bcf-b5f0-e6d97bcd2171",
  "accessToken": "eyJ0eXAiOiJKV1QJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6InRheWxvcmhlbGxhbSIsImV4cGlyZXMiOiIyMDE1LTA5LTA4VDIwOjM0LjIzMloifQ.LeC0U0w2nAc_Ld0d3j_5wVBsq",
  "refreshToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0eXBlIjoicmVmcmVzaCIsIl9pZCI6IjVjYmUyZDY1YmMwMjdhMDdjOTg2MTUxYSIsInVzZXJuYW1lIjoiZm9vYmFyIiwiZGF0ZSI6IjIwMTktMDQtMjJUMjE6MDg6NTMuMDU3WiJ9.xoH59FuOL4WmtVeHxuPunoerlNVai9mmhVnaRJyByYY"    
}

POST with prefix

{
  "prefix":"app1"
}

RESPONSE

{
  "username": "app1_5fafb95b-7126-4bcf-b5f0-e6d97bcd2171",
  "accessToken": "eyJ0eXAiOiJKV1QJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6InRheWxvcmhlbGxhbSIsImV4cGlyZXMiOiIyMDE1LTA5LTA4VDIwOjM0LjIzMloifQ.LeC0U0w2nAc_Ld0d3j_5wVBsq",
  "refreshToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0eXBlIjoicmVmcmVzaCIsIl9pZCI6IjVjYmUyZDY1YmMwMjdhMDdjOTg2MTUxYSIsInVzZXJuYW1lIjoiZm9vYmFyIiwiZGF0ZSI6IjIwMTktMDQtMjJUMjE6MDg6NTMuMDU3WiJ9.xoH59FuOL4WmtVeHxuPunoerlNVai9mmhVnaRJyByYY"    
}

POST with tags

{
  "tags":["tag1", "tag2"]
}

RESPONSE

{
  "username": "5fafb95b-7126-4bcf-b5f0-e6d97bcd2171",
  "accessToken": "eyJ0eXAiOiJKV1QJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6InRheWxvcmhlbGxhbSIsImV4cGlyZXMiOiIyMDE1LTA5LTA4VDIwOjM0LjIzMloifQ.LeC0U0w2nAc_Ld0d3j_5wVBsq",
  "refreshToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0eXBlIjoicmVmcmVzaCIsIl9pZCI6IjVjYmUyZDY1YmMwMjdhMDdjOTg2MTUxYSIsInVzZXJuYW1lIjoiZm9vYmFyIiwiZGF0ZSI6IjIwMTktMDQtMjJUMjE6MDg6NTMuMDU3WiJ9.xoH59FuOL4WmtVeHxuPunoerlNVai9mmhVnaRJyByYY",
  "tags": ["tag1", "tag2"]
}

POST /users/generate/test

Creates a test user. See the test data documentation

No request body required.

RESPONSE

{
  "username": "5fafb95b-7126-4bcf-b5f0-e6d97bcd2171",
  "accessToken": "eyJ0eXAiOiJKV1QJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6InRheWxvcmhlbGxhbSIsImV4cGlyZXMiOiIyMDE1LTA5LTA4VDIwOjM0LjIzMloifQ.LeC0U0w2nAc_Ld0d3j_5wVBsq",
  "refreshToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0eXBlIjoicmVmcmVzaCIsIl9pZCI6IjVjYmUyZDY1YmMwMjdhMDdjOTg2MTUxYSIsInVzZXJuYW1lIjoiZm9vYmFyIiwiZGF0ZSI6IjIwMTktMDQtMjJUMjE6MDg6NTMuMDU3WiJ9.xoH59FuOL4WmtVeHxuPunoerlNVai9mmhVnaRJyByYY"    
}

POST /users/available

Tests if a given username and email are available.

POST

{
  "username":"available_username",
  "email":"taken@email.com",
}

RESPONSE

{
  "username":true,
  "email":false
}

POST /users/login

Lo log in a user, response contains an accessToken as well as a refreshToken to receive a new accessToken. Post variables are username and password.

Sample response:

POST

{
  "username":"the username",
  "password":"the password",
}

RESPONSE

{
  "email": "foo@bar.com",
  "username": "username",
  "accessToken": "eyJ0eXAiOiJKV1QJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6InRheWxvcmhlbGxhbSIsImV4cGlyZXMiOiIyMDE1LTA5LTA4VDIwOjM0LjIzMloifQ.LeC0U0w2nAc_Ld0d3j_5wVBsq",
  "refreshToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0eXBlIjoicmVmcmVzaCIsIl9pZCI6IjVjYmUyZDY1YmMwMjdhMDdjOTg2MTUxYSIsInVzZXJuYW1lIjoiZm9vYmFyIiwiZGF0ZSI6IjIwMTktMDQtMjJUMjE6MDg6NTMuMDU3WiJ9.xoH59FuOL4WmtVeHxuPunoerlNVai9mmhVnaRJyByYY"  
}

POST /users/verify

Used to verify a user. If no user with the token can be found or another user meanwhile captured the email or username you will see a 422 or a 404 response. Note that this will not login the user.

Triggers Event: /users/events/verify

REQUEST BODY

{
  "code":"the verification code"
}

RESPONSE

{
  "ok":1    
}

POST /users/trigger_verify_notification

Triggers an additional verification event if the user lost access to the result of the original notification event. Will results in a 200 for a known unverified user or a 404 for an unknown unverified user.

Triggers Event: /users/events/verify

REQUEST BODY

{
  "username":"the username"
}

RESPONSE

{
  "ok":1    
}

GET /users/forgot_password/:email

Triggers the forgot email proccess in the system. Essentially this fires an event that is handled by a saga script that will sends an email, etc. The reponse status of this call is always 200 irregardless of whether the email exists or not.

Triggers Event: /users/events/change_password_request

RESPONSE

{
  "ok":1    
}

POST /users/change_password_verify

Used to change password, requires a change passwork token and a new password. Responds with 404 if the token cannot be found or a 422 if the password is not accepted.

Triggers Event: /users/events/change_password_verified

REQUEST BODY

{
  "code":"the change password code",
  "password":"the password",
}

RESPONSE

{
  "ok":1    
}

POST /users/:user_id/change_email_request

Used to change the users email. This should trigger an email or message via ascript containing the change code

Triggers Event: /users/events/change_email_request

REQUEST BODY

{
  "email":"the new email"
}

RESPONSE

{
  "ok":1    
}

POST /users/:user_id/change_email_verify

Used to verify the users email change request

Triggers Event: /users/events/change_email_verified

REQUEST BODY

{
  "code":"the change email request code"
}

RESPONSE

{
  "ok":1    
}

POST /users/:user_id/refresh_token

Used to retrieve a new access token when one expired. The :username must match the username of the user who received the refreshToken when authenticating with Saga

POST

{
  "refreshToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0eXBlIjoicmVmcmVzaCIsIl9pZCI6IjVjYmUyZDY1YmMwMjdhMDdjOTg2MTUxYSIsInVzZXJuYW1lIjoiZm9vYmFyIiwiZGF0ZSI6IjIwMTktMDQtMjJUMjE6MDg6NTMuMDU3WiJ9167671.xoH59FuOL4WmtVeHxuPunoerlNVai9mmhVnaRJyByXX99"  
}

RESPONSE

{
  "accessToken": "eyJ0eXAiOiJKV1QJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6InRheWxvcmhlbGxhbSIsImV4cGlyZXMiOiIyMDE1LTA5LTA4VDIwOjM0LjIzMloifQ.LeC0U0w2nAc_Ld0d3j_5wVBsq",
  "refreshToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0eXBlIjoicmVmcmVzaCIsIl9pZCI6IjVjYmUyZDY1YmMwMjdhMDdjOTg2MTUxYSIsInVzZXJuYW1lIjoiZm9vYmFyIiwiZGF0ZSI6IjIwMTktMDQtMjJUMjE6MDg6NTMuMDU3WiJ9.xoH59FuOL4WmtVeHxuPunoerlNVai9mmhVnaRJyByYY"    
}

GET /users

List all users with the current value of each property. Users can be searched and sorted.

  • search:
    • partial name like "name1"
    • filtering users with has to test for properties: has:location or multiple properties has:location has:home
    • filtering users with has having certain property values:has:favorite_color.value='red', has:game.value.selected=true, has:level.value=8
    • filtering with has by querying user property values: has:level.value={$gt:5} This is using mongo query selectors. When using $regex please note that a "" has to be encoded with "@". has:name.value={$regex:"/[a-z]+@d@d$/i"} becomes has:name.value={$regex:"/[a-z]+\d\d$/i"} . This is due to a JSON.parse limitation.
    • by combing the above player1 has:level or players has:colors.value.favorite='red',level.value=1
    • ordering by distance with near. It needs to be a URL parameter encoded geoJSON point value, for example: 
      {
    "type": "Point",
    "coordinates": [-74.642107,41.054243]
}
    • containing the maximum distance of the near search is done with the max_distance_m parameter which only returns results that are with the distance (in meters) from the point
    • returning results within an area using geoWithin. It needs to be a URL parameter encoded geoJSON polygon value, for example: 
      {
   "type": "Polygon",
   "coordinates": [
    [
      [
         -79.456097,
         24.562112
      ],
      [
         -80.252972,
         31.074696
      ],
      [
         -70.972012,
         40.427872
      ]
     ]
    ]              
}
    • by combing the above player1 has:level or players has:colors.value.favorite='red',level.value=1
    • a 422 error is thrown if the has or the near query are malformed
    • filter by a single tag tag:agent or multiple tags tag:agent tag:schedule
    • filter content by a list of id values id:573027f20bb5f8030073b6a5,2573027f20bb5f8030073b6a5
  • query 
    {
"$or": [
  {
    "$and": [
      {"properties.status.value": "online"},
      {
        "$and": [
          {"properties.age.value": {$gt: 20}},
          {"properties.age.value": {$lt: 30}}
        ]
      }
    ]
  },
  {
    "$or": [
      {"properties.progress.value": 100},
    ]
  }
]
}
  • sort
    • users can be sorted by 'username' or property values. sort=username sorts by username and sort=properties.level.value sorts descending by the values of level property, if this is used routinely an indexed property definition should be set.
  • mode
    • multiple search criteria are concatenated with the AND operator. to change that to OR set the mode parameter to 'or' when conducting a search
  • fields:
    • command separated list of names of fields to be returned
      • name,email
      • name,properties.geoJSON

RESPONSE

[
  {
    "_id":"573027f20bb5f8030073b6a5",
    "username":"1018412864895979fb",
    "email":"1018412864895979fb@fb.com",
    "displayname":"the displayname",  
    "properties":{
        "next_message": {
          "_id": "5c77795cc181020053c37c9a",
          "type": "user",
          "value": "yes",
          "parent_id": "5c686401a1b3490004b9ce0e",
          "source_creator": {
            "type": "oob"
          },
          "updatedAt": "2019-02-28T06:02:04.071Z",
          "createdAt": "2019-02-28T06:02:04.071Z",
          "sortable_id": 47149016,
          "__v": 0
        }
    }
  },
  {
    "_id":"2573027f20bb5f8030073b6a5",
    "username":"2018412864895979fb",
    "email":"21018412864895979fb@fb.com",
    "displayname":"the displayname #2",
    "properties":{
        "location": {

          "_id": "5c781fed47512800044927e5",
          "type": "user",
          "value": {
            "latitude": 40.74954,
            "longitude": -73.99173,
            "date": "2019-02-28T18:03:41.814Z"
          },
          "parent_id": "55eef2a943f0910300969b90",
          "source_creator": {
            "id": "568b1a24ee2dac0300723ca6",
            "type": "job"
          },
          "runnable_call_id": "5c781fed47512800044927e4",
          "createdAt": "2019-02-28T17:52:45.847Z",
          "sortable_id": 47161170
      },
        "home": {

          "_id": "5c781fed47512100044927e5",
          "type": "user",
          "value": {
            "latitude": 40.74954,
            "longitude": -73.99173,
            "date": "2019-02-28T12:03:41.814Z"
          },
          "parent_id": "55eef2a943f0910300969b90",
          "source_creator": {
            "id": "568b1a24ee2dac0100723ca6",
            "type": "script"
          },
          "runnable_call_id": "5c781fed47512800044927e4",
          "createdAt": "2019-02-28T17:52:45.847Z",
          "sortable_id": 47161170
      }        
    }    
   }
]

GET /users/:user_id

Returns the data of a specific user including the current value of each property of the user.

Query Parameters

  • fields:
    • command separated list of names of fields to be returned
      • username,email
      • username,properties.geoJSON

RESPONSE

{
  "_id":"573027f20bb5f8030073b6a5",
  "username":"1018412864895979fb",
  "email":"1018412864895979fb@fb.com",
  "displayname":"the displayname",
  "properties":{
      "next_message": {
      "_id": "5c77795cc181020053c37c9a",
      "type": "user",
      "name": "next_message",
      "value": "yes",
      "parent_id": "5c686401a1b3490004b9ce0e",
      "source_creator": {
        "type": "oob"
      },
      "updatedAt": "2019-02-28T06:02:04.071Z",
      "createdAt": "2019-02-28T06:02:04.071Z",
      "sortable_id": 47149016,
      "__v": 0
    }
  }
}

PUT /users/:user_id

Used to change username and/or display name. If you successfully change the username the user will need to log in again, all previously issued tokens to the user become invalid.

REQUEST BODY

{
  "username":"the new username",
  "displayname":"the displayname"  
}

RESPONSE

{
  "email": "foo@bar.com",
  "username": "username",
  "properties":{}
}

PUT /users/:user_id/password

Used to change the users password. Put variables are new_password and new_password_confirm. Responds with the user info.

POST

{
  "new_password":"the password",
  "new_password_confirm":"the password"
}

RESPONSE

{
  "email": "foo@bar.com",
  "username": "username",
  "accessToken": "eyJ0eXAiOiJKV1QJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6InRheWxvcmhlbGxhbSIsImV4cGlyZXMiOiIyMDE1LTA5LTA4VDIwOjM0LjIzMloifQ.LeC0U0w2nAc_Ld0d3j_5wVBsq"
}

Bots

A bot is every entity that is not a user. A chatty character in a game, a networked light in a dark alley, a networked audio speaker or a wandering virtual spatial agent traversing the digital. A bot has a set of properties in an identical structure to users. Each bot has a unique immutable ID, a name and a list of properties.

POST /bots

Create a named bot. Optionally a bot can be declared test data by setting the test_data to true.

POST

{
  "name":"the botname"
}

RESPONSE

{
    "_id": "558072df07057872e31ee84b",
    "name": "the botname"
    
}

POST with tags

{
  "name":"the botname",
  "tags":["tag1","tag2"]
}

RESPONSE

{
    "_id": "558072df07057872e31ee84b",
    "name": "the botname",
    "tags": ["tag1","tag2"]
}

POST with properties

When creating a bot you can supply a list of properties the bot will be initialized with. name and value tuples provided in property_list will be transformed into the common properties structure. This can be combined with `tags

{
  "name":"the botname",
  "tags": ["tag1","tag2"],
  "property_list":[
    {"name":"level", "value":1},
    {"name":"code", "value":"565"}
  ]
}

RESPONSE

{
    "_id": "558072df07057872e31ee84b",
    "name": "the botname",
    "tags": ["tag1","tag2"],
    "properties":{
      "level": {
        "_id": "5c77795cc181020053c37c9a",
        "name": "level",  
        "type": "bot",
        "value": "yes",
        "parent_id": "558072df07057872e31ee84b",
        "updatedAt": "2019-02-28T06:02:04.071Z",
        "createdAt": "2019-02-28T06:02:04.071Z",
        "sortable_id": 47149016,
        "__v": 0
      },
      "code": {
        "_id": "5c77795cc181080053c37c90",
        "name": "code",
        "type": "bot",
        "value": "565",
        "parent_id": "558072df07057872e31ee84b",
        "updatedAt": "2019-02-28T06:02:04.071Z",
        "createdAt": "2019-02-28T06:02:04.071Z",
        "sortable_id": 47149016,
        "__v": 0
      }      
    }
}

POST to create multiple objects

To create multiple objects at once an array of bots can passed in, the bots can use property_list and tags. The response will contain the bot _id and the status_code, 200 if success or 422 if there was a validation issue. 

[
    {
        "name":"botname1",
        "tags": ["tag1","tag2"],
        "test_data": true,
        "property_list":[
            {"name":"level", "value":1},
        ]
    },
    {
        "name":"botname1",
        "test_data": true,
        "property_list":[
            {"name":"level", "value":15},
        ]
    },
    {
        "name":"botname2",
        "test_data": true,
    }    
]    

[
  {
    "_id": "5c77795cc181020053c37c9a",
    "status_code": 200
  },
  {
    "name": "Unprocessable Entity",
    "status_code": 422,
    "errors": { "name": "'name' is taken" }
  },
  {
    "_id": "5c77795cc181020053c37c9a",
    "status_code": 200
  }
]

GET /bots

List all bots. Optional query parameters:

List all users with the current value of each property. Bots can be searched and sorted.

  • search:
    • partial name like "name1"
    • filtering bots having certain properties: has:location or multiple properties has:location has:home
    • filtering bots having certain property values:has:favorite_color.value='red', has:game.value.selected=true, has:level.value=8
    • filtering by querying bot property values: has:level.value={$gt:5} This is using mongo query selectors. When using $regex please note that a "" has to be encoded with "@". has:name.value={$regex:"/[a-z]+@d@d$/i"} becomes has:name.value={$regex:"/[a-z]\d\d$/i"} . This is due to a JSON.parse limitation.
    • by combing the above player1 has:level or players has:colors.value.favorite='red',level.value=1
    • ordering by distance with near. It needs to be a URL parameter encoded geoJSON point value, for example: 
      {
    "type": "Point",
    "coordinates": [-74.642107,41.054243]
}
    • returning results within an area using geoWithin. It needs to be a URL parameter encoded geoJSON polygon value, for example: 
      {
   "type": "Polygon",
   "coordinates": [
    [
      [
         -79.456097,
         24.562112
      ],
      [
         -80.252972,
         31.074696
      ],
      [
         -70.972012,
         40.427872
      ]
     ]
    ]              
}
    • contraining the maximum distance of the near search is done with the max_distance_m parameter which only returns results that are with the distance (in meters) from the point
    • a 422 error is thrown if the has query is malformed
    • filter by a single tag tag:agent or multiple tags tag:agent tag:schedule
    • filter content by a list of id valuesid:573027f20bb5f8030073b6a5,2573027f20bb5f8030073b6a5
  • query 
    {
"$or": [
  {
    "$and": [
      {"properties.status.value": "online"},
      {
        "$and": [
          {"properties.age.value": {$gt: 20}},
          {"properties.age.value": {$lt: 30}}
        ]
      }
    ]
  },
  {
    "$or": [
      {"properties.progress.value": 100},
    ]
  }
]
}
  • sort
    • users can be sorted by 'username' or property values. sort=username sorts by username and sort=properties.level.value sorts descending by the values of level property, if this is used routinely an indexed property definition should be set.
  • mode
    • multiple search criteria are concatenated with the AND operator. to change that to OR set the mode parameter to 'or' when conducting a search

  • fields: - command separated list of names of fields to be returned - name,email - name,properties.geoJSON

RESPONSE

[
  {
    "_id": "558072df07057872e31ee84b",
    "name": "chatbotname1",
    "properties":{
      "next_message": {
        "_id": "5c77795cc181020053c37c9a",
        "type": "user",
        "value": "yes",
        "parent_id": "5c686401a1b3490004b9ce0e", 
        "updatedAt": "2019-02-28T06:02:04.071Z",
        "createdAt": "2019-02-28T06:02:04.071Z",
        "sortable_id": 47149016,
        "__v": 0
      }
    }    
  },
  {
    "_id": "558072df07057872e31ee84b",
    "name": "chatbotname2",
    "properties":{}
  }
]

GET /bots/:bot_id

Get the bot with the given id

Query Parameters

  • fields:
    • command separated list of names of fields to be returned
      • name,email
      • name,properties.geoJSON

RESPONSE

{
  "_id": "558072df07057872e31ee84b",
  "name": "the botname",
  "properties":{
    "next_message": {
      "_id": "5c77795cc181020053c37c9a",
      "type": "user",
      "value": "yes",
      "parent_id": "5c686401a1b3490004b9ce0e", 
      "updatedAt": "2019-02-28T06:02:04.071Z",
      "createdAt": "2019-02-28T06:02:04.071Z",
      "sortable_id": 47149016,
      "__v": 0
    }
  }
    
}

DELETE /bots/:bot_id

Delete the bot with the given id.

UPDATE /bots/:bot_id

Update the name of the given bot.

POST

{
  "name":"the new botname",
}

RESPONSE

{
    "_id": "558072df07057872e31ee84b",
    "name": "the new botname"
}