Deep dive into Power Apps Portal Web API
Help UKRAINE ! Your action matters! Donate money to support Ukrainian Army! Donate money to charity fund! Organize/join street protests in your city to support Ukraine and condemn Russian aggression! Expose and report Russian disinformation! #StandWithUkraine
One of the most requested and long-awaited features for the Portals is finally here - Web API is available in preview. Finally, one of my portals was updated to the necessary version (to have Web API your portal version must be 22.214.171.124 or higher) and I was able to play around. Below I will describe what Web API is and will have a deep dive on how to use it.
You can find full official documentation on Web API here.
Why Portal Web API
Before we started our journey into the depth of the API lets first define what is the main purpose of the Portal Web API. Unlike CDS Web API you cannot use it outside the portal for integration or any other purpose. So why do we need it? Well, the answer is pretty straightforward - enhanced user experience.
Let me explain. Before Web API we need to rely only on provided standard functionality - forms (entity and web) on creating/updating records, entity lists on showing lists of records. And this was limiting especially from a user experience perspective. With the introduction of Portal Web API, we can create complex custom experiences - creative forms, editable lists and much more.
Microsoft opens the door for front end developers by making their Power Apps Portal less low code, which is great.
Web API vs CDS API
First of all, let’s compare Portal Web API to the CDS Web API. As per documentation, they tried to make it as similar as possible to the CDS Web API to make it easier to learn and use it. Web API operations available for the portal:
- Create (including creating related records in one request)
Now here you cannot see Retrieve operations which do make sense - fetchxml liquid is present on the portal for a long time and there a plenty of ways use it not only as part of the page during load but to turn it to some sort of web API as well. However, I do hope that this was a prioritization decision and in the future, we will receive proper Retrieve possibilities.
Web API and Site Settings
By default, Web API on the portal is disabled. To enable it you need to configure it support per entity as a site setting.
Furthermore, you need to specify which fields will be available for web API as another site setting.
Both these options give you more control over the security of your data (unlike odata entity list option).
Also, you can enable the ability to see inner Web API error with the next setting
For example we want to enable Web API for contact entity for first name, last name and email address. Our setting will look like this:
Entity permissions and supported entities
Web API respects entity permissions granted to a user via web roles.
Web API will support OOTB entities like contact, account and custom entities. It will not support portal configuration entities (like adx_webpage etc). As in preview, you will be able to change them, but this is NOT SUPPORTED and need to be avoided.
Portal will manage authentication and authorization, so no authentication code is required. However, you need to include CSRF token with all web API requests. In short - CSRF token is a specific unique, secret value generated by the server that needs to be included in the request to prevent CSRF (cross-site request forgery) attack. Don’t worry about how to get token - MS included a code snippet that you will be able to copy-paste into the portal that handles it for you - I will review it in the How to use Web API section below. Audit
To see actions performed by the portal user in the Office 365 Audit log events you need to include contact id in the request header.
How to use Web API
Portal web api can be accessed via next url: YOUR_PORTAL_URL/_api.
To perform any action you will need to send a request to correct URL (api + entityset name) with the proper payload. Below you can find a small overview between action and request type:
- Create - POST
- Update - PATCH
- Update single property - PUT
- Delete - DELETE
- Add reference - POST
- Update reference - PUT
- Disassociate - DELETE
For example to create contact you will send POST request with json payload to next url YOUR_PORTAL_URL/_api/contacts.
Unlike XRM library inside CDS, we don’t have anything like this OOTB, so you will need to make sure that you are using proper URL and request type. Luckily Aung Khaing in his awesome library XrmPortalJs already added support for Web API to make our lives easier - check it out.
To be fair to Microsoft they provide us with a convenient wrapper that can be found below (for the latest version check documentation).
Let’s split this code snippet apart to better understand how it works and what’s inside.
To call Web API we will need to call webapi.safeAjax function which accepts one argument ajaxOptions which is a standard object with properties for ajax request.
First thing this function creates deferredAjax object
By definition from jQuery official docs:
Deferred - a factory function that returns a chainable utility object with methods to register multiple callbacks into callback queues, invoke callback queues, and relay the success or failure state of any synchronous or asynchronous function.
Let’s take a look at the next line:
Remember earlier I was mentioning some CSRF token that needs to be included with each request? Well, that’s how you get it. MS included a special object called shell with function getTokenDeferred that returns the necessary token.
Next lines are pretty straightforward - we are just adding received token to the request headers.
After that, we have everything that we need to perform our ajax request.
You might notice that in the call we are using validateLoginSession function. This function is also provided to us by MS. As the name suggest it validates if the user is logged in and if his session is still valid. If the user is not logged in it will redirect to the login screen by another build-in function called redirectToLogin.
Example API call
Hopefully, now you understand how MS snippet works. If not - don’t worry as you can just use it as is. Just paste the snippet in your page and use it according to docs.
Let’s say we want to create a contact with name John Smith and email firstname.lastname@example.org. Also we want to show in console id of newly created entity. Our request will look like this:
The URL for your entity will contain not the entity name ie contact but rather entity set name ie contacts. This might be obvious if you used CDS Web API before, but if not might be a bit confusing.
In this article, I described what is Portal Web API, why we need it and also how to use it. I hope you find this article useful. Keep an eye on my blog as soon I will provide a detailed example on how to use Portal Web API to create Excel-like edit experience for your Portal