Workday Extend Graph API vs. Workday REST API: Endpoints, Scopes, and Versioning

Workday recommends the Workday Graph API first for reading and writing interactive data in Workday Extend apps because a single POST request to /graphql/{version} returns only the fields you select across both Workday-delivered objects and your app's Custom Business Objects (CBOs). When a Graph API query or mutation does not cover a required object or action, Workday's decision tree falls back to versioned Workday REST APIs (/{serviceName}/{version}), then paginated WQL, RaaS, and finally synchronous SOAP web services through Orchestrate.

Both Graph API and REST API calls from an Extend app or orchestration route through the regional Workday Cloud Platform (WCP) API Gateway, enforce user-based configurable security, and return a default page size of 20 records (up to a maximum of 100). Choosing the right API depends on whether the schema exposes your target fields, how many network round-trips your page or orchestration can afford, and how your endpoints handle partial errors and versioning.

Graph API vs. Workday REST API at a glance

Endpoint architecture and regional gateways

Every API call made from an Extend page or an orchestration must target the regional API Gateway base URL associated with your developer account—never a tenant-specific hostname.

Calling a gateway URL that does not match your account's region results in an immediate 401 Unauthorized response.

How versioning differs

Workday REST APIs version each functional service independently—for example, staffing/v7/workers or businessProcess/v1/events. In the REST API Explorer, Production Services list stable versions, whereas Experimental Services carry labs, alpha, or beta designations that Workday warns against using in production apps because their contracts will change.

The Workday Graph API exposes a single versioned endpoint (/graphql/v1) backed by a unified GraphQL schema. Instead of registering multiple service base URLs in your App Metadata (amd) dataProviders[] array, a PMD endpoint can reference the built-in "baseUrlType": "workday-graph" to query staffing data, procurement data, and your own Extend model components from the same URL.

Custom Business Objects in Graph API vs. REST API

When you deploy an Extend app containing model components (Business Objects, Attachment Objects, or Event Business Objects), Workday generates both REST endpoints and Graph API schema operations for them.

Generated Graph API operations for model components

In the Graph API schema, Workday prefixes every generated query and mutation with your app's reference ID so operation names remain unique across the tenant (note that you must refresh your browser in the Graph API Explorer after deploying model changes to see the updated schema):

• Queries: <appRefId>_<BusinessObjectName>, <appRefId>_<AttachmentName>, and <appRefId>_<EventBusinessObjectName>
• Business object mutations: <appRefId>_create<BusinessObjectName>, <appRefId>_update<BusinessObjectName>, and <appRefId>_delete<BusinessObjectName>
• Attachment mutations: <appRefId>_create<AttachmentName>, <appRefId>_create<AttachmentsCollectionName>, <appRefId>_update<AttachmentName>, and <appRefId>_delete<AttachmentName>

If your app reference ID or any field name starts with a digit, the Graph API schema prepends App_ to the identifier. And if you import an app into a different developer account with a new reference ID, you must update the query and mutation names in your PMDs and Graph Query components to match the new <appRefId>.

Generated REST endpoints for model components

Simultaneously, Workday exposes a REST collection endpoint for each Custom Business Object:

https://{basePath}/apps/{appId}/v1/{defaultCollectionName}

The CBO REST API supports GET, POST, PUT, PATCH (for apps deployed after November 10, 2020), and DELETE. It also automatically generates query parameters for all indexed (SINGLE_INSTANCE) fields on the business object, and supports bulk creation, updates, or deletions of up to 100 instances in a single call by appending ?bulk=true to the URL and passing a data[] array.

Security domains, policies, and scopes

Neither Graph API nor Workday REST APIs bypass Workday's configurable security model. Both execute under the OAuth context of the signed-in user (or the Integration System User when called from an orchestration configured with ISU credentials).

Common security requirements

1. Report/Task Permissions are mandatory: When configuring a domain security policy for either REST or Graph API access, you must grant Report/Task Permissions (View for reads/queries, Modify for writes/mutations) to the user's security group. Granting Integration Permissions on a domain only applies to Workday SOAP web services and has no effect on REST or Graph API calls.
2. Business process initiation rights: If a REST POST or Graph API mutation initiates a business process, the user's security group must hold initiation permission on the corresponding business process security policy.
3. Sub-resource and parent access: For REST sub-resources such as POST /workers/{id}/requestTimeOff, the user must also have security access to the parent workers/{id} resource.

Additional security domains required by Graph API

To call the Workday Graph API, users need access to three layers of domain security:

• Workday Graph API Applications: Governs overall access to the Graph API endpoint. Workday notes that a common setup is assigning the All Users security group to this domain.
• Graph API Descriptor: A system security domain that grants access to descriptor fields across the schema. Leave this domain at its default configuration.
• Underlying object and data source domains: Listed under the Secured by: section of each query field, data source, and mutation in the Graph API Explorer documentation. For example, running a worker query that uses the indexedAllWorkers data source requires an active security policy on Indexed Data Source: Workers in addition to the domains securing the requested worker fields (such as Worker Data: Current Staffing Information).

