Hello,
with what I’ve seen so far, the application is really great, technologically advanced and comfortable.
However, one lacking feature kind of shadows this all: REST API.
Before you go ahead and say “oh wait, there is an API”… no, there isn’t. There is a java application that has endpoints exposed over HTTP, but that is far from a RESTful API.
I say this for the following reasons:
- If you go to https://bluemind.net and follow the link to the API, you get redirected to BlueMind REST API browser where you’re gonna wait a nice while (2-3 min) looking at this message pending:
- If you try to see the python example API calls you get redirected to https://forge.bluemind.net/stash/projects/BA/repos/bluemind-samples/browse/python-api-examples, which does not work. After manually browsing forge.bluemind.net I could find the examples, but they are worthless as they are simply Java Code sideported to Python.
- Lately I see you added some example as to how to get an API key, but most of it is focused on and around Java. However, when you go to your instance API you see a lot of variables mentioned, like
containerId,uidand a lot more, but they are not explained anywhere. - The documentations have lots of errors everywhere, makes me wonder if anyone even analyzes the pages anymore when they change them, or just throw stuff at it hoping the users will get it. Example from User API | BlueMind doc :
curl -X GET --header ‘Content-Type: application/json’
–header ‘X-BM-ApiKey: <auth_key>’
–header ‘Accept: application/json’
–header ‘X-BM-ApiKey: <auth_key>’
There are 2 errors here. The header auth key is repeated, and the new lines are not escaped. If someone would try the intuitive thing to do, copy paste this and run it, it can not work.
All of this and other things I noticed lead me to the following facts:
- BlueMind does not have a REST API, but only Java endpoints exposed over HTTP. That is nice if you’re into Java, but if you hate it with your whole being (like me) then it’s very not nice.
- Even the existing API is actually just pieces of software put together and completely not documented, because the existing documentations are all wrong. (At least the python API client documentations - completely wrong)
Hence the feature request: Can we have a clean API?
P.S. Since the post may seem a little inappropriate, I will add one more example as to why this is such a big problem.
Let’s say you want to update the ICS of a user with an event. First of all, already looking for the API endpoint that does this, it’s very unclear which one does what:
Is it IVEvent? Is it ICalendarsMgmt? ICalendars? ICalendar? It’s IVEvent.
Now let’s dive into the documentation of the IVEvent:
Oh well, ok, I should probably look for a containerUid. Let’s go ahead and browse blindly through all the endpoints that we know are related to calendar, to hopefully find something that could help us find a containerUid. Oh look, ICalendars has an endpoint _search. Let’s see it’s documentation:
Oh ok that wasn’t very useful. Let’s go ahead and try stuff.
curl https://bm.example.com/api/calendars/_search?query=test -H 'X-BM-ApiKey: ...' -X POST
{"errorType":"NullPointerException","message":"Cannot read field \"containers\" because \"<parameter1>\" is null"}
curl https://bm.example.com/api/calendars/_search -H 'X-BM-ApiKey: ...' -X POST -d '{"owner": "some_owner"}'
{"errorType":"NullPointerException","message":"Cannot read field \"uid\" because \"<parameter2>\" is null"}
Looking one more time at the endpoints, one does notice the screaming one: “ICalendarUids”, so hopping right in:
curl https://bm.example.com/api/calendar/uids/<user id which I had to also query for>/_default_calendar -H 'X-BM-ApiKey: ...'
"calendar:<uid>"
So we have the auth key, the user UID, and the Calendar UID. Now let’s finally upload the 1kb file that should really not be so complicated to upload programmatically since it would be easier to setup an SSH connection to the server and just drop in the file instead of all this.
curl https://bm.example.com/api/calendars/vevent/<user uid> -H 'X-BM-ApiKey: ...'
{"errorCode":"UNKNOWN","errorType":"ServerFault","message":"container <uid> not found"}
Wait what, you thought it would be so easy as to get some uuids and give them in? No no, we want a container UID. What is that? I have no idea and this point I don’t want to know.
Ok I gave it one more try with the nice net.bluemind.core.container.api.IContainers:
curl https://bm.example.com/api/containers/_manage/_list -H 'X-BM-ApiKey: ...' -X POST
--> 687 characters of JSON string (3642 rows of formatted JSON).
curl https://bm.example.com/api/containers/_manage/_listforuser -H 'X-BM-ApiKey: ...' -X POST -d '{"owner": "some owner"}'
{"errorType":"NullPointerException","message":"Cannot invoke \"Object.hashCode()\" because \"key\" is null"}
And more I really don’t need to know.
), but we don’t have a clean high-level REST API yet. We have plans for one, but it is not here yet, at least not until we’ve reached some maturity with our technical stack, which is currently evolving to deal with huge installations (after a long list of previous evolutions). Sorry for this.