REST API Developer Guide

REST API
Quick Start
Examples
Generating an OpenAPI 3.0 Specification for sObjects REST API (Beta)
Reference
PDF

Newer Version Available

This content describes an older version of this product. View Latest

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

In this Beta, you can generate an OpenAPI specification for the sObjects REST API.

This feature is a Beta Service. Customer may opt to try such Beta Service in its sole discretion. Any use of the Beta Service is subject to the applicable Beta Services Terms provided at Agreements and Terms.

Note

This Beta feature enables you to generate an OpenAPI specification that represents four sObjects REST API resources reflecting the customizations and configurations in your org.

Supported Editions

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

About the Specification

This specification uses Version 3.0.1 of the OpenAPI Specification. For more information, see https://www.openapis.org.

This Beta specification is subject to change. Don’t build production integrations based on this specification.

Note

What the Specification Covers

This specification describes four REST API resources that allow you to retrieve, create, and update object data in your org.

  1. /services/data/vXX.X/sobjects/
    • Lists the available objects and their metadata for your organization’s data. In addition, it provides the organization encoding, as well as the maximum batch size permitted in queries.
    • See Describe Global.
  2. /services/data/vXX.X/sobjects/sObject/
    • Describes the individual metadata for the specified object. Can also be used to create a new record for a given object. For example, this can be used to retrieve the metadata for the Account object using the GET method, or create a new Account object using the POST method.
    • See sObject Basic Information.
  3. /services/data/vXX.X/sobjects/sObject/describe/
    • Completely describes the individual metadata at all levels for the specified object. For example, this can be used to retrieve the fields, URLs, and child relationships for the Account object.
    • See sObject Describe.
  4. /services/data/vXX.X/sobjects/sObject/id/
    • Accesses records based on the specified object ID. Retrieves, updates, or deletes records. This resource can also be used to 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.

Enabling the Beta

To enable this beta, follow these steps. (You must have either the “Modify All Data” or the “Customize Application” permission.)

  1. From Setup, enter 'User Interface' in the Quick Find box and access the 'User Interface' page.
  2. On the User Interface page, select Enable Salesforce Platform REST API, OpenAPI 3.0 Spec Generation (Beta).

    Selecting this item asserts that you accept the Beta Services Terms provided at the Agreements and Terms.

    Note

  3. Click Save.

Generating a Specification for Your Org

After the Beta has been enabled, generate the specification by following these steps. (You must have either the “Modify All Data” or the “Customize Application” permission.)

  1. Authenticate as usual when using the Lightning Platform REST API.

  2. Send a GET request to

    The API version 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.

  3. Assuming the request can be parsed without errors, the server responds with JSON that contains a URI where the specification can be obtained. For example:

    The last part of this URI (NTByUjAwMDAwMDAwMDBh in this example) is referred to as the locator ID for the specification.

  4. Send a GET request to the same URI with the locator ID appended. For example:

    1. If the server hasn’t finished preparing the specification yet, it responds with a 202 (Accepted) status code and a status message of “Not Started” or “In Progress”. For example:

    2. If the server has finished, it responds with a 200 (OK) status and returns the specification in the response body. For example:

After the specification has been generated, you can retrieve the specification again (using the same locator ID) for 48 hours. After 48 hours, using that locator ID results in a 404 (Not Found) error.

A new specification can only be generated every 6 hours per user. If you call /async/specifications/oas3 again within 6 hours of the last generation, the API returns the same locator ID.

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 specification aligns with your OpenAPI use cases.