API Workaround
Hello everyone!
Some of you may already be aware that the APIv2 page in the Dashboard is having some difficulties at the moment. This issue is being addressed and we're expecting everything to be back at 100% soon. The problem is around the interface of our APIv2 page (called Swagger) - the API itself is functioning normally.
Still, we want to make sure no one feels blocked from using the API while the interface is worked on. This post should help introduce you to API Platform programs, get you familiar enough to do basic calls and then I have a live example of anonymizing a user's mentions using two API calls at the very bottom.
GET Calls
These are the easy ones. For any GET call that you need to make, simply find the call you want to make and copy it to the URL bar of your browser, adding: "/api/v2/" after your community's domain. You will replace the {id} with the DiscussionID of whatever discussion you're looking to get information on.
So, to use the Success Community as our test subject, you could copy the following to the URL bar: https://success.vanillaforums.com/api/v2/discussions/74/
And that would give you the API return for our Release Notes Update discussion.
If you needed a more specific filter, you could add ?expand=all after the discussionID in the above example to get extra data.
Sending an /api/v2/ URL to a user that normally wouldn't be able to access that data will result in a Permission Error, so if you're encountering that problem, make sure you're signed into an account with the right privileges on your community.
POST/PATCH/PUT/DELETE Calls
These are the tricky ones and I don't recommend trying unless you are moderately comfortable working with API.
First, you will need to download an API platform. The Vanilla Support Team uses Postman (free to download) and I'll be using screenshots from that program in this post, but most API platforms will have a very similar setup.
When you open Postman, you'll be greeted by something like this:
There's a lot going on here, but we really only need to be familiarized with a few parts.
We will need to expand on this a little, but at it's most basic, this is all you really need to know to use Postman.
As a test, use the same Success URL as before to perform a GET in Postman.
We get a permission error. Why?
Because Postman doesn't have permission to access the Success Community with the same permissions as your user. Since this is a private community, the same thing happens to Postman as would happen to a guest user - they are denied access.
Our Success community managers have opted not to allow our member users to generate API tokens, but this is something you can 100% play with on your own community. This article walks you through the steps of generating an API token for your user but I also made a gif that shows the same steps - you should start from your user's profile page on your community:
After you hit 'Generate,' the screen will refresh with a string of random characters. This is your Access Token or API key, and how you can get API Platforms (like Postman) to access your site with the same permissions as your user. This is important for any administrative tasks you may need to do with the API.
🛑🛑🛑 Entering Security Checkpoint 🛑🛑🛑
Never share that API key with anyone. These are very powerful tools. If you are an administrator, it could potentially give someone unlimited access to your site and it's data. If you feel you may have accidentally provided your key to someone or posted it in a public channel, please delete it immediately:
Deleting a token will invalidate it. It's free to create new tokens and a best practice to delete tokens that you aren't actively using.
Better safe than sorry.
🛑🛑🛑Leaving Security Checkpoint🛑🛑🛑
Now that you have an API Key/Access Token, you can enter it into Postman by clicking 'Authorization,' selecting 'Bearer Token' from the dropdown menu and then entering it in the available 'Token' field.
Now, whenever you use Postman in that tab to send API commands to your site, it will attempt those actions as if it was your user. We're set for most of the things you'd probably need to do with the API in Postman.
Using Postman (kinda) Live
The biggest concern I've seen during this Swagger issue has been anonymizing user mentions for GDPR requests. If you've followed along the rest of this post, Postman should be configured properly and all you need to do is copy the command from the APIv2 page in the Vanilla Dashboard to Postman:
This would translate to something like: https://yourcommunity.yourdomain.com/api/v2/user-mentions/[USERID]/anonymize
Remember to adjust the API action you want to do in Postman before hitting send (GET, POST, PATCH, DELETE, etc)
In this next gif, I'm going to show anonymizing the user mentions for UserID 14 on my test site.
So, first, I did a GET call to see if my user 14 had any mentions.
Once that was confirmed, I did a POST call to delete those mentions.
Each time I make a call, you can see the payload information at the bottom update to show the information that I was requesting or confirming that it had carried out a requested action.
Summary
That's all there is to it. It gets a bit more complicated if you want to try things like Analytic API calls or creating posts via the API, but since the UI for both those actions is fully intact, I don't see a need to dive that deep.
Essentially, all you need is the API Platform of your choice. You need to authorize your call with an access token from your user and then you need to perform the correct API call to do whatever action you need.