New Feature: API Explorer category groupings/filter and reading mode

The new API Explorer tool has been updated based on feedback we've received since launch. Here's a rundown of the changes found at https://developer.genesys.cloud/devapps/api-explorer.

  1. Browse by API Category/Category Filter - The category filters on the right-hand column allow you to filter the list of resources on the page to show only the ones you check. This should assist in replicating the previous experience of having the API endpoint documentation segregated by category, and all at the same level/place in the site.
  2. API Resource Group by Category - API resources are now grouped by category in collapsible containers. Displayed category groups are limited to categories that contain resources based on the resource filter (textbox above) AND the selected categories.
  3. API Doc Reading Mode - Enabling reading mode disables all of the interactive parts of the new API Explorer tool to make it more closely resemble the previous read-only experience. This setting applies globally on the site and can be toggled globally by changing it from any resource.

Please comment below with any comments, ideas, and constructive criticism you have about the API Explorer Beta tool. We're still in active development it and want to keep an open dialogue with the community so we can incorporate your feedback as we go.

Ac couple of the upcoming features we are working on are:

  • Integrated Analytics query builder functionality - the request builder will be enhanced with additional context to guide the creation of queries. This will come with some new and updated guides documenting various queries that contain embedded API Explorer resources (execute the queries directly in the guide page!).
  • Integrated Search query builder - same enhancements as for Analytics, but for the Search APIs. Will also come with some new guides with embedded resources.
2 Likes

Hmm... The "API Resource Filter" keeps getting auto-filled with a value from my browser (my email address) and it therefore fails to display anything...

Am I the only one?

Edit: If I log in / add account (in the top right) it stops happening :+1:

1 Like

@JDunn I'll check the form's attributes to make sure disable autofill is suggested, but it's ultimately up to the browser and your extensions (like LastPass) if they respect the setting. I'd recommend disabling form fills for the site though; we never collect credentials on this domain.

Thank you again, @tim.smith! I love the changes! It is so much easier to find the exact API endpoint I need.

Question: with the upcoming features, will these still be able to be turned on and off (e.g. reading mode) like how you currently have the request section?

@Heather_Rauch Glad to hear it's an improvement for you! The reading mode toggle is a permanent feature and will apply to any future enhancements. For the case of the query builders, you'll only see that functionality when configuring the request while reading mode is off.

1 Like

I like the ability to filter. But when I use an account to login, the Filter disappears. Is anyone else having that issue. I'm not sure it matters, but it's when I using the clone user functionality for our customer's GC orgs.

When I "Add Account", it isn't using the cloned user of the customer org either, it is using my user from the associated Partner org for that region (which isn't much help). I can get around this by forcing a login from the Add Account functionality. But when I do that, I lose the filter functionality.

It also seems the date parameters for the queries are hit and miss. I'm unable to type in a date I want to use manually. And most of the time, it doesn't accept input from the calendar picker:

