No, it’s just a note-to-self.
A lot of customers have been using ServiceAPI, and to great successes. We also have very good documentation here – of which largely thanks to my colleague Mark Hall. But what if you want to play around with ServiceAPI and don’t want to write app/build/run it yourself? The answer is simple: There are many REST Clients can do the job for you, and Postman is usually regarded as the best/most popular one.
But, the documentation are for C# client, it can be quite confusing to use Postman to work with ServiceAPI for the first time (or times). If you are experienced with Postman, great! But if you are not – like me – when you use Postman from time to time and everytime it’s new, then this post can be useful to you. Today I need to do some tests with ServiceAPI, and I had to spend some time figuring out how to use Postman – so I decided it’s better to have all of those noted for future reference.
When you have an up and running ServiceAPI instance, time to fire up Postman and do some RESTful stuffs:
First of all, you need a bearer/access token. To get that, you need to send a POST request to https://yoursite.com/episerverapi/token , with the body containing grant_type, username and password , like this
Now you have the access token, you need to include it in upcoming requests. No you don’t add a header with Key = “Bearer”, with the value of the access token. To use it in a GET operation for example, you need to add a header with Key = “Authentication”, and Value as “Bearer <Your access token, without the quotes>”, like this
Now if you need to POST/PUT any data, you should put the Authentication header as above, but with the Content-Type, and the in Body tab, select “raw” data type (If you choose raw + JSON(application/json), then Postman will automatically add the Content-Type header for you. Pretty cool, huh?
And that’s basically everything you need to know to make Postman works for you!
Pst, use the Authorization-tab to setup the token-generation/binding instead.
No need to copy paste tokens and can reuse the token on multiple nodes.
I love postman, one thing you can do with this scenario that we do with our Azure resources is if you create an Environment from the environment config in the right side and add a variable you can then dynamically set it using
var jsonData = JSON.parse(responseBody);
postman.setEnvironmentVariable(“token”, jsonData.access_token);
This will be set each time you do the call so you can not only make it easy to request and save the token but if you are using the runner feature you can automate a series of calls easily.
Good tip!
I usually use Postman for basic scenarios (mostly for quickly testing/verifying things), so I don’t my that manual step.
Hi,
I have currently setting up the EpIServer api and trying to test it using Postman.
My configuration is the same that you described in your article but I am getting a 400 Bad Request with the following content:
{
“error”: “invalid_grant”
}
Any clue ?
Thanks,
David
Hi David
Make sure you send data in tab body with x-www-form-urlencoded content type.
Thanks for the quick reply.
That’s what I do. My request is exactly the same your first screenshot shows.
However in that same screenshot, it seems like you’ve set 4 values in the header of your request. The header of my request contains only 1: “Content-Type:application/x-www-form-urlencoded”.
What are the 3 other values you set in the header of your request ?
Thanks,
I don’t have the access to the environment now, but that would be the headers for grant_type, username and password, which I un-selected when moving to body.
Ok Thanks.
I have the impression that my authencication setup might be wrong.
I am using the Quicksilver demo to which I added the EpiServer.ServiceApi.Commerce (on the Site) following the documentation linked in your post.
I am not sure what the Startup.cs should contain to allow oAuth2 authentication. The cookie authentication is setup by default, so I added :
app.UseServiceApiIdentityTokenAuthorization<ApplicationUserManager, ApplicationUser>();
AND / OR (all combinations)
app.UseServiceApiMembershipTokenAuthorization();
To enable the Authentication on for the API, whitou success.
Which extension method should be called to set it up properly? Did I miss something ?
Thanks,
David
I came here to say the same as lot of others. I found having a reusable collection that I can copy with environment variables very useful. It’s a little bit of a learning curve, but pretty easy to use after some trial and error.
Hi, I used app.UseServiceApiIdentityTokenAuthorization(); in startup.cs, still get the error {“error”:”invalid_grant”}
When I am Calling /episerverapi/token with the setup you specified above I get an error: unsupported_grant_type. I have chosen x-www-form-urlencoded and specified grant_type to password.
I now know why I received this error. I was not specifying https in my request, which made Postman believe my granting was problematic. Problem solved =)
Now I recieve a “User is not authorized for this request instead” =/
It sounds like you need to grant some permissions to that user. Episerverserviceapiread/write IIRC. Check permissions for functions in CMS Admin
Seems the user is part of the administrator Group, which has permissions to those funcitons. What is IIRC?
ServiceApi needs special permissions. IIRC = if I remember correctly
oh yes, you are correct. I got it to work now. I downloaded Postman as an app, and specified the key “Accept” with value “application/json” in the headers, and I got a JSON answer.
I’m on Episerver CMS 11.14. If i call https://mylocalsite/episerverapi/token i get a 404. Does the service api not exist for Epi11?
It does. however it’s aim for Commerce more than CMS. Did you install it?
For future reference, we found out for CMS 12 (and Commerce 14) the token could be fetched from
/api/episerver/connect/token
had to provide
grant_type: client_credentials as well as client_id, client_secret, scope.