The abysmal nature of monday.com API

Monday.com is a wonderful platform and it has the potential to grow even more but the current state of it’s API can have very serious negative consequences on it’s adoption by developers. The developers at Monday.com can’t implement every feature, just like the developers at Google or Apple. Imagine Google trying to create every app on the app by itself. It is impossible. That is why companies create APIs and make them available for developers to be able to create applications on their platform. Monday.com claims to be a Work OS, and the beauty about OS’s are that, they are highly extendable. We enjoy using our computers because of the flexibility of the OS that has made developers to create different applications on that. In my current view, Monday.com is striving to be an opposite of what an OS is supposed to be. For users, it’s mostly great but for developers, it’s just terrible. I’m currently developing an application and the number of times that I have encountered problems within a short space of time is just unbearable.
Let’s take the status column for example. When I create a column in the app, a column in the app, I see it right away, but when done programmatically, it requires a page refresh or board reload for the column to be visible. This brings me to one main problem with Monday.com. There is a huge disconnect between what can be done on the app and what can be done using the API. In the presentation by Vlad on opening the platform for external external developers, he mentioned that, the API is to enable client “extend the platform”, but from what I see, there seems to be a disconnect. When I make a change, I expect to see the same changes like I do when I use the GUI. This is the expected behaviour for almost all apps that have the option to use commands or GUI. Take git for example, I can decide to use the command or use a GUI. Behind the scenes, the GUI just does the same thing like command line does. This is very important for two reasons

  1. In the future, if Monday.com decides that, when a new column is created, the created column should highlight, that change will just have to made at one place and it will work for both the GUI and the API. By having a single source of truth on how state of the application changes in response to an event, everyone is kept on the same page.

  2. It makes developers at Monday.com, the users and developers using the API lives easier because, everyone is rest assured that, any change made is going to be the same for everyone.

Still on the status column, a user can create a label for Status column very easily. The developer can not. This takes me back to my point of the disconnect between the GUI and API. If there already exists an implementation to create and change labels, why is it not available to developers. That is, the OS already has the implementation for a feature which is available for the GUI but it is unavailable for the command line. How is this even acceptable?

Monday.com decides to use GraphQL for their API. In this documentary, the creators of GraphQL state why they created GraphQL. In simpler terms, they created it for a particular problem Facebook was facing. As one user notes in this thread, Monday.com is not Facebook. REST has worked and continue to work for companies making billions. Personally, I don’t have a problem with Monday.com choosing to use GraphQL but then advantage of existing protocols like REST is that, they have been used for so long and most mistakes corrected over time that, it make s them ‘easy and comfortable’ to work it. REST has been so established that, we have terms such as CRUD which are often associated with well known REST commands, that is POST, GET, PUT, DELETE. Why am I saying all these? Because with the current API, there is no option DELETE a column value. Can it be done using GraphQL? Of course, yes. Is it possible to do it using the current Monday.com API? No. In fact, looking at the requests and responses for Monday.com boards, it seems Monday.com is still using REST. So this begs the question, why GraphQL? Like I said, I have no problem with GraphQL but where I have a problem with is when the chosen technology has issues that the previous one has long solved. Still on GraphQL, when I make a request using REST, I can be ‘rest’ assured (see what I did here :wink:) that, I will receive the same results every time provided the inputs are the same. GraphQL differs from that by having complexities. This leaves the developer in a state of uncertainty because, sometime can be working just fine at one moment and the next moment, it doesn’t work anymore because let’s say, the user added more items. This is sad because, how do you even test for use cases like this? Additionally, the developers at Monday.com have done a good job by adding a complexity variable to query so can at least try it out in the Playground and see the complexity of the query but then, complexity to my knowledge only exists for query and not mutations. You only see that you have exceeded the complexity when it shows in the error message.

Talking about error messages, that is another of Monday.com way’s of frustrating developers. Let’s take this error message for example.

