Getting Started with Rest API's - Transcript
Christopher Detzel (00:00:05):
All right. I'm going to go ahead and get started. Welcome, everyone to another Reltio community show. My name is Chris Detzel and I'm director of customer community and engagement. Special guest, I say special guest because it's been a while, Joel since you've been on. So, I appreciate you coming back.
Joel Snipes (00:00:23):
Yeah, it's good to be back.
Christopher Detzel (00:00:25):
Yeah. And today's focus will be Getting Started with REST APIs and Reltio. Just as a reminder, please keep yourself on mute and I'll ask questions that are in the chat. So, just as usual, it has been, it feels like a few weeks since we've had a show, but that's about to change because we have lots of shows coming up here in the next several weeks. The community show will be recorded and posted to the Reltio community. Maybe not today, but by Monday or Tuesday for sure. So, some upcoming events today's show is Getting Started with REST APIs. We have one next week on Blazing Trails and Master Data Management Stories from Women Succeeding in MDM and or Tech. Then on the 12th of October, we have Best Practices on Using LCAs and DVF. That was actually several customers really wanted some of that. So, found somebody to do a show or two people on that.
And then on the 14th, we're going to do something a little different, but we want to start thinking about data mesh, data fabric, what are they? What are the differences? How does it fit into master data management? And then we have a special, which I'm really excited about Gino coming in and talking about Reltio Name Cleansers for Matching, should be really fun. And then on the 27th, we have Google coming in and it's Matthew Cox from Google, and we'll have Michael Burke from Reltio talk about How Google Is Improving their Data Quality. And then we have some of our CCAB content kind of for our Reltio documentation they meet. So, if you're interested in becoming a member of that, let me know. It's just a small group of folks that help us with the content direction on the documentation portal, so. And I have a couple more coming up, but I have not scheduled those yet, but please go RSVP. Joel, that's enough of me. Now more of you.
Joel Snipes (00:02:44):
All right. Man, that is quite a calendar we have coming up of shows. I know the LCA and the cleanser jump out of shows I'd like to personally watch, so.
Christopher Detzel (00:02:52):
Joel Snipes (00:02:53):
You're awesome. Today, I want to talk about Using REST APIs with Reltio. This webinar community show is really targeted at either customers who are new to Reltio and aren't familiar with REST APIs or maybe some Reltio veterans who have mostly stuck to the UI up to this point. Maybe they're a little uncomfortable with Postman or REST APIs and want to take that step forward and see what they can do if they add that to their tool box. So, a little bit of prerequisites that you're going to need to work with REST APIs in Reltio. First at Postman, Postman is a REST API client. So it is kind of a tool that makes making your REST API calls easier.
Notepad++, this can be any text editor. It just makes editing the JSON documents you're going to be sending and receiving a lot easier compared to the notepad that comes with Microsoft. And Git. So, Git is a version control tool. And you specifically want Git because I've been working on a repository of REST API calls that go into your Postman and this will let you download the collection and get you a really nice head start.
All right. So, there's actually a lot of different REST API calls that can be made, but the four most popular and the only four used in Reltio are GET, PUT, POST and DELETE. So, these are the four kind of ways you can interact with Reltio through a REST API. GET kind of following what it sounds like is you're retrieving a document, all right? And it's always going to be a JSON document in Reltio. This is a read-only function. So, it has no effect on the data. You're just retrieving data. It's going to give you the same response every time, because you're not making changes unless something else has changed behind the scenes. This call will never have an effect on your data.
The second type of call is a PUT. So, a PUT is kind of a update. It can be used to create. The point of a PUT is to replace a existing JSON document in Reltio. So, one of the most common calls you're going to make is your L3, which is like your data model plus more is it's a PUT call to replace that document. And what makes a PUT different than what we're about to talk about with a POST is a POST is to create. So, when you go to create, maybe an organization entity, you'll use a POST, but it doesn't guarantee the same response every single time. You can make this call twice and possibly have a different outcome. And so, that's the very subtle difference between a POST and a PUT. The difference between those it's called idempotent. I'm probably butchering how you pronounce it, because it's one of the words you only read and rarely say.
But yeah, PUTs are indpotent, meaning they will not have a change, it will have a consistent response even though it is a right action. So, we have PUTs and POSTs, which are both right actions. GET it's a read action and DELETE is exactly what it sounds like. So, it's for removing a document. So, you can DELETE something and get rid of an entity or your data model for some reason you wanted to remove that. So, these are the four ways you can interact with Reltio.
So, the tool you're going to need to have these interactions is called Postman. This is what it looks like. In the center, you have the API, basically your API builder. So you have, whether it's a GET, POST, PUT. Here, you have the endpoint you're making the call to that's like a URL. Parameters are part of the URL. So, it helps you build out some of the parameters that you feed into the URL in a nice user friendly way instead of having to put it in this bar. Then you also have headers which are other metadata you send that kind of affect how your call's going to work. So, I'll show you how a bit of that works. Let's start with, you're brand new. We're going to download Postman for the first time. So, I'd go to your favorite browser and just searched Postman download. I spun up a VM just so I could do everything from scratch instead of working in an existing environment. That way, if you are new to this, you'll see every step, start to finish of how I set this up.
Christopher Detzel (00:07:43):
That's pretty bold. I love it.
Joel Snipes (00:07:47):
Yeah. It's kind of cool because I'm in a zero virtual machine here. I'm in the middle of a zero training. So, I get a little bit of overlap by spinning up a virtual machine in a zero while working on this. All right. So it looks like my download's complete. Let me go find my executable. So, when you install Postman, you'll have to have an account. The nice thing about that is when you move between machines, it's going to keep all your environments and collections in one place for you so that you don't have to export them and migrate them. It looks like when I set up for my demo, it kept some metadata or a cache of my account. So, it logged me in for me. I'm going to log out here so I can do it. Let's see. Thank you for this little man.
All right. So, you're new to Postman. First step once you log in is going to be to click, create an account. You can create account with Google or SSL. So for the sake of this demo, I'm just going to... Cool trick is you can add plus to any Gmail email and create an alias really quickly on the fly. So it's nice for setting up demo accounts on the fly.
Christopher Detzel (00:09:36):
So, nice little comment here for all the Visual Studio code users, there is a plugin called Thunder Client that has the same functionality as Postman.
Joel Snipes (00:09:46):
Thunder Client. Yeah. I have another client that uses them, one called Insomnia. And I know generally the library seem to be importable between them. So, that's cool. I haven't worked with Thunder Client specifically, but.
Christopher Detzel (00:09:59):
So, quick question. Is there a standard Reltio Postman collection that can be provided which contains all the APIs?
Joel Snipes (00:10:06):
That is a great question. Up until now, I was not aware of a standard Postman collection and part of my inspiration for doing this is I knew if you're new to Postman, one of the most frustrating things is setting things up, getting your variables right, getting your collection built. It's really hard especially if you aren't even familiar with how REST APIs work to begin with. So, as an artifact of this community show, I've started a ROCS repository, which is our open source community and created a Postman collection and a sample environment that has all of my best possibly organized REST API collections. So, this link is in my slide deck that I'll share out after the call. It's by no means exhaustive yet, but it is pretty good. And I'm planning on maintaining this in this ROCS repository.
So, if anyone has a collection in a particular area like maybe workflow or the Snowflake connector or something, and they want to push their awesome collection and add it to my collection, we can start crowdsourcing a really nice Postman bank collection that has all the different API calls. And almost more importantly is I'm hoping to standardize the environment variables everyone's using because a lot of times you'll get a collection from somebody and their environment variables are different than yours. So, even though their collection works perfectly fine for them, it might not for you. So, that's really been one of the goals of this effort in preparing for this community show is to create this artifacts. So, awesome question.
Christopher Detzel (00:11:57):
That's great and there's a couple of comments here is... Somebody else have something? No. Reltio Academy has some collection provided as part of the student training. So, that's great. And then you can go to the developer portal to see the test APIs. I'll put all those links into the... It's just one link, but I'll send you the link in here, so-
Joel Snipes (00:12:18):
Yeah, that training collection's really good too especially for beginners. I still have my training collection in my library and I pull calls from it from time to time. All right. The most important step, if you want to be taken seriously as any type of developer is when you download a new tool, go to settings and put it in the dark mode. You'll instantly double your street cred when presenting. It's a similar kind of side effect if you never want to open anything in notepad, you want to have a real text editor-
Christopher Detzel (00:12:48):
Joel Snipes (00:12:48):
Yeah. It's important.
Christopher Detzel (00:12:50):
Joel Snipes (00:12:51):
It's like having the stickers on the back of your laptop.
Christopher Detzel (00:12:55):
By the way, I've started to do that, so.
Joel Snipes (00:12:57):
Yeah, that's it. Started building that reputation. So, you have Postman installed. We have collections, which are where your APIs are stored, right? Kind of like your API library and you have environment, right? So, this is what you're going to use your APIs against. So, you can change which environment you're in the top right here. And you'll see, I have none, but maybe you have a dev test and a prod. You'll create an environment for each and you can change which tenant you're acting against by clicking this dropdown and changing the environment. But right now we don't have any, I want to show you how to get my collection from the ROCS repo I was just telling you about.
So, I'm going to, this is a REST API demo. So, I'm going to really hope you have Git installed. If you're not familiar with Git, and you want a nice user interface, I'd check out something called Sourcetree, but I'm just going to use the Git command line. So, I'm going to create a folder that I want to store my Postman calls in. And then I'm going to open up a command line. You can do that by hitting Windows R, typing CMD and hitting enter. I'm going to go to that folder, which I copied the path of right here by putting CD space in the path. And I'm going to take Git clone and I'm going to copy the URL that'll be in my slide deck.
And I forgot to put space. All right. And now we can see there's a folder called Master and I have a Postman collection and a Postman environment file. So, these two files from this website got pulled down here. The next step is you're going to open your Postman and you're going to go to import here on the left side my workspaces, upload files. And I'm going to upload the two files I downloaded plus one I set up in advance. You can see my API Postman collection is going to import the collection, the sample environment as an environment and my sandbox tenant, which is my personal tenant here at Reltio as yet another environment. So, after importing, I can now click the environment dropdown tab and I can see the sample environment and my sandbox. Now the sample environment is as important of an artifact as the API collection itself because something I've had a lot of my customers come to me with is... Let me find, I think I have a sample.
We'll look at... They'll be looking at a documentation page like this one, and they'll be wanting to make an API call. So, in this example, they're trying to get the mapping file for the Dun & Bradstreet batch process. And they come and see the API. They're trying to call and they'll see D&B connector profile URL is a variable and profile is a variable. You can tell because there's curly brackets around it. But they get here and they copy this into their Postman. And the variable comes up red and they make the call and it fails because the endpoint doesn't exist and maybe they realize they need this variable, but where do they find it? How do they know what it looks like? That the frustration I've ran into personally, and I've had some of my customers complain about too.
So, the sample environment might not give you the perfect endpoint for your environment, but at least tell you what you're looking for. So, if I open the environment, the D&B connector variable is already populated here. The most common dev test D&B connector is populated as the value. And then you could probably make a pretty good inference on what the right value is if you needed to change it. So, say you're trying to update this to the production. This value is probably Reltio production normally call it 361. So, you could replace that piece, but you at least know what the format of this variable is going to look like, which is a pretty common frustration. So, for all the different ones that exist out there like the LCA, DTSS, validation, cleansing... Like validation, cleansing, LCAs, all those are coming up soon. You're probably going to get demos of the APIs working great. You're going to go to the documentation. You're going to want to know what those URLs look like. So, there's a nice example here that'll get you started.
Christopher Detzel (00:18:06):
Hey, Joe, good question. D&B access is required or not?
Joel Snipes (00:18:12):
For that particular call, yeah you have to be a D&B customer.
Christopher Detzel (00:18:17):
Joel Snipes (00:18:17):
But the point of that example was really to show you that in our documentation, they have these variables all over the place because they're unique to your customer environment. They can't put the full value here. So, this could be for your RDM, right? What is the RDM URL? It just shows the variable here. The most common RDM URL is rdm.reltio.com. And so, you can see the RDM section in here. I have that kind of pre-populated for you.
Christopher Detzel (00:18:52):
Joel Snipes (00:18:54):
So, the reason I had two environments set up is because I didn't want to put my password in front of you guys. I'm sure you're all upstanding people, but just in case. So, when you download this file and you set it up for the first time, you're going to want to come in and change things to match your environment. So, maybe you are in test-USG or just in dev or test, you want to change this piece. You want to put your tenant URL here and here and you're going to want to put your RDM tenant here. Put your username and password and you're going to be pretty much ready to roll for most of your variables you're going to need. So, that's one piece of what this collection is. The second piece is if you go to collections, you'll now have this dropdown on the left side because-
Christopher Detzel (00:19:43):
So, quick comment, Joel. Sorry-
Joel Snipes (00:19:45):
Oh, go ahead.
Christopher Detzel (00:19:46):
... about that. But if you change the type filled from default, there's a way to mask values.
Joel Snipes (00:19:54):
Oh, wow. That would've-
Christopher Detzel (00:19:56):
See. Dan, thanks.
Joel Snipes (00:19:59):
Now, I'm learning something. I cannot wait to figure that out because anytime I work with a customer, I'm constantly like, "Hold on. I got to stop sharing for a second while I put in my credentials and then I'll come back." So, that is a great tip. Thank you, Dan.
Christopher Detzel (00:20:13):
Yeah, he said it's kind of newish, so.
Joel Snipes (00:20:15):
Oh, okay. Maybe in one of the later updates.
Christopher Detzel (00:20:17):
Joel Snipes (00:20:20):
So, in my Reltio API collection, I have a lot of the big headings of different things you can do in Reltio. We have MDM, which is the core product, RDM reference data management. We have our workflows, export, Dun & Bradstreet, Matching and inside each collection, I have subheaders, so particular, at least can go fairly deep, like in Dun & Bradstreet in particular, I'm showing this one because it's probably my most flushed out section of my code right now. It goes quite a few layers deep, right? Because we have Dun & Bradstreet, then we have the mapping and then maybe the batch mapping I was just showing. And then the three API calls you can make.
So, when you click one of these, it's going to pop up and you can see the variables are pre-populated so that it's going to pull the data from your environment. You can see that the parameters are pre-populated. So, right now there's two Dun & Bradstreet products. You can turn this on and change which product you're using. The headers are pre-populated and they get your access token and the body's pre-populated. So, this is kind of what a standard batch mapping looks like. So, you can make a couple of changes and you're ready to roll. So, you can probably see how this would be a huge head start from copy and pasting these values from the documentation and trying to get this to work for the first time.
Christopher Detzel (00:21:50):
And Joe quickly, and I think the first question was answered, but where do you get the user ID and password? And assuming they're acquire to authenticate before using the endpoints, somebody set up. Yeah.
Joel Snipes (00:22:02):
Yeah. That's a good question. So, username and password, you're going to be getting from your Reltio admin. If you are the first person on the ground with Reltio, you get that information basically when your project starts for your Reltio implementation, the main point of contact will get a document with their login and they'll be the admin who can then give access out to other folks. From that point, you might connect it to your SSO and then authorization will come through your SSO. But before you can make any API calls, you need to make an authorization call. So, I put this call outside of all folders at the bottom. When you make this call, up I'm in my sample environment with that password. So, I'm going to change to my sandbox and make this call again.
And you'll see that I got a different outcome because these variables were populated with different values. So, I just authorized to my sandbox and got a token. And in the test section, there's a nice little script that saves this to value here into your environment. So, now, you don't have to copy and paste your tokens over and over. You're just authorized. This token has updated in my environment. So, step one of any API sequence is to get a token. You can see in line five, the expires in... This is how long your token has to live. I have 3,599 seconds to use this token.
Christopher Detzel (00:23:32):
All right. Let's test that. No, I'm just joking. But quick question. I think you mentioned that you're going to save these lists of APIs. So, somebody wants to know how do they get a list? I know we have a documentation list, but is there something that you can share so that people can get access to stuff like this.
Joel Snipes (00:23:51):
Right. So, importing this collection you'll have all of these API calls, right? So, this will be one way to have a list of what's available. For an exhaustive list of what's available, it would be the documentation portal.
Christopher Detzel (00:24:09):
Joel Snipes (00:24:10):
There's really two ways to look at APIs in the documentation portal, docs.reltio.com has all of the APIs that I'm aware of that are customer-facing and developer.reltio.com is a swagger API portal. So, it's a little nicer, you can demo the APIs right on the webpage. And so, you can quickly see how they work. You can see what all the different variables are. It's really nice. I don't think every single API is covered there yet. So, if you don't find what you need in developer.reltio.com, take a look at docs.reltio.com. That's the most exhaustive.
Christopher Detzel (00:24:53):
And after this call, what we'll do is we'll kind of push that into the presentation that Joel is going to share. So, I think so that everybody can have that access. The other piece is, might be an opportunity for us to share some of these APIs specifically on community, some that have been helpful and things like that and just start a thread or something, so.
Joel Snipes (00:25:15):
Yeah, that's a good point. I'm wondering if maybe we even want to have maybe two collections in this repository because if you're just getting started and you just want the handful of the most useful APIs that are commonly used, that training collection is a great collection to start with. But if you're starting to dip your toes into the deeper water and you want everything, the goal of this collection I built here is to just eventually have every Reltio API in the same format so that we're all singing it from the same hymn book, so to speak.
Christopher Detzel (00:25:51):
That's a good one. Thanks, Joel.
Joel Snipes (00:25:56):
You're welcome. All right. So, we have our token, let's say I want to make a change to my data model. So, I'm going to go get my configuration. Also, notice the L3 by going to this endpoint under configuration, under MDM and hit send. And without any configuration in Postman, other than importing the library, I just got my L3 back, which is pretty handy. I can take my L3 into a text editor, or if you can't download a text editor, there's some pretty great online ones like JSON Editor Online. So, in this hypothetical example, maybe my goal here is to change the way organization label is displayed. So, ahead of that, I'm going to log into my tenant and show you what it currently looks like. So, this is my sandbox and we can see organization is displayed as the name organization. Let's see.
So, I'm going to find organization entity type here, and now I need to find the data label pattern or the label for the organization. Here it is. So, this is how it's displayed in the UI. So, I'm going to call it, I mean, Joel's organizations or something along that line. Update that. So, this was a GET call that I was alluding to earlier. It's just to read. Now we're going to make a PUT call, which is an update. So, I click the PUT configuration API call for my library. I'm going to navigate to the body tab. This is where the configuration will go. I'm going to DELETE the existing value and replace it with my new value and hit send. The response to the request displays in the bottom here. So it gives the new configuration as it was updated. And I get a status of 202, it was accepted.
You get some other nice information like how long it took to make the change, that sort of thing. So, now we can go back to my tenant and refresh and we can see these are now Joel's organizations. So, I just made a change to Reltio completely through REST APIs, no UI interaction. We only came to the UI so we could see it happen.
Christopher Detzel (00:30:08):
Hey, quick question. Is there any reason the formatted JSON is not used to send the updated configuration back to Reltio.
Joel Snipes (00:30:21):
The formatted JSON? I'm not sure I...
Christopher Detzel (00:30:25):
Jay you want to... He said, "Is there a reason that the formatted JSON is not used to send the updated configuration back to Reltio?"
Joel Snipes (00:30:36):
Yeah, so we got the JSON from this GET configuration call and then we updated it in our text editor, which we used JSON Editor Online. So, we copied it, well formatted and we put it into the body of the PUT configuration. So, we did use the formatted JSON to update it, I would say.
Christopher Detzel (00:30:59):
I think I saw you copying the update back to left side, right? That's the reason I was just wondering why you did that.
Joel Snipes (00:31:10):
Oh, yeah. So, because it's a demo, things are not going to work right for some reason, this isn't collapsing today or now it's going to do it because I... But I've been clicking this over and over and it's not expanding and collapsing. So-
Oh, okay. Okay. Yeah. Yeah. That's why I was wondering.
Joel Snipes (00:31:24):
But for the sake of keeping the party going, I made the change on the right side and copied it over.
Joel Snipes (00:31:28):
Yeah. This is what I get for not drinking my own Kool-Aid and using the Notepad++, I guess that you shared.
Christopher Detzel (00:31:33):
People are going to notice, man, Joel. You can trick me, but you can't trick people like a Jay for sure. So, another question. Yeah, no problem. And thanks, Jay... Any API endpoint available for updating just single elements of the L3 config or do you have to update the L3 as a whole?
Joel Snipes (00:31:55):
That is a good question. There are some endpoints that allow you to do that. I'm a bit of a creature of habit. And so, I always grab the whole L3, but there are endpoints that update just survivorship or just the match rules. I think the one for cleansers as well, so you can piecemeal update the L3 using those, if you like. You don't have to get the whole documented every time.
Christopher Detzel (00:32:29):
Joel Snipes (00:32:35):
All right. So, now we have made REST API calls from Postman. I want to show you one of the reasons this is really, really powerful. So, not only are you interacting with the Reltio algorithmic, you aren't using your mouse to interact with Reltio, but rather using these REST API calls, how do you transform this into maybe automated processes or scripts or that sort of thing? One of the really cool things that I love that Postman can do is it will automatically generate the code to run these REST API calls in whatever language you want. So, if I wanted to get my L3 once a day and maybe save it somewhere as a backup, if you wanted to do that with the command line, maybe some kind of shell script, it gives you how to do that with curl over here. If you wanted to do it with my favorite language, Python, it gives you two different ways.
So, it gives you the HTTP client library or the Requests library, and you can copy and paste this, save it to a file and now you have a Python script that'll pick up your L3 whenever you want to. So, really awesome for integrating into existing scripts and processes. Not only do you have a way to interact with it algorithmically manually, but you can start automating it really quickly by using its code generation on the right side. So, that's one cool tool I wanted to show you. Another cool tool that I am a big fan of is if you're doing export, sometimes you're doing targeted reports and you're doing this report over and over and over. So, you have to build a filter. So, if you look at the filter API options, they are exhaustive. So, you have all these sorts of options, like does it equal a particular value? Is the value empty? Is it not empty? And you can see that these kind of get pretty tricky to write out into a query so that it could be a long, annoying query to have to write out in your Postman.
So, one of the really cool things about Reltio is, Reltio is a REST API product. And this UI is just built on top of the REST API. The UI is less so the product than the API is. Everything you can do in the UI, you can do with an API because that's how the UI is doing it. And there is a way for you to see how the UI is doing it, and you can steal that code from it. So, I'm going to show you how to do that. So, hypothetically, you're doing a recurring search and you want to know... Do we have state data? You want to know who all your Illinois customers are every single day as a report. So, you have to write out a filter where it says filter = attributes.addresses.state = Illinois. That could be kind of error-prone when you're typing it directly into Postman. But you could avoid having to write that filter out and make, Reltio write it for you by doing the search in Reltio, hitting F12, and then refreshing the page.
What's going to happen here is you're going to see a whole bunch of API calls. You can limit them a bit by hitting the Fetch XR here at the top. And you're going to see all the API calls Reltio made to generate this page, which is quite a number. But as we start to become familiar with the API, we know we're looking for entities and we can look down this list of API calls being made and look for the entities call. You can see only one of them has the word entities to start with. Trying to expand this and it is fighting me. So, you can copy the URL and you can see it made a really long complicated filter to make this call. And you can go onto Google and type the code URL, paste it in and see what the URL looks like.
So, sometimes it has things like %20 for spaces. That's how you encode a space and HTTPS, but we can see that we have our, let's see, let me zoom in a bit. We were searching for an organization type where the address is Upstate province of Illinois, with the max of 25 because the UI limited the response to 25 and that sort of thing. So, now we have this awesome REST API call that would've taken a little bit to write, generated for us by the UI, which is really handy. I can take this UI call, open my Postman, authorize. I like to duplicate one of my existing API calls and then just paste it in here. Right? All the parameters will automatically populate. So, maybe I don't want to limit my responses to 25 and I don't want scores enabled so I can quickly make those changes. Now, I can make this call and get back a response, which was mysteriously empty. Make sure that this didn't break anything.
Speaker 4 (00:40:09):
Hey, Joel. Did you notice that you're sending a POST?
Joel Snipes (00:40:27):
Oh, that is it. Thank you.
Speaker 4 (00:40:29):
Joel Snipes (00:40:29):
That's exactly what's going wrong there. All right. And then I get the same response that the UI was getting back. Thanks for that catch in the live demo. It's easy to miss these things. So, I was trying to send a create statement and I was really trying to get data. So, I had to switch my POST to a GET. And now I get my response back. That's the exact same response that I'm getting from the UI here, right? These two Accenture values coming back here. So, if this is a useful API for me, I can go and save it. Save as, and add it to maybe my collection, name it something like Fine Illinois Customers.
And if I want to make it part of a script, I can quickly generate the script to find the Illinois customer. So, maybe if I onboard a new one, the script will automatically update. So, really cool, really powerful, not as easy to do and to integrate in the UI as you can do once you get out in the Postman. So, that's one of the really cool use cases I wanted to take a chance to show you. Hopefully that made sense because I know going into the Chrome developer tools can be a little daunting, but really handy.
Hey, Joel, you did something there that I thought might be a little bit instructive to drill down into a little bit. You copied one of your existing calls. Why did you do that?
Joel Snipes (00:42:02):
That is a great question because you're 100% right. If I just pasted this into a blank call, it would not have worked. And I copied an existing call because I'm lazy. And there are two headers here that I would've had to populate by typing them in by duplicating an existing call. These headers were automatically duplicated and the POST value was automatically duplicated, which is why it didn't work at first until it was kindly pointed out to me that I should change it to a GET. So yeah, whenever these two values in particular, authorization and content type are mandatory for maybe like 95%, 98% of Reltio API calls. So, I'd strongly recommend taking one of your existing calls and duplicating it when you're making a new one because it's really handy for saving your time having to write out these things.
If you forget to do that, the error message you'll get is something like call needs full authentication or something like that.
Joel Snipes (00:43:08):
Good point. And I appreciate you pointing that out because that could definitely get you. All right. Let's see. We did Chrome to discover. I think that brings us to the end. So, are there any other questions or any other API calls you might like to see?
Christopher Detzel (00:43:35):
None at this time. Feel free to speak up if you want. Yeah,
Yeah. This is Dan. Can you all hear me.
Christopher Detzel (00:43:43):
Joel Snipes (00:43:44):
Yeah. So, I put this in the comments, but I just wanted to call this out because it caused us a lot of pain. And if anybody else can avoid it, I'd highly recommend taking a look at the link that I posted in there to the Reltio documentation where I've highlighted the tip section there, where it talks about never applying a consolidated configuration to the tenant. Always pays to read your documentation before you start doing things because it took me hours to fix that problem. Somebody did it on our end and I just figured maybe Joel, if you wanted to cover that, it would probably be a good idea.
Joel Snipes (00:44:25):
Yeah, it's really frustrating to have to back out a consolidated configuration. So, let me start by explaining what that is. So, we refer to our configuration as a L3, which implies the existence of an L1 and L2. So, the L1 and L2 are Reltio provided inherited data models. So, they're not models that you can make changes to as a customer. They're just accelerators to get your models up and running faster. And on top of that, we generally provide an L3 as well, which nicely inherits from those L1 and L2s and allows you to make changes so you can inherit and then overwrite in the L3 and make changes to anything you want to, but you never want to, and you're not even able to make changes to the L1 and L2.
So, what some customers will sometimes do, or even maybe Reltio and PS employees who aren't being thoughtful is when you do this GET call, you authorize, you can get configuration with no inheritance. You can get configuration with inheritance. Sometimes you get configuration with no inheritance is getting your L3. Getting it with no inheritance and you'll see the endpoints are slightly different here in the underscore. This gets the L1, L2 and L3 as one massive document. So, what I see a lot of times happen is the customer will accidentally get the L1, L2 and L3 as one massive document. They can't write back to the L1 or L2. So, they'll accidentally POST this back over their L3. So, now their L3 contains L1, L2 and L3, and you're going to have to back out all the L1 and L2 stuff to bring that document size down to a reasonable size.
So, let me show you, this is the L3. It's like 366 kilobytes. This is the L1, L2 and L3, and it's 460 kilobytes. So, it's definitely a bigger file by about 30% here. And as you do a lot of your custom configuration, that can sometimes jump. If you do accidentally make this mistake, a really handy API call is adding in underscore history. This is going to bring back a really big document because it's actually a collection. And it'll bring back the history of all your L3 changes. In my demo tenant, I don't have a whole lot of them. So, this document's still pretty small, but if you accidentally made a change, you can use this history call to go back and get your L3 before you made that mistake. And you can copy that and put it back.
So, I think I had a mistake in there. So, you go and you can see the last update was made by me at this timestamp and you copy from the configuration down. So, starting around line five, all the way down to whenever your document ends. This will be your configuration that you can grab and put back. So, if you've made a lot of changes in the last few months, this document might have 10 entries in it. You can go back quite a bit.
Christopher Detzel (00:48:14):
Great, thanks. And there's some more questions and Dan, that was really awesome. Thank you for the link and bringing that up. So, do we need to know the data model to use the API?
Joel Snipes (00:48:30):
I think you can almost flip that. You can use the API to get to know your data model. You can't see all the data model in the UI a lot of times, because some of it's hidden or just isn't being used, that kind of thing. So, I love using Postman to get familiar with a new customer's data model. I'll do a GET, I'll grab the configuration, I'll pull it into my favorite text editor. This time I'm not going to use a web-based one, follow my own advice, paste it in here, change the language to JSON because it'll give you a nice highlighting to make it easier to read. And now I can go through this data model and see, "Okay, they used D&B and Salesforce as their sources. They have Kafka as a source." Okay, that taught me a little bit about where their data's coming from. Maybe I'll go look at their entities. I don't know if my mouse is acting up or if my computer is out of memory because I'm sharing, but whenever I collapse anything it's not working. All right.
Christopher Detzel (00:49:51):
Time to upgrade your memory.
Joel Snipes (00:49:53):
Yeah, I guess so. So, here you can see I have the party and my entity type. So, I've actually put something from the L1 into my L3. So, this is exactly what I was telling you not to do in general, but I actually didn't do it for the reason... I didn't do it on accident. This was actually intentional because sometimes you want to bring your L1 in and override something so that it affects all the things that inherit from this party entity. So, that's why it's in mine. And you can tell that it's intentional because the document sizes were different between the L1 and L3. So, I can scroll through this file and get to know all the different organization attributes, the location attributes. And I can use Postman to get this file and get familiar with my data model.
Christopher Detzel (00:50:43):
Great. Can we import a file for bulk updates?
Joel Snipes (00:50:49):
You can. So, just like you can do a bulk update API call in the UI. That same API call can be made through Postman. I don't think bulk update does file loading. You might want to use the data loader API if you're trying to send a file.
Christopher Detzel (00:51:12):
Okay. Regio wants to know is, and it's kind of the questions asked a couple of times already, "Is there a way we can get this PowerPoint for reference and Postman collection samples?"
Joel Snipes (00:51:22):
Yes. So, I will share out the PowerPoint after and I have a link in the PowerPoint to the Postman collection samples.
Christopher Detzel (00:51:29):
Great. So, looking for more monitoring API status logs. So, I guess they're looking for more of that. Do we have?
Joel Snipes (00:51:40):
I have a little bit in this collection I shared out.
Christopher Detzel (00:51:43):
Joel Snipes (00:51:44):
I think only have a couple. So, one of them checks the general health of a tenant and the other one checks the health of the match queue to see how much is in it. so-
Christopher Detzel (00:51:57):
Okay. So, that's being shared?
Joel Snipes (00:52:01):
Yeah. That'll be part of the collection. So, like in this API, I can see my tenant's green. It's not under any load at all. My queues are empty. That kind of thing.
Christopher Detzel (00:52:10):
Joel Snipes (00:52:10):
They're probably more out there. So, if you discover a great monitoring API in the documentation portal, upload it to this and let's grow our community collection here.
Christopher Detzel (00:52:28):
Yeah. So, Dan said, "Ours went from about 45K lines of JSON down to 12,000," after he cleaned it up. So, that's awesome. Is there an API to call only locate for address standardization?
Yeah, I put that one in the chat.
Christopher Detzel (00:52:47):
Oh, okay. Thanks. It's the cleanse API by the way. Perfect.
Joel Snipes (00:52:53):
That's a good question because I know you can cleanse like an individual entity by putting-
Yeah. It's the cleanse on the fly API that I put the Reltio doc.
Joel Snipes (00:53:05):
Thank you, Gino. Yeah, that's helpful.
Christopher Detzel (00:53:07):
Yeah. Another question is, do we have all Reltio API collection into our Postman collection JSON files? Do we have all those? Is that or is there way more than just what's being presented?
Joel Snipes (00:53:21):
Yeah. There there's way more than what's being presented. So, I, for when I went through D&B, which is probably the best collection in here, I went through in the order of the documentation and added each API in documentation order. And then if you click in Postman, I even have a link in the Postman documentation that links out to the API documentation so you could read more about the particular API you're trying to work with. So, my goal here and with this library is I want to have a set of standards. I want to have standards around the variables. I want to have standards around the completeness of the API options. And I would like to have them link out to the relevant API documentation each time. So, because of that, I haven't gotten to every API in Reltio. I'm curious how many endpoints there are. I'm guessing probably in the low thousands. So, it's going to take a while to get them all there.
Christopher Detzel (00:54:21):
So, just out of curiosity for myself and so I can help folks know that basically, you're uploading these APIs into Postman and then you can share that Postman to others. Is that what we're talking about?
Joel Snipes (00:54:36):
That's exactly it.
Christopher Detzel (00:54:37):
And they can just look at the same stuff that you're doing? So, I could go here tomorrow and... Okay.
Joel Snipes (00:54:42):
So, I put my Postman collection in Git, and so that's kind of a shared place to maintain and then you can import it once you download it from Git, but at the same time, if you've improved this collection in any way, export it and push it back. And then now that collection will be a little bit better for everybody.
Christopher Detzel (00:55:04):
Joel Snipes (00:55:04):
That's kind of what I'm hoping to achieve here.
Christopher Detzel (00:55:07):
Yeah. I want to promote that heavily. So, you and I should do some stuff offline so that I can have a better understanding so that I can share this out better so that people know, especially on community.reltio so they can go here to do this, because there's obvious interest in this. Some other questions or thoughts is, "I usually do a bulk update using the API, however, having some trouble in getting the status of the bulk update. How do you get the status of the bulk update via API? I can see it through the UI." Oh, I think Gino might answer that, but...
Joel Snipes (00:55:43):
So yeah, in Reltio, there's jobs and tasks. And so, depending on what type of job you set off, depends on where you go to monitor it. And then also there're different endpoints I was showing you earlier, right? So, if it's an export task, it's going to be at a different endpoint than maybe a bulk update task. So, I think Gino might have shared the relevant API above, but I also have under administration kind of just check running task and get lists of processes. I have a couple of these monitoring API calls in here that'll be helpful.
Christopher Detzel (00:56:25):
Great. And by the way, I think some people are leaving. There's a survey after this that will just pop up from Zoom. So, please take that survey. So, a few other questions. Can we bulk insert new RDM values using this method of using Postman APIs? I think Steve put some links there, but I don't know.
Joel Snipes (00:56:46):
Yeah. So, with RDM you can send, I can't remember how many a time in a call. So, maybe 50 records in a call or something like that. It's probably higher than that. It's probably in the hundreds of thousands, but there's also a tool on ROCS as well called... There's RDM JSON Generator. So, converting your RDM values from CSV to Reltio JSON, and there's also a RDM data loader. So, I'd take a look at the ROCS. If you go on our docs portal and just search for R-O-C-S, ROCS, there'll be links out to both those tools.
Christopher Detzel (00:57:25):
Great. So, last question looks like, I saw a bunch of N or no, it's not... NPM libraries related with Reltio. Are these available for public use?
Joel Snipes (00:57:41):
Let's see. I'm guessing NPM is node libraries. I think so. I'm not sure what node.js libraries exist for Reltio. Not sure who would be the right person to ask for that.
Christopher Detzel (00:58:03):
Joel Snipes (00:58:04):
Unfortunately I don't think I can answer that question. I'm sorry.
Christopher Detzel (00:58:06):
No, that's okay. So, if you go to community.reltio.com, Sanjay, I can help find an answer there if you actually post it there, that'd be helpful to me so that I can go and find somebody. Simon says, "Sorry for the novice and dumb question," but it's not. "If you have a D&B identifier number, but want to call the API to get the enriched D&B data, is that possible?"
Joel Snipes (00:58:32):
Right. So, you want to get just the D&B data is what I'm assuming.
Christopher Detzel (00:58:37):
Joel Snipes (00:58:37):
And not just your Reltio record. And I'm going to... It's funny, D&B actually inspired this project because D&B has their API collections on their website. So, if you just Google D&B API collections, and they're super easy to use out of the box so this is actually one of the standards I'm trying to live up to is I want our API collection, which we have a lot more APIs, I think, to live up to this. So, if you wanted to do that, you would want to make a call like this. So, download the D&B direct plus identity resolution and the parameter is going to be the Dun's number here. Let me see if I have an active key so I can even use. Yeah. So, I don't have any D&B keys in right now, but if you made this call with your D&B keys after authorizing, you would get the D&B record for that. So, that's how you would do that.
Christopher Detzel (00:59:39):
Okay. And just a quick question. "Hey, which keyboard keys were you using to see the API call on Reltio UI?"
Joel Snipes (00:59:47):
Good question. Yeah. So, when you're on... The way I always do this, because it can make a lot really quickly is I create the search I want, hit F12 and then refresh the page because if you continue to navigate around Reltio while this is open, this already made a whole lot of calls and now I got to go find the entity's call, the one I'm interested in. But if I continue to navigate, it's making a lot of API calls. So, that gets confusing pretty quickly. Keep Fetch XHR on, that kind of limits the number of things you're seeing in here. And if this gets filled up and you want to reset it, this button right here will clear everything, so then you can see just the API calls of what you're about to do. So, F12 is how you get to this panel. Also, you can also get to it by... There's a way by clicking in the settings to get to it as well. But that's harder, just F12 is easy.
Christopher Detzel (01:00:44):
This was great. And please take the survey everyone after this call, it just pops up from Zoom. Hopefully you really like this and a lot of great questions, a lot of great insights from Joel and Joel really appreciate it. We'll kind of continue to build that collection of APIs and push it out to... What is it? Git bucket. Is that where we put it?
Joel Snipes (01:01:08):
Yeah, it's Reltio's open source.
Christopher Detzel (01:01:12):
Joel Snipes (01:01:12):
Oh, yeah. ROCS.
Christopher Detzel (01:01:14):
ROCS. And then we'll continue to do that and please share your own APIs as well that whenever to update it and stuff like that. But thanks everyone for coming. Thanks, Joel for giving this great presentation. Really do appreciate it. Jay says, "Today's session is fantastic." So, that's good to know. Well, let us know what you think. So, thank you everyone for coming. Really great. This was awesome.
Joel Snipes (01:01:45):
Yeah. Thank you everybody. I appreciate all the support.
Christopher Detzel (01:01:51):
And I'm going to stay on just for a minute or two. It's really good. You always get tons of questions and one thing I really loved about this particular session was how everybody pitched in. It's funny a lot of people know some of these things on this, so it was pretty cool.
Joel Snipes (01:02:12):
Yeah. I appreciated the support. People picked out what was wrong with my API call. That was really, really helpful because it's hard to spot a little thing like that when you're the one presenting sometimes.
Christopher Detzel (01:02:27):
All right, everybody, I'm going to go ahead and end it. So thanks everyone. Take care.