Generating an OpenAPI 3.0 Document for sObjects REST API (Beta)

Supported Editions

This beta feature is available to Developer Editions, Partner Developer Editions, sandboxes, and scratch orgs that have API Enabled.

About the Document

The OpenAPI document adheres to Version 3.0.1 of the OpenAPI Specification. For more information, see https://www.openapis.org.

What the OpenAPI Document Covers

This OpenAPI document describes these REST API resources that you can use to retrieve, create, and update your object data.

1. /services/data/v57.0/sobjects
   • Lists the available objects and their metadata for your data. Provides the organization encoding, and the maximum batch size permitted in queries.
   • See Describe Global.
2. /services/data/v57.0/sobjects/sObject
   • Describes the individual metadata for the specified object. Can create an object record. For example, retrieve the metadata for the Account object using the GET method or create an Account object using the POST method.
   • See sObject Basic Information.
3. /services/data/v57.0/sobjects/{sObject}/describe
   • Describes the individual metadata at all levels for sObjects
   • See sObject Describe.
4. /services/data/v57.0/sobjects/sObject/{id}
   • Accesses records based on the specified object ID. Retrieves, updates, or deletes records. Can retrieve field values. Use the GET method to retrieve records or fields, the DELETE method to delete records, and the PATCH method to update records.
   • See sObject Rows.
5. /services/data/v57.0/sobjects/{sObject}/deleted
   • Retrieves the list of individual deleted records within the timespan for sObjects
   • See sObject Get Deleted.
6. /services/data/vXX.X/sobjects/{sObject}/{id}/{blobField}
   • Retrieves the specified blob field from an individual record and returns it as binary data
   • See sObject Blob Get.

Enabling the Beta

Generating an OpenAPI Document

After the beta feature is enabled, generate the OpenAPI document by following these steps.

1. Send a POST request to
   1https://MyDomainName.my.salesforce.com/services/data/vXX.X/async/specifications/oas3

   The procedure in API version 56.0 has changed from the procedure in earlier API versions. This step now uses a POST request instead of a GET request.

   Note

   The API version in this POST request, XX.X, must be 54.0 or greater.

   If the server encounters errors processing the request, it reports a “Failed” status and returns a 4xx or 5xx status.

   The request body must be
   1{
   2   "resources" : [ selectors ]
   3}

   where selectors can be
   • "*" (to get all the resources)
   • or, one or more of the following selectors (to only get specific sections of the OpenAPI document)
     • "/services/data/v57.0/sobjects"
     • "/services/data/v57.0/sobjects/sObject" where sObject can be the name of any standard or custom object that you have access to in your org
     • "/services/data/v57.0/sobjects/sObject/{id}"
     • "/services/data/v57.0/sobjects/sObject/deleted"
     • "/services/data/v57.0/sobjects/{sObject}/deleted"
     • "/services/data/v57.0/sobjects/sObject/describe"
     • "/services/data/v57.0/sobjects/{sObject}/describe"
     • "/services/data/v57.0/sobjects/{sObject}/{id}/{blobField}"

     {blobField}, {id}, and {sObject} must be entered literally. They aren’t variables.

     Note

     Don’t add trailing slashes at the end of a selector, For example, "/services/data/v57.0/sobjects/" retrieves nothing.

     Note

     For the /describe and /deleted selectors, you can use either {sObject} literally or an object name. The response body for these requests is the same for all objects.

     Note

     The API version in the selectors must be the latest version, v57.0. (This does not need to be the same version as the POST request in Step 1 or the GET request in Step 3.)

     Note

     For example
     1{
     2   "resources" : ["*"]
     3}

     or
     1{
     2   "resources" : [
     3      "/services/data/v57.0/sobjects",
     4      "/services/data/v57.0/sobjects/Contact",
     5      "/services/data/v57.0/sobjects/Lead",
     6      "/services/data/v57.0/sobjects/Lead/{id}",
     7      "/services/data/v57.0/sobjects/{sObject}/deleted",
     8      "/services/data/v57.0/sobjects/Account/describe",
     9      "/services/data/v57.0/sobjects/{sObject}/{id}/{blobField}"
     10   ]
     11}

2. Assuming that the request can be parsed without errors, the server responds with HTTP status code 202 (Accepted) and a JSON response body that contains a URI where you can get the OpenAPI document. For example:
   1HTTP/1.1 202 Accepted
   2{
   3     "href" : "/v57.0/async/specifications/oas3/NTByUjAwMDAwMDAwMDBh"
   4}

   The last part of this URI (NTByUjAwMDAwMDAwMDBh in this example) is the locator ID for the OpenAPI document.

3. Send a GET request to the same URI with the locator ID appended. For example:
   1https://MyDomainName.my.salesforce.com/services/data/vXX.X/​async/​specifications/​oas3/​NTByUjAwMDAwMDAwMDBh

   The API version in this GET request, XX.X, must be 54.0 or greater.

   1. If the server isn’t finished preparing the OpenAPI document, it responds with a 202 (Accepted) status code and a status message of “Not Started” or “In Progress”. For example:
      1HTTP/1.1 202 Accepted
      2{
      3   "status" : "In Progress"
      4}

   2. If the server has finished, it responds with a 200 (OK) status and returns the OpenAPI document in the response body. For example:
      1HTTP/1.1 200 OK{
      2  "openapi": "3.0.1",
      3  "info": {
      4      "title": "Lightning Platform REST API",
      5      "description": "REST API provides you with programmatic access to your data in Salesforce. The flexibility and scalability of REST API make it an excellent choice for integrating Salesforce into your applications and for performing complex operations on a large scale. You can use REST API tools to create, manipulate, and search data in Salesforce by sending HTTP requests to endpoints in Salesforce. Depending on where you send requests, you access and operate on different pieces of information, called resources. Resources include records, query results, metadata, and more. ",
      6      "version": "57.0
      7  },
      8  "servers": [
      9      ...
      10  ],
      11  "security": [
      12      ...
      13  ],
      14  "paths": {
      15      "/sobjects": { ... },
      16      "/sobjects/Contact": { ... },
      17      "/sobjects/Lead": { ... },
      18      "/sobjects/Lead/{id}": { ... },
      19      "/sobjects/{sObject}/deleted": { ... },
      20      "/sobjects/{sObject}/describe": { ... },
      21      "/sobjects/{sObject}/{id}/{blobField}": { ... }
      22  },
      23  "components": {
      24      ...
      25  }
      26}

After the OpenAPI document is generated, you can retrieve the OpenAPI document again by using the same locator ID for 48 hours. After 48 hours, using that locator ID results in a 404 (Not Found) error.

A new OpenAPI document can only be generated every 6 hours per user. If you call /async/specifications/oas3 again within 6 hours of the last generation, even with different request bodies, the API returns the same locator ID.

If you select a resource that doesn’t match any of the supported resources, or you select a resource that you do not have permissions to access, the request does not fail but the OpenAPI document will not contain that resource and its path will not be visible in the OpenAPI document.

Giving Feedback

To give us your feedback, log in to Trailhead and then join the OpenAPI Specs for Salesforce REST APIs Trailblazer Community.

Your feedback is valuable and can help us find existing problems and inspire future change. We’re looking for general impressions, improvement suggestions, bugs, and feedback about how well this OpenAPI document aligns with your OpenAPI use cases.