{
  "error_code": "ColumnValueException",
  "status_code": 200,
  "error_message": "This status label doesn't exist, possible statuses are: {0: Working on it, 1: Done, 2: Stuck, 14: , 12: , 7: }",
  "error_data": {
    "column_value": "{\"label\"=>\"x\"}",
    "column_id": "sampleColumn"
  }
}

Let’s start with the status code - 200. In the REST world, this indicates OK. But one might say, we are not using REST, we are using GraphQL. That will be a valid excuse expect that, both errors and non-errors responses return 200. So in effect, the 200 does not mean anything. As a matter of fact, almost all the errors returned by Monday.com are 200’s expect for a few. The status_code is useless at this point. Moving on to the next variable, error_message. This would have been fine expect for the last part. Until October of last year, this was the only way one could know of the existing labels, and oh boy, don’t get me started on labels. Such a tiny part of the whole application, is so difficult to work with. First, there was no way to get them. You could only get them through an error_message. In fact, Monday.com was so proud of their implementation that, they mentioned it in their documentation that, you can get them in the error_message. This would have been less painful if it was easy to get. Spoiler alert. No it is not. First. the label ‘object’ is preceded by a sentence. There is no assurance that, in the near future, this sentence will not be changed, so depending on the end of the sentence to start retrieving the ‘object’ is not future-proof. You might say, okay, start retrieving the ‘object’ from the first curly braces. Again, in the near-future, if Monday.com decides to wrap the ‘object’ in another object, like

{labels: {0: Working on it, 1: Done, 2: Stuck, 14: , 12: , 7: }}

then, suddenly, your JSON.parse (JS) fails again. Now to the ‘object’ itself. I keep putting ‘object’ in quotes because the last part is not an object but a mess. It makes you wonder, is it too hard for Monday.com just give a valid object since that was the only way to get the available labels anyway. Seems like the main aim is to just frustrate you as a developer. Wouldn’t it have been better to completely extract the labels object and put in a separate property all together so that they could be accessible by some like data.labels? Lastly, what does "column_value": "{\"label\"=>\"x\"}", even mean?
Isn’t this better? "column_value": "{\"label\":\"x\"}",. That way, the developer hasn’t have to replace =>. See why initially, I mentioned that, it seems Monday.com intentionally is trying to drive developers from the platform?


Back to the labels, currently, I can duplicate multiple items on the board just fine, but when I try to update several labels for several for a single status column, it fails sometimes due to complexity. Makes me to wonder, duplicating items which can contain several column_values and updating the label of a status column, which is more expensive? Why can I duplicate multiple items ( which sometimes takes some time, which is understandable due to the multiple changes being made) but have problems updating labels of a single column.


Next is documentation.
When I say it’s terrible, I’m just been kind. For starters, which good documentation doesn’t have a search box?
On small screens, like that of my laptop, there padding on the left sidebar which makes it impossible to even see the words




I always go into the developer tools to remove the padding myself.


This is it with the padding removed

So much better.

Still on the documentation, most users have been asking for improvements to existing features and even new features. The Apps & Developers community on community.monday.com is full of such requests. The Changelog doesn’t reflect the eagerness of the Monday.com team to implement the needed features. In most cases, only one change is made for a change log. One. Don’t believe me? Open the Changelog section on the documentation page and see for yourself. This is nothing short of pitiful. Additionally, the Changelog isn’t a source of information about a feature, the documentation is. Ask yourself, how many times have you as a developer visited the Changelog to find an information about a feature. Most people I believe rarely visit the Change log of software products. Why? Because the documentations are updated to reflect the changes in the changelog. Imagine my surprise when I found out that, Monday.com had finally released support for getting label colors because I saw it in one of the community posts. Then I began to wonder, how come I couldn’t find it in the documentation. Guess what? It wasn’t in the documentation. Surprise surprise. It was buried in one of the change logs. :cry:
Documentation organization
For comparison, let’s look at these documents from Shopify and Stripe. For starters, these are billion-dollar companies which are still using REST. Even if we look at a GraphQL documentation on Shopify, it still beats what Monday.com currently has. These documentations are well-structured. I can’t say the same about the Monday.com documentation.


