Mattermost, Inc.

Completing API Documentation

Hi everybody!

I hope that everyone’s night is going well. So I have a couple of small questions.

A little about me as a user for context: I am currently trying to develop a webapp which requires a messenger system similar to slack. While I was doing a little bit of research, an awesome friend of mine suggested to me to checkout Mattermost, and it seems to offer exactly the messenger services that we need. So now we need to figure out how exactly to integrate Mattermost with our own backend.

Now, I would like to give a small disclosure: much like Jon Snow, I know nothing. Chances are that the issue we’re having is an imaginary one (like my friends) and there is already an answer out there (maybe the webhooks? I must admit that I don’t understand them fully (and would love a clarification), but I don’t think that they have the full scope of functions we want).

So moving on, we’re trying to write the backend in node (using express), and what we would like to have is a running Mattermost server which we can call to access several of its services services. As such, we want to use the Mattermost API to perform certain actions. Now here, I would like to be abundantly clear: we are looking for the Restful API, not a driver, and the most complete one at that. Not only do we want to get and post messages, but we also want to view teams, create teams, register users, etc… An example of what we are currently looking for is something similar to, for example, the imgur API. Again, we could be missing something very important right now, so please call us out if you already have an answer.

We looked in-depth at the current API page, as well as all of its links (incuding the one to the Web Service API), and we found the documentation kind of lacking-- we now know how to do an authentication call, but that’s pretty much it. Our research did not stop there, and we tried to look at issues raised, feature requests, forum posts (there’s a couple more unlisted references), and it seems that there is a general consensus that there is currently no such documentation. The sources we looked at generally instructed us to inspect the source to understand the endpoints, and I think that we found them:

Sadly, none of these handlers (and the others not seen) seem to have any documentation. My question then is: have I been wrong in my train of thought so far, and if not is there any objections to me to try to fill in the documentation? I, of course, do not out-right expect for such documentation to be fully accepted, but would you guys, the Mattermost in-house developers, be amenable to considering such help? This is a really cool project, and I think that such documentation can go a long way for user adoption.

So yeah, that pretty much covers my rant. Sorry that it took so long-- I wanted to be very clear and thorough. Thank you for your time, and have a nice night!

Would highly appreciate the help with documenting the Web Service API.

You can look at the Golang and Javascript drivers as a start to figure out how the Web Service API works

Review the contribution guide to see how things work and make a pull request to the Web Service documentation when you feel ready.

You can receive feedback from the community on your PR, it might take a bit of revision but once it’s in your work will help countless developers around the world :slight_smile:

Hi,

You are right in that the API documentation is severely lacking, and you’re on the right lines about where you’re looking. Personally, I found it easier to use Chrome’s developer tools to analyse the requests and responses made by the web interface (which still uses the API), then augmenting that with browsing the source.

I’m hoping to contribute some stuff on the API to the documentation once I get a bit more time. If you do have any specific questions on parts of the API though, I’d be happy to try and answer them (though I’m far from a definitive authority on it).

Hi it33, hi limey98,

Thank you guys for your guidance and encouragement, I really appreciate it :slight_smile: . Right now I’m in the middle of work and classes, so I don’t want to get everyone’s hopes too high, but I promise that I will try to write as much of the documentation as I can. it33, I’ll definitely review the resources you mentioned. limey98, I was currently thinking of using postman to test out the requests and responses-- I take it that chrome offers more tools, specifically one to analyze the web page (or is it just the classic inspect element?)? Thank you both again, and have a nice day!

Hi Again,

So I’m currently documenting the handler middleware (I figured that before I deal with the endpoints, I must understand the handlers and their flags), and I had a couple of questions:

  1. What’s the license endpoints for (InitLicense in api/license.go)?
  2. What is the purpose of the isUserActivity handler flag? Does it just specify whether an action should update the session?

Anyone knows if there is a possibility to flag a message using the API?