API Playground enables users to test API requests using built-in connectors, powered with a curated and vetted API Collection for each external system.
API Playground can be used for the following scenarios:
It’s available under Moveworks Setup > Core Platform > Connectors > API Playground.
Before viewing API endpoints, you must select a connector.
Steps:
Go to the Connector tab in the API Playground.
Use the Select Connector dropdown to choose the specific connector for the external system whose APIs you want to test.
Once a connector is selected:
You can switch connectors at any time using the same dropdown.
After selecting a connector, the API Collection panel displays 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 resources.
For example, in Okta, the /api/v1/users endpoint is used to retrieve all users in the system for importing users into Moveworks.
When you select an API endpoint from a collection, the HTTP method is automatically selected, the Base URL is automatically resolved, the endpoint path is populated and query parameters and request body are pre-populated where applicable. This helps ensure APIs are executed with the correct configuration without requiring manual setup.
Features:
APIs are organized into logical collections such as Users, Groups, Content, Permissions..etc
Use the Search APIs field to quickly find endpoints.
Click on any API to load it into the editor.
When an API is selected:
The HTTP method is auto-selected.
The Base URL is automatically resolved.
The Endpoint path is populated.
Query parameters (if applicable) are pre-filled.
Request body (if applicable) is pre-populated.
The correct authentication profile is inferred and applied.
The right panel allows you to review, modify and test the API request.
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 serverPUT: Update or replace an existing resource entirelyPATCH: Partially update an existing resourceDELETE: Remove a resource from the server
The Base URL represents the root endpoint of an API. For example, in the URL https://api.example.com/v1/users, the base URL is https://api.example.com
It is used to construct API endpoints by appending paths such as /users, /products, or /orders to access different resources
In API Playground, the Base URL field is not editable, as it is automatically resolved based on the selected API from the API Collection of the chosen connector.
The Endpoint URL represents the specific API path being called.
https://api.example.com/v1/users, the endpoint is /v1/users.
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.
After importing built-in connectors, there’s no need to add Authorization field as an API Header.
Query parameters contain additional data in key-value pairs appended to the URL to filter, sort, or modify the API request. These may include search terms, pagination limits, or 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 with value price and order is the key with value asc.
Use Cases of Query Params:
https://example.com/products?category=shoes)https://example.com/products?sort=price&order=desc)https://example.com/products?page=2&limit=10)https://example.com/products?q=blue shirt)The Request Body contains data sent from the client to the server as part of an API request. It is typically used in POST, PUT, or PATCH operations to create or update resources.
In API Playground:
Test Button allows you to send API requests to external systems and view the responses, status codes, and any errors returned from the server.
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.
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:
x-www-form-urlencoded request body typetrace_id displayed in the UI for errors encountered in the API Playground?
trace_id is not shown in the UI for errors within the API Playground.