The Marketplace.
Most often than not, I find myself navigating away from the marketplace unknowingly because of the way the routing on the Monday.com marketplace is designed. When a user clicks on 'See all", and a new view is showed to the user, years of using the internet has shown as that, if you want to see the previous view, use the back button. Most people like me don’t even think about it, we just click the back button to go back. But once again, Monday.com is different. It turns out, when you click on ‘See all’, the URL doesn’t change so when you are done and want to go back, you have to look for a button that you initially weren’t even aware was on the page, the ‘home’ button to be able to go back to the previous page. It gets even worse when you are on the bottom of the page. There is no way to go back unless you scroll up to find the home button.


Once again, for comparison, let’s look at the app stores on other platforms, for example Google Playstore, Shopify app store, Xero apps, etc. Once again, the difference is clear.


Surely, there is more to talk about but I would like to end here. But before I go, there is a problem I’m currently facing that I haven’t still found the solution for. I’m trying to change the status color for multiple columns. In my use case, it would have been easier if I could delete the column and in response, I could get the delete column and get the deleted column properties such as it’s index and then re-create a new column. This will serve as a form of reset and then update the new column with the needed updated. Again, this would have been a fairly easy task if Monday.com has change_multiple_item_values just like it has change_mulitiple_column_values. Once again, such a functionality is already available on the GUI, like, converting a column to anther type, changing the label on a status, etc. Both actions change multiple item values but sadly, you can’t do that using the API. In trying to solve my problem, I decided, to reset the value of that column ( a Status column) of each item before running the new update. This lead to other problem, which is, over ceding complexity because of the previously run ‘reset’. I’m currently stuck and don’t know how to tackle this problem. If anyone has an idea on how to do that, I will very much appreciate your help.


In conclusion, I think Monday.com is a great platform and the developers are working hard to hard to make the platform better but there is still a long way to go. My suggestion is to have a team that (if it doesn’t already exist), is sorely decided to handling developer-needs. It ranges from, making sure the API is well-structured and up to date but most importantly, that is rich in features so that there is no disconnection on what can be done using the GUI and the API. I am sorry if this was a lot to read and if I may have sound harsh but after several pain-striking moments with the current state of the API, I felt the needed to put this out there. Thank you.

4 Likes

Oh, my God, yes. All of this.

Disclaimer: I don’t have formal programming training, so the first 2/3rds of your rant here was on the edge of my awareness but not something I was looking for or able to articulate possible solutions.

The documentation for the Monday API is… hot garbage. If you check my post history, you’ll find a few instances where following the documentation actually caused errors in my queries, especially when I was trying to change a query from capturing one column to capturing multiple columns and parsing the responses. Honestly, at this point, the only workflow that works for me is brute forcing my way into the results I want via the Monday playground and then copying that into a text string in my program. (Pro tip, OP. Set a test item with a column status that you want the index of, and then query that item in the playground to get the index value. Better yet, if you’re querying data, just replace “Value” with “Text”, to return the text of the status as the response value. Avoids some coercion or needing to maintain a dictionary of color-value relationships, in case some middle manager gets a wild hair and recolors everything to be more feng shui. I think you may be able to use this to set values, too… haven’t tested it yet, but the error message workaround can go suck eggs.)

The problem with a system this large, when you have this many people adding to it and not a central control point like I have (and I suspect you do too), everyone institutes their own naming convention. Periodic code reviews and refactors have saved. my. bacon. on my own programs, but they are always greeted with far less excitement than feature announcements. I wonder why. :slight_smile:

3 Likes

Hi @kolaai

