***
title: API Playground
deprecated: false
hidden: false
metadata:
robots: index
-------------
## About
### What is API Playground?
API Playground enables users to test API requests using built-in connectors, powered with a curated and vetted API Collection for each external system.
### What is it used for?
API Playground can be used for the following scenarios:
* Verify authentication and scope of built-in connectors to prevent downstream impact
* Analyze API responses from external systems for various troubleshooting scenarios such as data inconsistencies, API rate or usage limits, permission issues, API response format changes, and more
* Review API responses of external systems while creating source-specific mappers
### Where does it reside?
It's available under **Moveworks Setup > Core Platform > Connectors > API Playground**.
## Demo
## API Playground Components
### Use Existing Connector
Use Existing Connector Button lets you select from the list of built-in connectors available in your org and import the specific connector for the external system whose APIs you want to test.
***Step 1:** Click on 'Use Existing Connector'*
***Step 2:** Selecting a built-in connector*
***Step 3:** Importing a selected built-in connector*
*Built-in connector has been successfully imported*
Base URL and Authorization data will be fetched from the successfully imported built-in connector.
### Pro Tip
Click the **cross button** next to the connector name in the top-right corner to clear that built-in connector and restart the selection process.
### Method
An API method defines the type of action the client wants the server to perform on a resource. The supported API methods in API Playground are:
* `GET`: Retrieve data from the server (read operation)
* `POST`: Create new resources or submit data to the server
* `PUT`: Update or replace an existing resource entirely
* `PATCH`: Partially update an existing resource
* `DELETE`: Remove a resource from the server
### Base URL
A Base URL is the root location of the API server or instance. For example, in the URL `https://api.example.com/v1/users`, the base URL is `https://api.example.com/v1`.
It can be used to construct additional endpoints by adding different paths, such as `/users`, `/products`, or `/orders`, to access different resources.
In API Playground, **the Base URL field is disabled as its value is derived from the successfully imported built-in connector's Base URL.**
### Endpoint URL
An API endpoint is a specific URL path that represents a particular resource within an API. For example, in the URL `https://api.example.com/v1/users`, the endpoint is `/users`.
**API Collection**
API Collection is a library of curated and vetted API endpoints from external systems used by Moveworks internally for various use cases such as fetching, creating, or updating a resource. For example, in Okta, `/api/v1/users` endpoint is used to get all users in the system for importing users in Moveworks.
Upon selecting an API endpoint, the method, query parameters and request body will be pre-populated, whenever applicable. (**🚧 Note:** Pre-populating the request body is planned for future improvements)
In API Playground, there are two ways you can provide the Endpoint URL value:
* **API Collections:** Select an API endpoint from a pre-defined API collection, which will appear as a dropdown when you click inside the input box
* **Custom Endpoint:** Type your own API endpoint that is not available in the API collection
### Pro tip
Start typing inside the Endpoint URL input box to search for the API endpoints you want to use.
### Authorization
Authorization verifies the identity of a user or application before granting access to an API's resources. Common auth methods are `Basic Auth`, `Oauth 2.0 Auth`, `API Key Auth`, and more.
In API Playground, **the Authorization tab is disabled as its value is derived from the authentication method used in the imported built-in connector.**
### Headers
API Headers contain additional metadata in key-value pairs about the request or response, such as content type, authorization, and other information exchanged between the client and server in API requests and responses.
### Pro tip
After importing built-in connectors, there's no need to add authorization as an API Header.
### Query Params
Query parameters contain additional data in key-value pairs appended to the URL to filter, sort, or modify the API request, such as search terms, pagination limits, and other criteria sent from the client to the server.
For example, in the URL `https://example.com/items?sort=price&order=asc`, `sort` and `order` are query parameters. *sort* is the key, and *price* is its value and *order* is another key with the value *asc*.
**Use Cases of Query Params:**
* **Filtering:** Selecting specific items based on certain criteria (e.g., `https://example.com/products?category=shoes`)
* **Sorting:** Arranging the results in a specific order (e.g., `https://example.com/products?sort=price&order=desc`)
* **Pagination:** Retrieving data in chunks or pages (e.g., `https://example.com/products?page=2&limit=10`)
* **Searching:** Finding items that match a specific search term (e.g., `https://example.com/products?q=blue shirt`)
Please do not include query parameters in the Endpoint URL field like `https://example.com/products?q=blue` shirt as they must be added in the QueryParams tab in key-value pairs.
### Request Body
API Request body contains data sent from the client to the server in the API request, such as JSON objects, form data, or other structured information used to create or update resources.
For now, only JSON format is supported in the request body of the API Playground.
### Response
**API Response:** Contains data and metadata returned from the server to the client after processing an API request, such as requested information, status codes, headers, and other details about the operation's outcome.
**API Response Code:** A status number returned by the server to communicate the outcome of an API request, such as success, client errors, or server errors.
### Clear and Test Buttons
**Clear Button**
Clear Button allows you to clear all fields in the API Playground and start from scratch. It requests your confirmation before clearing the data.
**Test Button**
Test Button allows you to send API requests to external systems and view the responses, status codes, and any errors returned from the server.
## Supported API Collections
As we have 80+ external systems for which API requests have to be curated & vetted, API collections will be rolled out in phases, staring with most important ones:
| Supported External System | Use Cases |
| :-------------------------- | :----------------------------------------------------------------------------------------------------- |
| JIRA | Approvals, Issues, Search, Service Desk, Workflows, Projects, Users, Authentication, and Configuration |
| FreshService | Tickets, Ticket Fields, Service Catalog, Conversations, Requesters, Groups, Agents, and Helpdesk |
| FreshDesk | Agents, Contacts, Groups, Knowledge, Tickets, and Helpdesk |
| Okta | Users, User Lifecycle, Multi-Factor Authentication, Groups, Applications, Logs, and Policies |
| Slack | Authentication, Users, Conversations, Messaging, Files, UserGroups, Bookmarks, Views, OAuth, and SCIM |
| Zendesk | Tickets, Search, Groups, Organizations, Comments, Ticket Fields, Users, Webhooks, and Triggers |
| Confluence | Content, Search, Spaces, and Groups |
| Sharepoint Online (Classic) | SitePages, Folders, Files, Sites, and Libs |
| Google Drive | Drives and Files |
| Microsoft Graph | Users and Groups |
| Notion | Databases, Pages, and Blocks |
| ServiceNow | 🚧 Available by 10th July |
| Workday | 🚧 Available by 15th July |
| Gsuite | 🚧 Available by 15th July |
## Upcoming Functionalities
* Ability to import cURL requests
* Testing APIs from blank slate
* Support for `x-www-form-urlencoded` request body type
* Auto-populate request body upon clicking API endpoint in API Playground
* Right Sidebar to display all the API Collections upfront
* RBAC implementation
* API Playground Logs
## FAQs
* **I can't find the API endpoint I want to use in the API collection. What should I do?**
* You can manually enter the API endpoint in the "Endpoint URL" field to access it.
* **Can I import cURL requests?**
* The import cURL functionality is not available in the current version, but it is planned for the next release of the API Playground.
* **Can I test APIs from a blank slate?**
* Testing APIs from blank slate functionality is not available in the current version, but it is planned for the next release of the API Playground.
* **I want to test the auth and scope of the connectors before creating them. How can I do it?**
* We recommend creating the connectors first and then testing them. The ability to test auth and scope before creating connectors will be available in the next release of the API Playground.
* **Is there a way to save my personal API collection?**
* No, saving individual API collections is not supported as we are focusing on developing a curated and vetted library of API collections.
* **Do you support running API scripts?**
* No, running scripts is currently not supported.
* **Can I view additional debug information like request headers, response headers, and request body?**
* Currently, displaying additional debug information such as request headers, response headers, and request body is not available.
* **Is the`trace_id` displayed in the UI for errors encountered in the API Playground?**
* At this time, the `trace_id` is not shown in the UI for errors within the API Playground.
* **Can I see the Bearer Token JWT Claims generated from the connector for authentication debugging?**
* Currently, viewing the Bearer Token JWT Claims for authentication debugging is not supported.
* **Does the API Playground automatically parse parameters when a URL is pasted in Endpoint URL field?**
* No, automatic parsing of parameters from pasted URLs is not supported in the API Playground. This is planned for the next release of the API Playground.