Salesforce offers hundreds of well-documented REST and SOAP APIs that can help with all your integration needs. While the documentation and the Postman API collection help you explore these APIs, they must be documented in a system-understandable format for external systems to quickly consume them. In this blog post, we’ll talk about a new feature that’ll allow you to quickly integrate Salesforce to an external system.

API specifications

A specification describes what an API can do, how to consume it, parameters, authentication methods it accepts, and what to expect back as a response in the form of a human and machine-readable format. The industry standard for SOAP API specification is WSDL, and the REST API specification is OpenAPI or OAS (previously known as Swagger). The latest version of OAS is 3.0 (OAS3).

These specifications are easily consumed by external systems, tools, API clients or codegen libraries accelerating time-to-market for an API-driven solution. This is the principle behind the External Services wizard in Salesforce that helps you integrate with third-party systems faster by allowing you to import their API specification.

Salesforce can generate SOAP specifications in the form of a WSDL file that is tailored to your org. When it comes to REST specifications, we have OAS3 specifications for APIs like Einstein Vision and Language REST APIs, but nothing for the core platform, which is why we’ve piloted the ability to generate an OAS3 spec for Salesforce REST APIs.

OpenAPI 3.0 spec for sObjects REST resources (Pilot)

We started this journey in Winter ‘21 by producing “standard” specifications for the sObjects REST API. In Spring ‘21 we’re enhancing this by giving you an endpoint that lets you download a specification that reflects your org’s unique endpoints and object customizations.

The generated specification describes the below sObject resources:

  • /sobjects
  • /sobjects/{sObjectName}
  • /sobjects/{sObjectName}/{Id}
  • /sobjects/{sObjectName}/describe

Below is a sample specification. It contains some basic info about the API, the base URL of the org, the Auth mechanisms it supports, and lists different paths. Each path is an endpoint from the sObjects REST API, and there are different paths for different objects in the org. Since the specification reflects your org’s customizations, you can see dedicated paths for your custom objects as well. For example, this specification has a path "/sobjects/Product__c" for the Product__c custom object.

Watch the demo Integrate with the Salesforce REST API using OpenAPI 3 from DreamTX for a deeper dive into how to generate the specification and consume it in Postman. Watch the session See the Future of APIs at Salesforce from the Developer Track at DreamTX to see how the new OAS3 specification can simplify the process of integrating Salesforce with a Lightning Web Components Open Source app that uses Node.js as its backend.

What’s next

If you’d like to participate in the “OpenAPI 3.0 Spec for sObjects REST Resources” pilot, contact your Salesforce Account Executive or open a support case. Your feedback is very important to us, so that we can give you the best developer experience possible.

Also, before Summer ‘21 comes out, don’t forget to update your integrations to use API versions greater than 20.

Resources

About the author

Aditya Naag Topalli is a 13x Certified Lead Developer Evangelist at Salesforce. He focuses on Lightning Web Components, Einstein Platform Services, and integrations. He writes technical content and speaks frequently at webinars and conferences around the world. Follow him on Twitter @adityanaag and checkout his contributions on GitHub.

Get the latest Salesforce Developer blog posts and podcast episodes via Slack or RSS.

Add to Slack Subscribe to RSS