Exploring the Salesforce APIs with Postman

– Hello, welcome to this trade live session My name is Philippe Ozil I’m a developer evangelist at Salesforce And on today’s episode of cloud live, I have the pleasure to talk to you about how we can explore the different Salesforce API using a postman collection that we assembled Before I jump into the presentation, I need to give you the standard forward looking statement What this means is basically that you have to make your purchasing decisions based on what is commercially available in the product And today, it’s especially important for the session because some of what I’m gonna cover today, actually most of what I’m gonna cover today is a contribution made by sauce simple east, but it is not part of the product itself I’m gonna be talking about a contribution for postman, and this is just not part of the Salesforce offering So bear in mind when you purchase licenses All right that being said, here’s our agenda for today We’re gonna talk first about postman in general, I’m gonna cover some main concepts and features that you’re gonna be using with postman And then I’ll talk for a long time about the Salesforce API’s Collection This is what we’re contributing and this is what we’re sharing with you as an open source project Finally, I’ll also open door to how you can contribute to this particular project I’ll talk to you about how we are building the collection how you can add to that to get even more from the from the product All right, with no overview, let’s start with the first part of today’s session I’m gonna be talking about postman So first, I’m going to give you a bit of an overview about what postman is and we’re gonna talk about some specific features so that you know a bit how postman works before I dive into the Salesforce specific part So this is postman, the capture, a screen capture you see here on the slide here, is a capture of postman, this is a desktop application that you install on your computer It works for any type of OS whether we’re using Linux, Windows or Mac And what this is essentially is an HTTP client So this is a software, which lets you create and edit HTTP requests So on the left side, you’ll see there’s a collection of different requests And these are grouped into folders and they support the different rest verbs get post, put patch, delete And on the on the right side of the screen, you’ll see a large set of options And what is amazing with postman is that you have a lot of options to customize the HTTP request, you can play with headers with the body, you can have binary content in there, get attached files and there are a lot of options for the different ways you can configure all of that you can even do a bit of automation I’ll talk about that later on So this is the main, the core feature of postman requests Then those requests can be grouped into collections Here you can see on the screenshot, there’s a postman echo collection, which is the collection is available out of the box when you install postman, it’s just a set of dummy requests, which show basically how the tool works Now, having said that, you can create also your own collections And the advantage of creating collections is that it’s a it’s a group of requests, and you can easily import or export them And what we’ll be sharing with you later on is a collection of postman resources Now, collections are powerful, but when you combine that with environments, it’s even more powerful The environment is a set of variables which have a particular value Now, what was interesting with environment is that you can clone it So you can have multiple environments, which share the same variable names So when you switch to another environment, the environment takes the value that these variables have for this particular environment So let’s say when we gonna apply this to Salesforce, we’ll be running queries, or requests on multiple orgs And an org is basically an environment And so for each environment, there’s the same variable name, which is for example, username But depending on the org, or depending on the environment, the variable takes different names So there is an environment and very a lot of things with templates in which we can inject these environmental variables And finally, there’s another concept of workspace Workspaces are great because these lets you package everything So collection environments, requests, all that they’re all grouped into this top level entity called workspaces And the truth is, today I’ve talked about sharing a postman collection, but in fact, we’ll be sharing our workspace because it contains a collection but it’s also, we also have a an environment with it That is what we’re going to share with you