Afterwards, when I go to execute the query, I also get a date format error (on a date I'm unable to manipulate):

{
"message": "Date-only values must be specified using a four digit year and two digit month and day in the format yyyy-MM-dd",
"code": "invalid.local.date",
"status": 400,
"details": [],
"errors": []
}

And lastly, is there a place I can go to see the full and updated query I'm attempting to run? In the previous version, the full query was front and center, just above the results. The closest I can on the BETA version is in the HTTP tab. But it doesn't update to what is actually being called. For example, below, I expect to see something similar to:

".../workforcemanagement/managementunits?expand=details"

I hope this helps to explain some issues I'm seeing. I've tried multiple browsers (mostly Edge and FireFox, but some Chrome as well) and still seeing issues after deleting my cache.

Thanks,
Trent.

Hey Trent, long time no see! Hope you're doing well. Thanks for the feedback!

I haven't gotten other reports of this and haven't been able to reproduce it myself. The filter box is unrelated to authorization and the app itself isn't aware of the nature of the relationship between the user/org. That shouldn't have anything to do with the issue, but I'll keep it in mind. To confirm, this screenshot is the filter you're talking about, correct?

Can you provide some additional info?

  • OS
  • Browser
  • Screenshot of the whole page when the filter is missing
  • Are there any errors/warnings in the JavaScript console?
  • Are there any steps you can take to make the filter come back?
  • Is the issue contained to adding specific accounts or any account?

The site is using the standard behavior for Genesys Cloud authentication; the site simply redirects you to the login page, which will auto-complete with whatever account is remembered by the login screen. Forcing the login prompt ignores the remembered account and always prompts you to allow you to complete the login flow as desired.

the cloned user of the customer org

Can you explain your workflow here? How are you logging in to the customer org? Are you using the same browser window/session for that and the dev center?

What I wouldn't give for date-like types to be consistent throughout the API's definition... It sounds like there are some date variants we haven't handled correctly. Can you point out specifically which fields on which API resources you're having an issue with?

Not currently within the app itself. That's something we can add though. For now, the workaround would be to open the Network tab in your browser and inspect the request it makes when you submit it.

I am currently using MS Edge Version 100.0.1185.29 (Official build) (64-bit)
I just tested this and both my text filters and selected categories were wiped out upon selecting my account.

Hopefully this helps,
Heather

And you too! Seems just like yesterday (cough 15+ years ago cough cough) we were sitting in the queues!

Naturally, as I'm going through detailing my work flow and taking screenshots, I'm now unable to reproduce the problem. And no, it was the category filter on the right hand side:

And not logging directly into the customer org per se. I login to our regional Support org, then select the customer I need to log into from the Clients selection up in the menu bar:

I'll keep trying to reproduce, but it looks like @Heather_Rauch may have a similar problem as well.

Being able to see the full updated query would be awesome and real time saver. Having it right there and updated dynamically would allow an immediate copy and paste into other tools, after confirming the expected result set in the API Explorer itself.

In terms of the date field issues, I'm using the weekDateId field from the
/api/v2/workforcemanagement/managementunits/{managementUnitId}/weeks/{weekDateId}/shifttrades API call.

In the old version of the Explorer, I could just throw in a date to use without issue. In this version, I can't insert manually, or select a date from the calendar picker. And when I use the date that is in the tool by default, it throws the formatting error mentioned in my last post.

Thanks for the additional info @Heather_Rauch and @Trent_Vance! I think we're on the same page now.

The text for the API Resource Filter is intentionally not saved as it's meant to be a transient setting. I'll bring this item back for discussion. Particularly since the category filters are supposed to be persistent, I can see that it seems odd that the filter text wouldn't also be persistent.

Regarding the category filters being reset after adding an account, have you enabled the Allow browser storage setting? Privacy and client-side storage has been implemented very strictly in this app. If you don't have that checkbox checked, the app is unable to persist anything when you refresh the page or navigate away (e.g. completing an OAuth flow). The only way I've found to lose that setting is if browser storage isn't enabled; if you can readily reproduce with that setting enabled, please let me know steps to reproduce.

I had a hunch that is what you were doing. I'll check in with the auth team to see exactly what's happening when you log in that way. IIRC, that method doesn't ever take you to the Genesys Cloud login screen, which means the auth cookie used by the login screen never gets updated to that account. So the "remembered" account is the last one where you entered your credentials. If there's any way we can support this use case, via updates to the dev center or the auth process, I'll push to get it done.

@tim.smith I just tested this out. I was pleased to find that not only are the search categories retained, but dark mode is now also retained on browser refresh and upon adding an account. The free text search does go away on refresh, as you stated. I am not personally bothered by that bit. However, to your previous point, it is inconsistent and may help others to have the behavior match the categories.

Thanks again!

Great to hear! I had previously added some tooltips to help warn people when they set settings that won't be remembered, but there were performance issues with the tooltips and they had to be removed until the performance issues are resolved. They'll be back. :slight_smile:

Hi Tim, I wanted to use the API Explorer to test out the Conversation Participant Attributes search but I don't actually see it in the API Explorer at all. Am I blind?

Conversation participant attributes search (genesys.cloud)

@JDunn If you scroll down on the left hand side, the API Explorer is located farther down under Developer Applications.
image

Hi Heather, thanks - I can see the API Explorer, but I can't see that particular API in the explorer to test with.

@JDunn That particular API is in preview. Preview APIs are on a separate page, but have the same API Explorer interface. It can be found here: POST /api/v2/conversations/participants/attributes/search

Ahh... I see what you mean. I searched "attributes" across all of the different API categories and only the PATCH method, used for updating participant attributes appear. I also do not see any listings for POST methods that are listed in the referenced article.

Would it be possible to add, at the very least, a link at the top of the API Explorer below the search bar, something to the effect of "Looking for an unlisted method? Check out the preview methods" so people know there are other places to look for related content?

Thanks again!

2 Likes

For sure. There's a few pieces of info that need to be added to that page to help provide context and link to related resources.

Ah, right, thanks - that's good.

It seems that calls to that API through the explorer aren't available yet on my org yet, but, I'll check back periodically.

Thanks again!

Capture