Search
  • KrazyTech Team

Learn MOAR with Spring ‘21: OpenAPI 3.0 Spec for REST API

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 customization's.



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.


{
 "openapi": "3.0.1",
 "info": {
 "title": "Lightning Platform REST API",
 "description": "REST API provides a powerful, convenient, and simple Web services API for interacting with Lightning Platform...",
 "version": "51.0"
 },
 "servers": [
 {
 "url": "https://mydomain.salesforce.com/services/data/v51.0"
 }
 ],
 "components": {
 "securitySchemes": {
 "openIDConnectDiscovery": {
 ...
 },
 "bearerAuth": {
 ...
 },
 "oAuth2": {
 ...
 }
 }
 },
 "paths": {
 "/sobjects": {
 ...
 },
 "/sobjects/Account":{
 ...
 },
 "/sobjects/Account/{id}":{
 ...
 },
 "/sobjects/Product__c": {
 ...
 }
 ...
 }
}


Post Source link





8 views0 comments