API Playground

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.

📘

Note

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)

🚧

Note

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.

🚧

Note

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:

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 thetrace_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.