So that’s it for posting, there are plenty more features and really interesting things that we can do with automation But I will cover all of that when we get into the service API collection, because we’ve leveraged a lot of useful features Now, before I jump into the API collections, I want to jump to a quick demo and show you how we can use postman So I’ll be demonstrating the basic environment for postman What we see right now here is a default fresh installation of postman And we see on the left here we have the first collection, the postman echo collection with a few of those pre assembled queries, requests, I’d say Now, if you select those requests, you’ll see the different verbs here you can modify those queries, below here is absolutely hard code But this gets even more interesting when you have environments By default there is no environment that is shipped with the default collection But let’s just continue with that, this is a quick tour This particular request here is GET request, you can see that it has query parameters, which are injected right here in the URL If I change the values here, this will update the values there This is pretty basic Now there are a lot of other things we can do, we can modify the headers Here were hidden actually, because of different content type, you can add your own And you can also do things in this little tab here called tests, which lets you automate queries And you have the ability to run some JavaScript code to do some checks and perform some operations We’ll be using that in the samples collection So that’s how it works And when you’re ready, if you’re happy with your query, you just hit send, and it fires the query Now, if you look at the bottom of the screen here, you’ll see the status of the request to earn okay means it’s a successful code This is just a standard HTTP code for success And you can see the response here, which is JSON in this case, but it can be other types of data All right, and you can see also the test results here, which tells us that everything was okay This is the result of those two tests All right, so that’s really the basics of postman Let’s now go back to the start, I’m gonna be talking about what we’ve created as a resource that we can use the Salesforce API’s collection Now, when you work with Salesforce, there are a broad range of API’s And here on this slide, I’ve reused sort of content I’ve created presented earlier, but just to give you a sense of how many APIs there are, and this slide isn’t even really an exhaustive list The most popular API’s, the ones you will use the most are the ones on the left and center And the ones on the right are the ones which are a bit more specific Now, there are a lot of different API’s that you use, but the one that is most commonly used is the REST API The good thing with the postman collection I’m gonna share with you is that we covered 10 different sets of API’s, including sop rest, some custom API’s, bulk version one, version two, you also cover the UI API, and a bit of tooling in metadata as well Now, this test is gonna evolve, of course, again, it’s an open source project, so you can actually add your own requests So how do you start with that collection? Well, the first thing you want to do is head out to the GitHub website I’ll be sharing the URL later on And the way it works is that you start from this GitHub website here And you can find here the different resources for the the collection, the different API’s that are supported a screenshot and there link here to get the latest version of the collection There are multiple releases, and we’re always fixing bugs, adding new features So if you just click on that one, you’ll get the latest one So how does that how does that work? Clicking on the link gets you this type of file here a JSON file And this is a postman export file which contains, again, the collection, the environment, which is a template environment, it’s just empty with name and variables, and you have to fill up later on, and also some header presets, and then you import it into postman So let’s take a look at that I’ve already downloaded the latest version of the collection, so I don’t need to download it right now, I can just directly jump into my postman Now, what I’m gonna do here is I’m gonna isolate my work from what I’ve been doing here So the best practice is to create a new workspace I’m gonna go in here and I’m gonna create a new workspace So I’m just gonna name it Salesforce APIs And here I have the option to choose either team workspace or personal workspace I’m using the free version of postman

But if you’re using the paid for version, you can actually work with Team workspaces And you can share resources with version control directly embedded inside postman That’s not my case, I’m just gonna select the basic personal workspace Of course, I can still share it later on So I’m gonna click on create workspace And there we go, we have a new blank workspace Now, what we’re gonna do next is we’re gonna import our JSON file So the JSON file isn’t here It’s this one So I’m going to drop it here And this imports my collection you can see here that I have 191 requests And I also got a template environment Let’s take a look at that So what we’re shipping with the collection is a template environment which is empty It contains a bunch of variables here, which are left empty and a few of them already prefilled Now, when you import the the collection in the environment, what you’re gonna do is you’re gonna actually clone that template so that you can create your own specific configuration with at least username, password, maybe a token and client ID, client secret So I’ve already done that to save a bit of time here So I’m not gonna do that right now I’m gonna fill that, but remember that the process is actually to copy first, and then fill the copy on the template environment Now in my case, I’m going to just import the template that I already prefilled for my org, which is here, my sample org There we go So now I have my my configuration here I’m not gonna open it because it contains my credentials So I don’t wanna show you my credentials I’m gonna switch to my sample org so that I use my environment that I have prefilled here And then we’re gonna look at the collection itself So when I open the collection, I’ll see the top level folders, which presents the different API’s that we support Now, one thing that you need to know is that each time you wanna use a Salesforce API, you first need to authenticate That’s a general rule It’s not specific to postman It’s a very common thing with API’s So I’m going to open the off folder, which isn’t really an API on its own but it’s a group of all the different authentication methods And here you can see that we support multiple operations, multiple authentication types The easiest way to authenticate is the sop login And that’s really simple And I’m gonna show you a bit how it works But we can also try the other ones And it’s pretty interesting to test the different authentication modes Because when you’re doing an integration with third party application, you may be tempted to think that maybe something is wrong with the parameters that you’re setting, something like that, well, with those different authentication requests here, you can simulate an authentication flow, just to test your parameters very easily All right, so back to our request, we’re using sop login here And notice that the URL isn’t hard coded right now And we have this notation here with a double curly brackets And this is a way for us to inject the environment variables So if I hover over this URL parameter here, I can see the value that I have in my current environment Here, I have changed the default value, which was configured to go on test.salesforce.com And I’m using a login.salesforce.com My simple one is actually a Developer Edition And it’s the same thing for the other variables, you can see that they already have a value here, I didn’t touch the version, it’s already pre-configured Now, there is no parameter because, on this one because it’s not a GET query, but if I go into headers, actually, let me hide the auxiliary headers You see that we have already preset a few headers in this particular request, nothing special here That’s what is required for the sop login And then in the body here, we have a bit of XML, which contains the credentials for performing the authentication And again, you can find here the syntax with the double curly brackets And this is what will be replaced at runtime when I run my query by my environmental variables All right, so what I’m gonna do now is I’m gonna send this request, is gonna hit my org And here you can see that I have a status 200 So that means about my authentication is accepted What I’m getting back right now, if I scroll down, is some information and this will also include a token, access token The access token is what is required for all of the other requests that I’m gonna make later on