Welcome to the community. I could add at least the same amount of information about these topics. With regards to changes and change log, every time a change appears here I like to test it. Guess what: I find bugs in almost every change made to API and/or apps platform. Sometimes it goes like this:
me > support: looks like this ia a bug
support > me: it works, have you read the documentation…what?
me > support: here is a video, screenshots, my code and the debugging output
support > me: this is a know bug
me > support: when will it be resolved
support > me: we can’t give a date
me… giving up

I remember the famous words: with the apps platform and the API you can build everything why have build yourself…huh…really? After long discussion I got: ohh, but that piece of functionality runs in God mode :frowning: , you don’t have access to it.

2 Likes

I also use the Playground just like you do and then try different values before copying and pasting into code. The whole development process feels like a hack.

1 Like

It’s a sad state of things. It seems like developers are seen as an after thought and not an integral part in making the platform as wonderful as it should be. Every easy thing is hard to implement and easier things are even harder. Very sad.

1 Like

Hey @kolaai,

It takes quite a lot of effort to write a detailed post with so much feedback, and I really appreciate you taking the time to do it. I interpret it as a genuine desire to make our platform better, so thank you.

I won’t be able to do respond to every point in detail, but I wanted to give you some context about the efforts we’re working on internally.

Again, I really love the detail you put into your message!

API Documentation

We know that the state of our current API documentation is a pain point for many developers, and we’re in the early stages of overhauling the docs completely.

Our goals for the overhaul include:

  • Make the documentation easier to navigate (including a dedicated search bar)
  • Improve the accuracy/clarity of the information in each section
  • Add more code examples
  • Unify our apps framework documentation with the API docs
  • Make the docs more responsive to feedback from our developer community

We don’t want to rush and create more problems than we’re solving, so the timeline for this change is more on the scale of months and not weeks.

Our team also is building more “informal documentation” (guides, workarounds, etc), which we’re putting in a special section in our community. We’re hoping that these resources bridge the gap between the official docs, feature announcements, and the common issues that developers run into while building their apps: Dev Announcements and Resources

Feature Completeness

We have a dedicated R&D team that is responsible for maintaining our dev tools and API. Like you mentioned, we can’t develop every feature – and we won’t get to a place where every feature in the GUI is also available in the API. But there are some core functionalities that we can prioritize based on our users’ needs.

The primary way we decide which features to add to our API is through user feedback. Therefore, I really encourage you to go through our API feature backlog and vote for all the features you’d like to see in our API: Developer Feature Requests

If you want to read more about how we decide what to develop and which bugs to fix, check out my explanation in this thread: monday.com development priorities

Breaking Changes

We strive to not push breaking changes to our API, since we have a whole ecosystem of apps that rely on it. That said, we are human and do make mistakes. If you see any changes to our API that break the functionality of your app, please let our team know by posting in the community or reaching out to appsupport@monday.com.

Tips for using the API more effectively

Here are some tips and solutions to the topics you brought up as well.

Searching the API docs – we built the current docs as a single page so that devs can search with CMD-F/their browser’s “Find in page” functionality. However, there’s still room for improvement as this doesn’t provide results from our apps framework docs.

  • API Playground – I rely on the API playground as the main way to test the API as well.

  • 200 status code – This is actually a recommendation of the GraphQL spec. The status code reflects whether the HTTP transport was successful, and the 200 status code means “We received your query”. Any errors that arise from the GraphQL layer are surfaced in the response body (as you described).

  • Status labels – Did you manage to figure out how to retrieve the existing status labels from a board? You need to use the settings_str field on the Column object.

  • Change status color on existing column – I’m afraid this isn’t possible at the moment. Our API doesn’t allow you to manipulate labels in status or dropdown columns. I see you’ve already voted for this feature in our requests backlog! Define status labels via API

I hope this gives you some additional context about our priorities. Do let me know if you have any more questions – always happy to share our efforts with users who take a genuine interest.

5 Likes