SOAP vs REST vs GraphQL for Dynamics 365

Three predominant API styles offer different trade-offs for Dynamics 365 integrations: SOAP (the legacy enterprise standard), REST/OData (the dominant modern API style, what Dataverse uses), and GraphQL (the modern query-language alternative). Each has a place; choosing wisely matters.

SOAP overview.

• XML-based.
• WSDL contract.
• Strict typing.
• Built-in standards (WS-Security, WS-AtomicTransaction).
• Verbose payloads.

Origin: late 1990s enterprise integration; still common in legacy.

REST overview.

• Resource-oriented.
• HTTP verbs (GET, POST, PUT, DELETE).
• JSON typical.
• Stateless.
• Lighter than SOAP.

Dominant since mid-2000s; modern default.

OData. A specific REST flavour:

• Standardised query semantics ($select, $filter, etc.).
• Used by Dataverse and F&O.
• Rich query capability.

GraphQL overview.

• Single endpoint.
• Client specifies query shape.
• Strongly typed schema.
• Subscriptions for real-time.
• One round-trip for complex data.

Emerged 2015 from Facebook; popular for client-rich apps.

Comparison.

| Aspect | SOAP | REST/OData | GraphQL | |---|---|---|---| | Format | XML | JSON | JSON | | Verbosity | High | Moderate | Moderate | | Contract | WSDL | OpenAPI | Schema | | Query flexibility | Low | Moderate (OData) | High | | Caching | Hard | HTTP-friendly | Custom | | Tools | Mature, enterprise | Vast | Growing | | Real-time | WS-* extensions | Push patterns | Subscriptions |

Dynamics 365 native.

• Dataverse — REST/OData. SOAP organization service still supported but deprecated.
• F&O — REST/OData via data entities. Custom services can use either.
• GraphQL — not native; available via wrappers.

For Dynamics integrations, REST/OData is the canonical choice.

When SOAP still appears.

• Integration with legacy enterprise systems (SAP, mainframes, banking).
• Existing investments unfeasible to migrate.
• Specific industry standards requiring SOAP.
• Some Microsoft legacy APIs (older organization service).

For Dynamics, SOAP is for legacy compat, not new development.

When REST/OData wins (most Dynamics scenarios).

• Calling Dynamics from any system.
• Standard tools and libraries.
• HTTP-friendly (caching, proxies).
• Lighter than SOAP.

Default for new Dynamics integrations.

When GraphQL helps.

• Front-end consumer benefits from query flexibility.
• Mobile / bandwidth-constrained scenarios — request only what's needed.
• Multiple data sources federated.
• Strong developer experience preference.

Less common in Dynamics native scenarios; useful when fronting Dynamics + other systems.

Performance comparison.

• REST — multiple endpoints; potentially multiple round-trips for related data.
• OData $expand — fetch related in one call.
• GraphQL — request exact shape; one round-trip.
• SOAP — typically heavier payloads.

For complex queries, GraphQL can be most efficient; OData $expand often sufficient.

Caching.

• REST — HTTP caching (ETags, Cache-Control).
• GraphQL — harder; POST-based queries.
• SOAP — typically no caching.

Caching favours REST.

Versioning.

• REST — /v1/, /v2/ paths or headers.
• GraphQL — schema evolution (deprecate fields).
• SOAP — namespace versions.

Each has pattern; all manageable.

Tooling.

• REST — Swagger / OpenAPI, Postman, curl, every language.
• OData — additional tools for OData specifically.
• GraphQL — Apollo, Relay, GraphQL Playground.
• SOAP — older tools; still many.

For Dynamics, REST tooling dominant.

Security.

• REST — OAuth 2.0 typical.
• GraphQL — same.
• SOAP — WS-Security with signatures and encryption.

Modern: OAuth for all; WS-Security in legacy contexts.

Custom Dynamics services.

• OData custom actions / functions — extend Dataverse standard API.
• Custom REST APIs in Azure Functions — for non-Dataverse logic.
• GraphQL wrappers — for specific scenarios.
• SOAP services — rare; for legacy integration.

The right choice depends on consumer and pattern.

Multi-API support.

• Some integrations expose multiple flavours.
• API Gateway abstracts; consumers choose.
• More work but maximises consumer choice.

Migration considerations.

• SOAP → REST — common modernisation; significant effort.
• REST → GraphQL — quality-of-life upgrade; substantial work.
• REST to additional GraphQL — coexist; not migration.

Common pitfalls.

• SOAP for new development. Almost always wrong choice today.
• REST without OpenAPI — undiscoverable, hard to integrate.
• GraphQL without query depth limits — DoS vulnerability.
• OData over-fetch — without $select, fetching too much.
• API style chosen by trend, not fit.

Best practices.

• Default to REST/OData for Dynamics consumers.
• Document with OpenAPI.
• Use OAuth.
• Version explicitly.
• Consider GraphQL for complex client-rich apps.
• Maintain SOAP only for legacy.

Hybrid landscapes. Most enterprises have all three:

• Legacy SOAP for old integrations.
• REST/OData for most.
• GraphQL for specific scenarios.

Not religious choice; pragmatic per integration.

Strategic positioning. REST/OData is the right default for Dynamics 365 integrations. GraphQL is occasionally useful when client experience demands. SOAP is for legacy connectivity only.

For architects:

• Choose pragmatically per integration.
• Standardise where possible.
• Document API styles in architecture.
• Plan modernisation of SOAP legacy.

The teams that obsess over API style choice often lose sight of what matters: clear contracts, reliable operations, manageable evolution. Pick a style, do it well, focus on the outcomes.