Introduction to API v2 - monday.com for Builders | monday.com

um we're gonna go through the API today I would love for all of you to take a minute or two to fill out our welcome form we've got some 600 people on here I would love to know who's on what you do you can just go to that URL cut ly slash Monday - API - webinar go ahead and fill that out and we can then get started with understanding who's here and this is a Monday form the the Welcome forum and it'll bring and whenever you fill it out it's gonna populate on to this board and Wow we've already got a bunch of people who've already filled it out I see key here is in marketing and does web development got a few folks from the c-suite in education and travel a bunch of people on in IT Telecom another sass person in implementation hi everyone ooh amazing we've got more and more people joining as we start this is wonderful to see so many people joining us as you all fill this out and I'll come back to this in a little bit let's go ahead and talk about our agenda for today so to begin with we're going to talk a little bit about our API at a high level why do we want to use our API what is an API and how can I use it to connect Monday comm to other tools after that I'm going to go through a bunch of examples we're gonna start with a couple of examples of applications that we've already built I'm just showing you how you can pull data from various places into Monday comm and also create more flexible integrations and automations after that we're gonna get kind of technical we're gonna talk about graph QL which is the technology that our API is built on and we're gonna then make some API calls so I'm gonna structure this so that we start high-level and get more and more technical as we go down and what that means is if you aren't super technical that doesn't matter go ahead and stay on and watch us do these examples because I think you will get a lot of value from the first little bit so let's get started I want to go back to that form and see what we have filled out who's in the room with us so right here we've got a bunch of people a lot of people in software development project management a lot of different a lot of different industries right here let me go ahead and turn this into a chart and we can see if there are what the most number of people come from so we see that a lot of folks are coming from IT from marketing from manufacturing as people are joining this this chart is is getting updated but this is super cool to see that we've got so many people here in the room with us and working with us on this webinar so yeah let's get started let's talk a little bit about our API what is an API and why should we use it so to begin with our API is a layer that you can use to feed data in in and out of your Monday comm account so this could be either from homegrown tools that you use internally from other SAS applications or even from Monday comm itself you if you want to use your API to take data from one board and put it on to another board you can definitely do that as well really what we want to do with our with the API is one of build integrations that will break down those data silos right ensure that your teams can connect across different platforms so you don't have to worry about only the customer success team being able to get insights from Zendesk tickets for example we also want to minimize grunt work you can use the API to take manual work out of the equation send data from one place to another instead of having to construct a new report every six weeks by exporting three excel documents doing a vlookup to add everything together and then sending it to your director you could write an integration that automatically does all of that for you and puts it on the Monday board you can even create charts like we created just now and have that report automated within minutes and you could even build custom workflows so what I mean by that is having different workflows in Monday comm that are really adjusted to your needs if you have a board where you assign a contractor on one board and you want it to appear on the contractor specific board you can do that with our API you can create all sorts of custom workflows to ensure that you are expanding the limits of Monday comm and build your Monday comm workspace to work for you really the way that I'm I think about our API is it makes Monday calm more Monday commish it makes it more flexible and makes it easier to communicate with your with your team and it just makes everything better and everyone happy so let's go ahead and show a couple of examples I'm going to show you three examples of integrations with our API now because of the technical difficulties in the beginning I will need to set some stuff up but I'm gonna go ahead and do that on the fly and I'm gonna show you how I do it as well so those of you who are more technical can can understand what's going on so I'm just gonna share my screen again and you'll see my terminal window right here I'm just gonna use it to run some code so to begin with I'm just gonna go to my API webinar folder and we're gonna look at our first integration which is a Zendesk integration we're gonna talk a little bit about this integration before I show you what it looks like so this is a board where I want to see all of the tickets that hide myself deeper Amanda comm have touched in the last week the data in Zendesk is pretty siloed in that only customer success can access that application and I want to pull that out and show other stakeholders in our business what I've been working on for the last week who have I've been talking to what have I been talking to them about and I also want to see historical data I want to see stuff from the last week and not necessarily a real-time sync this will let me track the work that I'm doing in a personalized way and really showcase the work that I'm doing as we speak so let's go ahead and run this application I created a Python script I'm gonna send you the code for all of this in a little bit after this after this webinar but let's go ahead and just get started so when I run this code it pings the Zendesk API to get a list of all of the tickets that I have touched in the last week based on a search term after that it goes in and it adds every single ticket the subject of the ticket the status whether it's new it's open or if it's a ticket that's already been solved in here with a link directly to the Zendesk itself you so this is super cool I would love for you to put in the chat what you think give me a give me a smiley face if you think that's cool awesome I see a lot of smiley faces we are getting started good good stuff I see that there are lots of folks who want to do this with freshdesk as well you can do it with freshdesk as long as the other application has an API you can pull this information from fresh tests API then you can write an application that sends this data to Monday comm using our API I remember that our API is just a layer that you can use to send data to Monday comm so it doesn't matter where that data comes from you can just send it directly into Monday comm you could also do that with JIRA and a bunch of other applications if you need in terms of other questions do go ahead and put any ongoing questions in the Q&A section there's a little Q&A chat we do have 600 people here there's gonna be a lot of chatter in the chat and I will probably miss your question so go ahead and put that in the Q&A section instead we can put all the questions in one place so this is the Zendesk integration that we showed you this is awesome for pulling data in in one shot based on historical trends I want to show you a couple more examples that are Monday to Monday automations though the next integration that I'm gonna show you is based on a real use case that our that one of our clients that we talked about we and it's it's a pretty common use case so this client uses a lot of different contractors these are people who are external to their team so they don't have access to the entire Monday comm account they only have access to one shareable board that is just a list of all of the tasks that they do and this is a board that kind of looks like this for deeper Oklahoma click contractor it's just a list of current project as well as what's done now they send tasks to be contracted from a high level board and their management team tracks this this is the internal project board they use this to lift out everything but we're working on right now and they use a drop-down column right here to assign the contractor what this integration will do is it will take the data from that drop down column using a web hook and send it to the individual contractors board if it exists so we're using a web hook right here in the integration section and I'm I'm sending this to an application URL which actually has broken now because I had to restart my computer and we're gonna we're gonna see how you set this up as well so I'm gonna go back to my terminal window I'm gonna go to the folder that this exists in which is called cross coordination and this is kind of an ongoing integration that will where Monday comm will ping my server to when the drop down column changes and then my server will then do something with that information if it's a contractor if the contractor has changed so what that means is there are there's a back and forth so I do need a public URL that this this integration can connect up to or rather I can send the web hook to but for that I'm just gonna use n grok this is a I think one of my favorite tools in terms of in terms of creating public URLs what this will do is it'll just create a public URL that you can then copy and paste into the web hook and it's wonderful for testing and I'm also going to go ahead and run this code okay so now listening I'm gonna go in and update this webhook so a webhook will basically send data to a URL when something painted in this case when a column changes it's gonna send a payload of information to the URL that I specified so now this is this has been sent now let's go ahead and add some items and get this operation right let's go ahead and fill out some projects do y'all have ideas on the kinds of projects that we would like to fill this task wolf please but like I'm gonna take three or four so if everyone gives me one I'll have 600 plenty to deal with implemented Monday comm API build freshdesk integration eat Paco's I love it and have a beer I like these last two alright so we've got four different items that I want to assign contractors to I'm now gonna go ahead and assign D Pro to this to this item what I expect to happen is that item is going to then go and appear on the D pro board so let's go ahead and do that all right so some stuff is happening let's go ahead and open up deep bro and boom in bloom on Monday calm API has appeared here basically what I'm doing is I'm watching for a for a web hook and then creating a new item on whatever board it should be created on I can also do that for Eddy for building the freshdesk integration and for eating tacos and Eddie's board will also get updated what's what I particularly like about this integration is if I add a new contractor I don't have to worry about creating a new board for them manually because the integration will do that for let's go ahead and create a new contractor I'm just gonna use one of the last people on the chat and I apologize misael but I'm gonna use your name so right there and when I assign them to a an item it'll create a board for them go ahead and see that here if I search for a mu tile boom their board has been created if you open the board you'll notice that it is created with the same template that the other boards are created with and have a beer is already populated so I don't have to worry about editing misael to a new board creating a new board etc etc all of that is already handled by the integration I'm gonna move this to the folder that we've been using just so that we keep everything in one place and now I can add missile to a bunch of other things too so if I wanted to create coffee and add missile to that one that connection was gonna happen it'll work so missile will now get coffee there as well this is a super cool integration I thought that the use case was really really relatable and I thought I'd share we're we are gonna show you so after this email after this webinar I'm gonna send an email to all of you with step-by-step instructions on how to set this up I've got a mid hub repository that has all of these examples listed in there as well as instructions on how to set them up so if you're looking for any of that Hank in the next couple of days I will send that out if you can't wait and need it ASAP you can always to reach out to support it Monday comm and they can do that you all right and a few people have questions about this about this particular integration I will handle them in the Q&A right at the end do go ahead and put them in the Q&A section well did I look at them because otherwise this will get lost in the chat all right so now we've gone through two examples one where we're taking data from another platform then desk in this case and bringing it into Monday comm in a pretty structured way in a very custom way I only want the last week of tickets in here and I can do that using our API and I've got another use case right here where I'm creating an ongoing automation between Monday comm boards and I'm doing that in a really customized way based on the workflow that I want instead of maybe the workflow that someone else has given me so we can really use this to create custom flows the third integration that I'm going to show you is not work-related at all it's tic-tac-toe just going to show this to you let's go ahead and quit the previous integration that we created and go back to to the to the folder that this existed and just like the other just like the other application what I'm going to do is I'm going to run an application server right here so this is on port 8080 just gonna copy this web hook URL start the application you and put the webhook in here okay and I think something messed up so I'm gonna just quit that and run this again oh I know what the problem is this is the wrong version of tic-tac-toe this is the version that I uploaded to github so it doesn't have any of my API keys and stuff so let me go ahead and fix that just give me one second while I traverse my entire folder structure all right let's see if this works all right now the moment I hit play it cleared the cells so I know this is working amazing and this is tic-tac-toe it's exactly what it looks like the human player plays circles so if I try and play an X it's gonna tell me nope you can't play X and I'm just gonna put a circle and then the computer's gonna play a next I'm gonna play a circle right here let's see if the computer bleeds me nope not at all this is quite a stupid computer and I'm gonna put a circle right here and boom I win tada done so that's Tic Tac well the way that this works is we're using that web hook again to listen for update from boots board and every time an update is made I'm just using the integration to update a new a new status column based on what was in there so if I play a circle here then the integration is gonna play an X somewhere else and not here and so on and so forth so we've got that back and forth going again and we've got it going because of the web hook yes someone in the chat said that AI won't be able to take over the world and rule humans because it's not super smart and this is proof of that and I totally agree this is just proof that the robots will not take over okay so those are all of our examples I hope this was helpful in understanding how the API can make things happen and get those creative juices flowing in terms of what what you can do with the API to really expand your use of Monday comm to other use cases we're now gonna talk about graph QL we're going to talk about our API get a little bit more nitty-gritty but just so that we can talk through the technical document portion I'm gonna go ahead and close this by the way and open up some slides so let me go ahead and hit present so to begin with our API is built on graph QL now you don't have to read through this yet we'll come back to this in detail but graph QL is an application layer that uses that lets you take the data in your boards the relationships in your boards and get data based on those relationships I really really like graph QL because it lets you leverage those relationships to get related data and I'm going to show you kind of what I mean in Monday comm so let's go ahead and open up a board and let's talk through some of the relationships on this board because those relationships are also maintained in our API but we begin with of course this is a board what board itself has some details that are specific to this particular board such as the board title the board ID will be confined in the URL and of course via the API and some of the other configuration such as having groups each of these groups it's also an object in and of itself right a group is important it contains items it has a color it has a position on it and every group has items in it every board also has items in it so we've got that relationship between the board items groups and as you go down the item we've got columns and you've got three different columns here each column has values inside it so we've got a column value and based on the type of the column so the person's status mate whatever data inside this column is different right so a person column doesn't have the same kind of data that a date column does because of course people and dates are different so all of this is exposed in our API the column itself also has some some information in it right it's got a title got some column settings it's gonna type there's a person columns to status column and so on and each board also has a set of of columns so all I'm trying to say is that there are are pieces of data in Monday comm and they all have relationships you can use a board to get the items on the board you can take an item and want to get all of them values on this board and based on our use case and based on how we as humans interact with with platform these relationships are important well that also mean is it's important to be able to get data in a way that preserves and leverages these relationships and that's what Monday comm that's what graph QL is super good at let's go into some nitty-gritty and go back to that board I go back to that presentation slide sorry and talk through what you're really doing when you're making an API call in graph QL so I mentioned earlier that graph QL is an application layer between you and Monday comm what this means is a little bit different from other api's such as REST API is that you're thinking of it's not a set of resource URLs instead it's a it's a layer that you can send a query to similar to if you would send an SQL query or something like that based on the data inside that query how the query is structured what you're specifying in the query you're gonna get different pieces of data and this is based on the relationships of the data on your boards or in your account and what they represent so at a high level every object in Monday comm whether it's a board it's an item it's a group they all contain fields when an item for example has an ID a board has an ID a name and it also has I ton it and each of these fields can be a primitive so a string or a or an integer this is what's showing up in purple or it could be an object itself right which means a board could contain items and if those items contains an ID that's what I'm showing right here where your query is structured in the same way that a graph would be structured right where you were getting data from one object and then possibly also nesting on other object within it so yeah you can in your query you're specifying what objects in fields you want to return and you can return this at the entry point for this is always query and then after that you can go to boards you can search for items and so on and so forth and you can for each of these items they often have an ID so you can just query for the ID and get the ID back if I want the IDS of every single board on my account I can do that using good query but yeah so this is a query um I don't want to get too in-depth with this I just want to I just want to show you the high-level head space that you want to be in when you're thinking about our Monday comm API there's a ton of documentation that we'll go through in depth how to construct these queries I just want to explain that graph QL we're thinking about objects and were thinking about graphs and not necessarily thinking about resource URLs like you might be thinking about in arrest another thing that I'd like to point out is that the way you structure a query is you start with query and then you put in the object that you are trying to ask for so I want to get boards I want to get some kind of data on the boards and specifically what I want to get is I want to get the ID of the board I want to get the name of the board and I want to get all the items on the board and for each item I want to get an idea the way that I like to think about it is each word in here is a node in the graph and each curly braket is an edge and so we're using this query to kind of transfer from one object to another and so on a lot of people are asking about the presentation and recordings and just to clarify I will be sending this recording and all of the information that we're going through because I know we're going through a lot to everyone who is on here and also the people who are not on here just to ensure that you have all of the data and can recreate all of this because it is complicated and really the intention of this webinar is to get you started to get those creative juices flowing and to kind of open the conversation for more talks about the API alright so now that we've got this anatomy of a query down and we'll go through some more examples of queries in a little bit let's talk a little bit about the difference between graph QL and rest just quickly in order to put some preconceptions out of the way so a lot of API is that are out there our REST API s so what this means is they're structured differently the way you get data from them is different from the way you get data from graph QL I just want to I want to lay it lay out what those differences are especially begin with we only have a single endpoint for our API it's called API down Monday comm slash v2 unlike aggressed where there's a different end point for each operation or for each resource where you just only have to worry about one URL you just point every request to that one URL same with the HTTP method we only are looking for post requests unlike rest where you can send a get to get a resource you can post pain or something and so on and so forth we only care about posts the data that you want to send to our API is gonna be in the post body unlike in rest where you often send it in the URL parameters if you send your parameters as in the URL our API is not gonna accept that and we'll send you a 400 did you go ahead and send it in the post body instead I'll show you some examples in the future read operations our queries so in the operation that you write out you're gonna use the word query at the top and that's basically the same of the get endpoint and rest and then for all right operations you're going to use a mutation this is a specific word for graph QL and it basically means I'm changing data and this is the same as if you were to use a put post delete and so on in rest to modify data all of that is in a mutation and best of all what's cool about graph QL is that you can return a custom set of data very easily while in rest you're kind of limited to the specification of how each endpoint is so maybe each endpoint will always give you the same five fields and if you only need two of them you will still get the remaining three regardless with graph QL you don't have to worry about that you can say I only want to get the idea item I know that it has a name I don't need it right now and we won't give it in you will only give you the data that you asked for which makes it super flexible and makes it very easy to parse out the beta that you need and not have to worry about extraneous information all right if you have any questions about all of this remember put that in the Q&A section we will be going through the Q&A right at the end there are 40 or 50 questions in there so we may not have time for everything but we will try and get through as much as possible and if your question doesn't get answered I'll talk to you about how you can get that end all right so now let's go ahead and hope this is too early we're now gonna go ahead and make some examples of words I know I've been talking about them a lot but it's nice to to actually play around with it and for that we're gonna start by going to our developers volge this is our API documentation you can get there by going to developers Monday comm or Monday comm slash developers slash V - I will send this to you and all these resources in the follow-up email that I sent you but this is where you can see our graph QL schema you can see all of the different queries that you can make with boards and each field on each of those objects and the mutations as well and there's some other information as well about rate limits and so on and so forth what I really like about this documentation though is that there is a try it yourself page so right here when you click try it yourself it's gonna open up a new window and this is a testing environment so this is super great for if you want to start playing around with some queries remember this is an application layer so we can just send out queries and play around to understand what we're getting back you can do all of that using or try it yourself Paige I think it's really really helpful to start understanding how graphic ul works and to see how the data in your in your account is structured so the start with of course I need to fill out my API key we do this I'm gonna go to the admin section I'm gonna go to API you're gonna hit copy and I'm gonna put it in here so right there that's the API key right now only admins can access their API pilgrim's but in the future we want everyone to be able to access the API I'm glad someone else also heard that that doorbell ring I thought it was just in my head this is Shelley I'm here with Ron one of our developers and we're here just if you have any specific questions maybe technical a bit more and he's here to help also so go ahead and ask him whatever you guys want amazing thank you so much all right so we're going through some examples right now and then we'll finish up with some questions so yeah if you have more technical questions that you want a developer to answer or if you have any feedback do go ahead and put that in the Q&A we would love to see that and pass that along to our developer um let's go ahead and get started with making some queries just as a high-level we're gonna go through four queries and all of this is going to be sent after as well so you don't have to worry about missing it the first query we're gonna get is exactly what we were talking about before I want to get the board's on my account I only want to get one board because I have a lot of words on my old ISA and I want to get the ID for that board I want to get the name of that board and I want to get the items on that board now when I hit play it's gonna execute that that query and it's gonna give me all of the ideas from the board which is the API example board so right here I've got a boards object and it's an array of every board in this case there's only one and then for object in that array I am getting the ID the name and the items so so that's the data that's getting returned that's the query this is reading data if I wanted to change this remember I mentioned that graph QL is super flexible I didn't want to get the name was this this board if I was very confident in the name of this board I could hit play and it's not gonna send me the name alternatively if I wanted to get some other information about the board as well let's say I wanted to get let's go ahead and look at the board object and see what other fields I can get if I wanted to get the description of the board I hit go I don't think this has a description it does not go ahead and open up a board that does have a description right here it's that who's in the room board that has all of your wonderful names and occupations on it I'm gonna specify that in the ID and I hit play and boom I get the description of the board as a string and I also get the name and ID basically everything that I'm asking for I'm returning nothing more nothing less so that is a query that is how to get the boards on your item on your on your account it's super simple and you can use this to build out a bunch of other more complicated queries the next thing we're going to do is we're going to create an item on a board and we're gonna use this just test board right here this is a board I'm gonna go ahead and put this ID in the board right here so for every mutation the way that I like to think about it is you're making a function call and in this particular case you're making a create item function call and there are two parameters that you need to give it give it what is the item gonna be called so the item name and you need to give it the board ID so I just put in the board ID super quickly and I'm gonna add this change this item name as well - hey Ron and Shelly you and I'm gonna hit play and boom it's gonna create an item and I asked for the item ID back and so back go ahead and open up the board and boom hey Ron hey Shelly you're on the board now so right there super simple just creating an item the next thing that you're gonna want to do with your AP with the API is you're going to want to change a column value so in this case I want to change the column ID which is status to done in order to turn your column value I need to know which cell I want to change and so I need to know the boarding this Sun I need to know the item ID of the item that I want to change and I need to know what kind of column I'm changing so if aliy the column ID every column has an ID it'll be something like status text that is 3 so on and so forth you can you put the column ID in here and it will then update that relevant status and I also need to give it the value now take note here every single column has a different type which means that in guests different pieces of data and ingests data in a different structure in this case I want to change a status column and let's say I want to change this particular status for Ron and Shelley to a done label let's add a done label so what that means is in order to change the status I need to tell it which little booklet and I'm gonna do that by using the label parameter right here I'm just going to say label equals done now I do need to change these ideas to make sure they match so I'm gonna make this board and I'm gonna change the item of the item ID of this newly created item which I'm gonna get from the URL and I'm gonna put that here I'm gonna hit play and boom I didn't get any errors and when I open up this item this has been changed to done so when I was showing you that Tic Tac Toe example if this status that was being changed and this is the the API call that I was making in order to change those statuses just change the label to an ex change a label to an O and so on and so forth so now you know how to change a specific column on it on a board now how do you change multiple columns and specifically what I want to do is I want to heavily multitask I want to create an item and when I create the item I want to add the a couple of column values and in order to do that what I need to do is I need to specify in the same way as earlier the name of the item I need to specify the board ID and it's going to be this board ID that we've been playing with bar and I'm going to change the status column right here in order to change the status column what I need to do is ensure that it's in JSON format let me and this a little bit you can see better but this column value structure is a JSON string each key in the JSON string remember that a JSON string is basically a dictionary so there's a key and a value for every key this this JSON string is oops this just jumped out at me is is the column ID so earlier the column idea was status right here I'm putting it in as need later on sorry that's keeps plumping column ID goes in here as the key and then after that what I was putting in as value over here I just put it after the colon which is labeled equals one so if you wanted to add multiple column values in one shot all you would do is add the second column column two and put in the various pieces of data that you want to send through you'll also notice that I have a lot of back slashes in here this is because I have some inner strings and side outer strings when you're using the try it yourself page you're gonna want to ensure that your back slashing or escaping the inner string so make sure that we don't get confused about which where that string it and you can see this impact for every single column type in our documentation there's a section specifically for up columns so let's go ahead and hit play and what I should see is a new item on that board that says hey friends will be label done and boom there we have it since we are running out of time I'm not gonna show you the last item or actually I want to show it to you but I'm not gonna walk you through it too much it's basically items by column values this will let you filter to just the items that have a specific column value in this case I want to get the items that have done in the status on this particular board when I hit play it's gonna send me I think seven ish yeah seven different items from this board this is a this is a testing board but let me show it to you quickly and you'll see that the seven items that are returned here are also going to be the seven items that are marked as done so right here these seven it's a testing board there's a lot of crap on here but you will see that the data here that is returned is also on the board so there you have it a couple of queries that you can start playing around with I want to quickly also show you how you could do this in postman so how you structure the individual requests and then we'll move to questions let me go ahead and pull postman out over here if you're not familiar with postman it's basically an application that lets you test out API requests and let you specify which endpoint you're going to what the HTTP verb is let's file the headers and all that good stuff I'm going to use this to quickly show you how you would structure an API call and again I'm gonna send this to you after the the webinar so don't worry about not getting it all um begin with as I mentioned before we want all of our API calls to be post request I'm gonna make this a post and I'm gonna send it to our single graph QL endpoint which is the API URL after that for authorization I'm going to put a key value pair into the header specifically I'm gonna put authorization as the key : and then my API key after that in the body this is the query that we used before kind of it's a little bit simplified but it's basically pulling the ID and the name of this particular board and you'll notice that what I need to do is I need to start with query : now this indicates to our server that what comes after this is the query that you want to execute if it's a mutation you would also put your mutation after this query right here so it would be like mutation yada yada yada and then you would put whatever you want in here I like to remove all the white spaces and the enters just to make sure that there aren't any parsing errors and then I'm just gonna go ahead and hit send and it says not authenticated because I need to check my API key I guess so let me go ahead and do that home right here let's go back to admin view API in the admin section copy the personal API token and paste it in here and now hit send and boom I have got my high-level projects board the name and the ID as specified in the query so I know that was super quick in terms of going through those examples I just wanted to make sure that when we get through as much as possible it's helpful for folks and we are gonna switch over now to talk a little bit about to go through questions just to recap if you have any other questions or you need more help you can always go to our knowledgebase at Monday comm slash support for some general articles on our API

Channel: monday.com

Views: 10,015

Keywords:

Id: 27_R-hgrDgU

Length: 43min 52sec (2632 seconds)

Published: Sun Jul 05 2020