The most powerful way to interact with the PlayFab services is by calling its RESTful Web API directly. In fact, our various SDK's are currently just wrappers around the Web API -- convenient shortcuts to make it easier to use that Web API from other languages or platforms.
Knowing how to manually call Web API is invaluable when you are trying to integrate PlayFab into your game. If a function isn't working out quite how you expect, being able to call it yourself to see what's happening is very powerful. There are a number of tools out there that make it easy to interact directly with a Web API, but one that we really like is the Postman Chrome plugin.
This blog post will show you how to setup and use Postman to try out the PlayFab service yourself.
Step 1. Install the Postman plugin from the Chrome store.
Step 2. Login to the PlayFab Game Manager, and go to your game title. Provision a new title, if needed. Click on the Settings->Properties menu. Note your PlayFab AppID, and your API endpoint. That's the custom URL that your game will use to access the PlayFab API. For example, the AngryBots sample app uses https://8d34.playfabapi.com.
Step 3. Run Postman (from the Chrome apps menu) and configure it as follows:
- POST method
- RAW body type, with JSON (application/json) format
- Enter your app's API endpoint URL where it says "Enter request URL here". Make sure to include HTTPS at the start.
Calling Client API functions
Now you are ready to start calling Client API functions. The full list of functions is in the API documentation.
Step 1. The first step is to login as a valid user, to obtain a session ticket. Virtually all the API calls require a session ticket. The easiest way to do this is by calling the "LoginWithPlayFab" function which takes your PlayFab appID, username, and password as inputs. To do this:
- Append the name of the function to the API endpoint URL you entered earlier in the Request URL field. In this case, I'm entering https://8d34.playfabapi.com/Client/LoginWithPlayFab.
- Copy and paste the sample body out of the documentation, but replace the fields accordingly with your own data.
- Click "Send".
If everything worked okay, you should get a code 200 back and a session ticket in the data, as shown above. We blurred out the sensitive parts, but you get the idea. If it didn't work you may get an internal server error. To help debug, you can try clicking "Preview". It will show you the full POST request, and you can compare it to the sample request in the documentation to see what might be wrong.
Step 2. Assuming it worked, you now have a session ticket. You can now use this session ticket to authenticate the rest of your API calls. To do this:
- Copy the session ticket into the clipboard (don't include the quotation marks)
- Click the "Headers" button. You should see one header already filled out with "Content-Type".
- Fill in a new header with the header name "X-authentication". Paste your session ticket into the value.
- Call whatever function you like, such as "Client/GetCatalogItems" with whatever input data is appropriate pasted into the field.
Again, if it worked you should see code 200 and the results of the calls.
At this point you should be able to call the rest of the client API's to experiment with the full power of the PlayFab backend. The client API is limited, however, in what it can do because we have to assume that client code can be compromised, and hackers will have found this documentation too. You don't want a hacker using PostMan to give themselves 100,000 gold coins in your game!
To fully exercise all the functions of PlayFab, you need to experiment with using the Server API and the Admin API too. The server API is more powerful since it can only be called by your trusted game server code. The Admin API is the most powerful of all - it's what the Game Manager tool uses to configure your game.
Calling Server or Admin API functions
Step 1. Go back to the Game Manager, and this time take note of the PlayFab API Secret Key. Keep it secret! Anyone with this key can compromise your game!
Step 2. Look up the documentation for the function you wish to call. For example, let's say you wish to grant yourself some virtual currency for testing and will therefore call the Server/AddUserVirtualCurrency function.
Step 3. Configure Postman as for an authenticated client call above, however instead of authenticating with the session ticket, now you are authenticating with your App's Secret API key. Set the header name to "X-SecretKey" and the header value to your API secret key.
Step 4. Fill in the rest of the API call details, then click Send.
If it worked, you should get a code 200 and the result of your call.
And that's all you need to know to fully exercise the PlayFab suite of backend functions!
If you run into problems or questions, start by looking at our support resources, including the forum. If you're still stuck, you can email our Developer Relations team at "email@example.com" or submit a support ticket via the ticket system.