Now, do I have to copy that token manually? No, that’s pretty convenient We did something interesting with the ability to plug in some JavaScript here And if you look at the test time here, what we’re doing with this, instead of doing an actual test, is that we are parsing the response from the server, and we are extracting a few things Now, with that particular command here, PM environment sets, we’re assigning some environment variables And these variables have a specific syntax Notice that we put an underscore B in front of them, we are calling them private variables Basically, these are variables that you’re not setting manually yourself in the environment, but when are automatically set by us with some test code So the next request that I’m gonna run is gonna actually leverage that underscore access token value that we extracted from this first API code to do the authentication This way, I don’t have to copy my access token across the different requests It’s gonna be automatically filled up for us next time we run a query, pretty powerful Right now, what do we see in the authentication command here with sop login, let’s try to launch another request So we’re done with authentication, we have secured an access token And let’s take a look at the rest APIs I’m gonna do something very simple here, I’m just gonna run this query to get the status of my current limits And just to show you about the test script that ran, did its job We can see here that we have already an environment variable with underscore in front of it And this has been replaced with my domain for my current Developer Edition So you see that the variable is replaced So let’s just run that And this will return for us JSON response with my current limits for my Developer Edition So I want to point out right now another feature which is very powerful, which is part of postman, the ability to generate code snippets out of requests So this request is pretty simple here But what if I want to create an integration and use that in a third party application? Well, I can click over here on the code button here to generate code that can run this particular request And you can see here there’s a broad range of different languages that are supported For example, I’m just gonna take take fetch for JavaScript, which is a basic HTTP request, and you can see all my parameter values and everything I need to run my command That’s pretty powerful Now we can just copy, copy, copy, paste this code and use it in a product One of the most interesting things is probably the curl version The curl version is something that you can directly run as a command line So this is pretty powerful because you can create a shell script very easily in dumb that just two lines of your request in there and use it Of course, you’ll have to bear in mind that the authentication token that is here is very temporary, I’m gonna publish the video later on And this token won’t be valid anymore So don’t even worry about me sharing that with you But the idea is that you’ll have to authenticate each time and reuse a new token So you can actually chain the different commands, take the authentication command, extract the authorization token, and then use it in subsequent requests That’s it for the code generation Let’s now take a look at another example There are plenty of different requests here and some of them are things that you can also run on simple tool like workbench Now, what you cannot do with workbench is actually create your own queries, create your own variables, save them and share them with your colleagues or even run the same set of requests with different values on multiple orgs So that’s pretty convenient just to be able to switch environment and share your request with multiple people in orgs So that’s it for the tour of the different requests we have in here in rest, I want to point out to one last thing, which is part of the tooling API And if you’re working with sandboxes, you may be interested in to look into that sandbox folder under tooling We recently added that to a new release the collection with a bunch of commands, which lets you retrieve sandboxes, which are tied to a particular org And for example, in this in this instance, here, I have a set of five different sandboxes, developer sandboxes which are tied to my org And with those commands, I can actually do simple basic actions to run my different sandbox I can refresh them, I can delete them, I can clone them