When calling CBO REST APIs from an external application outside Workday, you must register an OAuth 2.0 API client on the Developer Site and select the Workday-Owned scope.

Calling Graph API vs. REST API in PMDs and Orchestrations

In Extend Page Metadata (PMD)

For a Workday REST API, you declare the service base URL in your .amd dataProviders[] list and configure a GET inbound endpoint or a POST/PUT/DELETE outbound endpoint using url and baseUrlType.

For the Workday Graph API, both inbound queries and outbound mutations use "httpMethod": "POST" and "baseUrlType": "workday-graph" with a graphQuery block (either inline or referencing a reusable Graph Query component via queryId):

{
  "name": "getActiveWorkers",
  "baseUrlType": "workday-graph",
  "httpMethod": "POST",
  "failOnStatusCodes": [{ "code": 400 }],
  "graphQuery": {
    "query": "query workersList($ds: Worker_DataSources!, $limit: BigInt, $offset: BigInt) { worker(dataSource: $ds, limit: $limit, offset: $offset) { data { workdayID { id } descriptor businessTitle } total } }",
    "variables": {
      "ds": {
        "indexedAllWorkers": {
          "filter": {
            "indexedAllWorkersFilter": {
              "isActive": true
            }
          }
        }
      },
      "limit": "<% empty pagingVariables.limit ? 20 : pagingVariables.limit.toInt() %>",
      "offset": "<% empty pagingVariables.offset ? 0 : pagingVariables.offset.toInt() %>"
    }
  }
}

In Orchestration Builder

When calling the Graph API from an orchestration using the Send Workday API Request step, keep two formatting and runtime rules in mind:

1. Single-line query strings only: While PMD graphQuery blocks and the Graph API Explorer allow multi-line GraphQL strings, Orchestration Builder and external REST clients require the query string in the JSON body to be on a single line with no newline characters. Use Copy Raw JSON in the Graph API Explorer and paste it into a Create JSON step's Generate Structure dialog.
2. Warning headers on mutations: If a Graph API mutation or REST write triggers non-critical Workday validation warnings, you can pass the header wd-warning-action: updateonwarning so Workday commits the change and returns the warning details in the response.

Troubleshooting common Graph API and REST errors

HTTP 200 responses that still fail in PMD

Unlike REST endpoints that return 4xx or 5xx when a field cannot be resolved, the Graph API returns 200 OK whenever the request is syntactically valid and reaches the Graph server—even if individual fields or mutations fail during execution. When a field resolution fails, the JSON response contains an errors[] array alongside partial or null data. In an Extend PMD page, any Graph API response containing errors[] is automatically treated as an endpoint error even though the HTTP status code is 200. For syntax or variable-type errors (which return HTTP 400), always include {"code": 400} in the endpoint's failOnStatusCodes array.

500-instance error on related business objects

When you traverse a multi-instance field as a related business object in a Graph API query (or in WQL), Workday enforces a hard cap of 500 related business object instances. If a record has more than 500 instances on that relationship, the query fails with an error. Query the child object directly with pagination (limit and offset) instead of nesting it as a multi-instance field.

Dynamic values inside the Graph query string

PMD onSend scripts can inspect a Graph API payload for debugging, but you cannot dynamically concatenate values into the static graphQuery.query string at runtime. Always declare $variable placeholders in query and pass dynamic PMD expressions inside graphQuery.variables (or parameters when calling a self-contained Graph Query component, noting that variables and parameters are mutually exclusive when referencing a queryId).

How kiweely fits

kiweely inspects your live tenant metadata, security domains, and Extend model components directly so you can build and test Graph API queries, CBO REST endpoints, PMD pages, and orchestrations without guessing field names or security policies. In your Workday personal developer account and its tenant, Kiweely Personal is free (Kiweely Personal is free for your Workday personal developer account and its tenant. Any other tenant needs a Personal licence, $99 a month, or a seat in your firm.).

Frequently asked questions

Should I use the Graph API or REST API for a new Workday Extend app?

Workday's API Decision Guidance recommends starting with the Workday Graph API for both reading and writing data in Extend apps because it consolidates multiple calls into one request and returns only the fields your page needs. Use Workday REST APIs when the specific business object or action is not yet exposed in the Graph API schema, or when you need CBO REST ?bulk=true operations for up to 100 records.

Why did my Graph API query stop working after I imported the Extend app into another account?

Generated Graph API queries and mutations for Extend model components prefix the operation name with your app's reference ID (<appRefId>_<BusinessObjectName>). When you import an app into a different developer account that assigns a new app reference ID, you must update the operation names and input types in your Graph queries to use the target account's reference ID.

Why does my user get a permission error in Graph API when they already have access to the worker domain?

In addition to the domain policies securing the specific business objects and fields (such as Worker Data: Current Staffing Information), Graph API users must have Report/Task permission on the Workday Graph API Applications domain, and on the security policy for the underlying data source (for example, Indexed Data Source: Workers when using indexedAllWorkers).