API calls troubleshooting using Postman.

Unknown

I am creating this discussion to go through the initial troubleshooting steps that CSMs can follow when getting API calls questions, the recent validation errors and what was done to fix/troubleshoot them & how to use Postman.

We will be adding more test examples.

API docs reference for endpoints that i'll be testing

/comments

https://docs.vanillaforums.com/help/apiv2/swagger/#/Comments/get_comments

/discussions

https://docs.vanillaforums.com/help/apiv2/swagger/#/Discussions/get_discussions

/analytics

https://docs.vanillaforums.com/help/apiv2/analytics/

API Call: /discussions

Error: "Validation Failed", "item.name is required."

The client was getting this error on some of the pages. Looking at the error message "name is required" when making a /discussions call, means one of the discussion names is either empty or is getting filtered somewhere in the code.

Troubleshooting

You can start troubleshooting this using PostMan (steps below).In this case it was discussion names that started with <name, getting filtered to "", and since discussion name is a required field the API call was failing, causing the validation error. This is a bug.

Filed Issue

https://github.com/vanilla/vanilla/issues/8018

API Call: /users

Error: "Validation Failed", "item.roles.name is required."

We are storing user's roles in table GDN_UserRole, making an API call to /users and getting "role name is required error", you would first check roles available Vs. what roles are assigned to users. This was a bug that is now fixed.

Fixed Issue

https://github.com/vanilla/vanilla/pull/7756

API Call: /comments

Error: "Validation failed ", "One of discussionID, insertUserID are required."

Trying to make a call to /comments without adding the discussionID which is a required parameter.

Testing an API endpoint: using PostMan or directly from Vanilla

Download App: https://www.getpostman.com/

Testing Endpoint: /discussions (doc referenced above)

Status: 200 OK.

• Open PostMan.
• Generate a new token using your local vanilla test site.

http://dev.vanilla.localhost/profile/tokens

• Create a new call

http://dev.vanilla.localhost/api/v2/discussions?access_token= ....

• Click Send

Testing Endpoint: /discussions

Status: 422

Validation error related to https://github.com/vanilla/vanilla/issues/8018

Testing Endpoint: /analytics/query

Status: 200

I'll test this call using Vanilla's API v2 swagger.

In your local setup, browse to settings/swagger

select analytics/query

{
 "type": "count",
 "collection": "page",
 "start": "2017-11-19T18:25:44.738Z",
 "end": "2018-11-19T18:25:44.738Z",
 "property": "discussion.countComments",
 "filters": [
  {
   "prop": "discussion.countComments",
   "op": "eq",
   "val": 1
  }
 ]
}

You'll need to refer to the docs for the property field, we have ~ 300 different parameters to use, the docs mention a few of them that might be useful for the client.

Testing Endpoint: /analytics/query

Status: 400 bad request

{
 "type": "count",
 "collection": "page",
 "start": "2018-11-19T18:47:19.728Z",
 "end": "2018-11-19T18:47:19.728Z",
 "property": "discussion.countComments",
 "filters": [
  {
   "prop": "discussion.countComments",
   "op": "eq"

  }
 ]
}

Request result:

{
  "message": "Validation Failed",
  "status": 400,
  "errors": [
    {
      "field": "val",
      "code": "missingField",
      "path": "filters[0]",
      "status": 400,
      "message": "filters[0].val is required."
    }
  ]
}

Filter is expecting a "val" parameter to be set. We are filtering by property " discussion.countComments" we need to specify a value to filter by.

Testing Endpoint: analytics/leaderboard

Status: 200

using PostMan

Request result

Testing Endpoint: analytics/leaderboard

Status: 422 validation error

changing start date to yyyymmdd instead of yyyymmdd

Request result

Looking at the docs for analytics/leaderboard, start parameter is expecting an (ISO 8601) time range, using a different format would cause a validation error.