All that with postman with just a click, and I can also generate the source code, which lets me run that So that’s pretty powerful because otherwise, you could do that with the CLR Or you could do that with the user interface of your favorite ID But with postman, you can also do that right here with a few clicks So that’s pretty interesting All right, I’ll let you explore the different requests There are really a lot of them We’re gonna get to 200 very soon And I’m gonna move on to the next part of my presentation So we’ve seen how you can use postman to use, to code the different API’s But what if your favorite API is not listed there? What if you think that a query is missing? Well, it’s up to you to contribute The project is open source, let me share a few guidelines and explain a bit how we can contribute to the project The contribution process is pretty simple The first thing you want to do of course, is import the postman collection environment inside your postman client You wanna make your changes in postman? Once you’re done with that, you wanna export your workspace and there’s an export feature directly in the application This generates for you a large JSON file, the one that I just imported earlier, when you wanna use a utility we’ve shared called PMX PMX is a little script I wrote, which is not built in OGS And what it does simply is it takes this large JSON file, which contains the entire workspace So collections, header presets and environment and the requests And what this postman extractor does is that it splits this large JSON file into smaller JSON files with also a file structure with different folders So that makes it very easy for us to actually version the fame because we see more granular files And the PMX utility actually has two features, it can actually expand the single workspace file, or also compress it back into one single file So in this case, when you’re contributing, you wanna split the files So but it has this exact same structure as the GitHub repository, and then you can create a pull request on the repository So just to show you the structure, I’m gonna go back to the GitHub repository You can see here, the SRC folder here contains the file structure, what is contained inside this JSON If you try to import an SRC directly in your postman, it won’t work But the content of all that, with the collection with all the requests with the folders you saw earlier, is represented here, is just the main JSON file being split into smaller folders and sub JSON files So that’s the process on how you can contribute Now for those of you who are interested to know how we actually build and how we actually use that, we are using GitHub with actions And let me cover a bit the process of how we release a new version This is just for your own curiosity It’s not something you need to know when you’re contributing, but it might be interesting to you So how do we work? We start from the repository, and we manually create a release on GitHub Now, this kicks off a GitHub action, which is automatically triggered after version is released The GitHub action will actually check out the source file the SRC folder here with all of its sub folders, it will run PMX to reassemble the multiple files and folder into one single JSON file that postman understands and it will attach the JSON file to the new release It’s as simple as that And after that, what we get in the releases section of postman is simply a list of different releases with each containing an asset, which is the JSON file that we need to download in postman So when you just wanna use the collection, all you need to do is just download this JSON file, you don’t need to work with the repository, you really just need the JSON file here That’s it, I hope you found this interesting I’m going to share a few resources with you before leaving you The first one I want to share with you is the repository And this is where you wanna start the readme is pretty precise And if you want to learn about how you can contribute, I forgot to mention that but there is a link at the bottom of the readme file, giving you the contribution guidelines So check out this file here And make sure you give us a shout out myself Philippe Ozil and also my colleague Sebastian Collado, who actually came up with this idea first, and it’s been a great teamwork so far, so make sure you shout out

and make this thing known to people because I think it’s a very valuable resources for developers and for architects Now, if you want to learn more about the Salesforce API’s, I’ve set it for you a challenge batch, which is pretty short And also very interesting because it covers most of the top level API’s that the platform offers It’s called lightning platform API basics It’s been less than an hour, I think, and it covers the main API, so pressed and a few other things So give it a try And this can be a good starting point to learn about the API’s And once you’ve done this batch, you can probably enjoy the postman collection even more Now remember that the postman collection is not a replacement for documentation, you generally wanna work with postman on one side, and the documentation on the other side And here I’ll just share with you a very obvious link, the link to documentation If you’d like to know more about, and to learn more about the collection, we also share, we also written a blog post on the Salesforce developer blog, you’ll just have to search for a postman collection and you’ll probably find it very easily We’re explaining a bit how we came up with this idea, how Sebastian created and assembled all of these valuable resources All right, that’s it for me I wanna thank you all for for joining tonight And I hope you had a really great time and have fun of the collection Again, share it, feel free to contribute The more people use it, the better the postman collection gets Thank you again, goodbye