Whether to Use Vendor SDKs to Access Vendor Services

This blog post presents perspectives on whether to use vendor SDKs or access their HTTP/JSON service endpoints directly, specifically in the context of the Contentstack SaaS headless content management system but with considerations relevant to any headless CMS or service-oriented application. If you have perspectives on whether and when to use the vendor’s SDK to access HTTP/JSON services, please comment on this blog post.

For some background perspective, see these previous blog posts:

• Why Isn’t This In the .NET SDK? – Deliverystack.net
• The (Best) [CMS] API Has No Methods – Deliverystack.net

Contentstack provide three main sets of services:

• Content management services support read/write data manipulation, such as editorial and publishing operations through the CMS UI and import processes using the HTTP API.
• Content delivery services support read-only data retrieval of published textual data.
• Content management services manage textual metadata about binary assets. Content delivery services deliver that asset metadata data. Contentstack provides separate storage and services for assets services including server-side manipulation of images before edge caching.

Organizations can use these services to implement almost any kind of solution. Most organizations implement websites that consume content delivery services. Many customers implement applications dedicated to specific lines of devices, such as mobile apps for the major platforms, that contain and consume content from the CMS.

For each content delivery and custom content management solution, you can use the platform technology of your choice, with or without the SDK from the vendor. Using an SDK from the vendor has short-term advantages in reducing development time and may have long-term advantages in terms of support from the vendor, but also leads to tighter coupling between the content solution and the vendor, where headless intends to avoid tight coupling.

The choice of whether to use an SDK from the vendor may vary by content delivery solution. For example, an app for a mobile device seems relatively tightly coupled in any case, which would encourage using the vendor’s SDK unless the developers want responsibility for the networking code. Developers more fluent in NodeJS and other technologies used by their vendors may be more interested in using the vendor’s SDK for that platform. I would be more likely to use the vendor’s SDK in Jamstack applications if I would let them access vendor content delivery services directly, but I would prefer to have my applications access service endpoints that I control anyway.

At least for .NET, for the following reasons I seem to prefer accessing content management and content delivery services directly rather than using the vendor’s SDK:

• SDKs introduce strong coupling to the vendor that requires synchronizing of vendor API, SDK, and custom solution build and deployment processes.
• SDKs may not provide complete service endpoint coverage, for example around new endpoints and features, in which case solutions must fall back to manual network programming.
• At least in .NET, the network programming and JSON processing is relatively trivial.
• The SDK must expose all vendor functionality generically where a custom solution can optimize specific use cases.
• The SDK introduces a dependency on someone code written by someone else, and almost certainly depends on third-party libraries that I may prefer to avoid.
• Invoking service endpoints directly requires awareness and allows instrumentation and control of all vendor APIs in use, helping to minimize the range and the number of vendor API calls, again loosening coupling.
• SDKs may not provide certain desired flexibility and control.
• I prefer to have the deeper understanding of the vendor’s product required by reading API documentation, viewing JSON structures, and constructing HTTP requests rather than reading and using the SDK documentation and abstractions, which may not always match my mental models.

There are certainly cases where using the vendor’s SDK appears advantageous. If I would otherwise spend significant effort writing my own version of the SDK, then I might use the vendor’s SDK. In the context of headless CMS, the most complex aspect appears to be constructing queries against the CMS, whether in the vendor’s proprietary query syntax or a custom GraphQL JSON format. Personally, I prefer to minimize CMS queries including GraphQL in favor of using search indexes. If I needed to implement something like CMS query, I would still prefer to copy significant source code from the vendor’s SDK to construct the required JSON or query string parameters rather than depending directly on that SDK. It would take something larger than that to get me to use the .NET SDK rather than managing the HTTP API calls myself.