Define an API Specification for an External Service

Learning Objectives

After completing this unit, you’ll be able to:

  • Describe the purpose of the API spec.
  • Explain the elements of a supported External Services schema definition.
  • Name three issues that can cause your API spec to fail.

Why Do You Need a Schema Definition?

Whether or not you’re the one who ends up creating an API spec for your External Services registration, it’s helpful to understand its purpose and how it’s used. Already familiar with creating an API spec from a REST-based API? Go ahead and skip to the next section And... What Makes a For a Valid and Supported Schema?

Imagine we have a REST-based bank API. We need a common, standardized format to describe the structure of our bank’s REST-based API. Enter the API spec. Salesforce uses the commonly adopted OpenAPI specification for the description format. 

Your API spec contains a schema definition that describes what types of inputs and outputs you can include in the calls, or requests, that your org makes to the external web service. For example, your calls might include an ID as numerical input or a name as text output.

Your API spec also contains the endpoint information and authentication parameters for the REST-based API web services that you can access. (Remember that the endpoint exposes the web services resources that External Services interacts with.) For example, this API spec from a fictional bank web service includes methods for adding and deleting bank accounts. https://th-external-services.herokuapp.com/accounts/schema

Note
In a real world application, following security best practices, you would include an authentication step before accessing a bank’s API!
Since our fictional bank's API spec is human-readable, structured data, let’s look at it together.
Here are the basic account operations of our schema:

Operations for path: /accounts/{accountName}
Description
GET
Retrieves an account
POST
Adds an account
PUT
Updates an account
DELETE
Deletes an account

Here’s a partial code snippet from the API spec's schema that contains information about a GET method. If you don’t know, a GET method simply retrieves resource information from a web service. This particular GET method retrieves (“gets”) information about an account using the resource path, in this case /accounts/{accountName}, where {accountName} is a specified account. If you look under “parameters”, you can see "name":"accountName". This parameter must match the account name that you specify and is required ("required":true). It should also take the form of a string.

"paths": {
     "/accounts/{accountName}": {
       "get": {
         "operationId": "getAccount",
         "summary": "Retrieves an account",
         "description": "Retrieves the account with specific name",
         "consumes": ["text/plain"],
         "produces": ["application/json"],
         "parameters": [{
           "name": "accountName",
           "in": "path",
           "required": true,
           "type": "string",
           "description": "Name of the account"
        }],
         "responses": {
           "200": {
             "description": "The response when system finds an account with given name",
             "schema": {
               "$ref": "#/definitions/accountDetails"
            }
           },
           "400": {
             "description": "Error response if the account name parameter is
            less than minimum characters",
             "schema": {
               "$ref": "#/definitions/errorModel"
            }
           },
           "404": {
             "description": "Error response if the account is not supported by service or account is not found",
             "schema": {
               "$ref": "#/definitions/errorModel"
            }

This is just one part of a much larger schema definition. But you can see that while it’s designed for consumption by External Services, it’s also human-readable. It’s also formatted in a logical way that allows External Services to process the operations so that it can surface them as invocable actions in tools like Flow Builder or Einstein Bots. These actions are what we will later use as inputs and outputs in a flow.

The next steps show you how to declaratively register your API spec. But first, let’s cover the elements that make up a valid and supported schema definition - the detailed descriptions of each separate API capability contained within the API spec document.

And...What Makes for a Valid and Supported Schema?

So now we know what an API spec is all about. But what do we mean by a valid and supported schema

There are schema validation requirements that the OpenAPI specification defines, and there are specific External Services schema requirements as well. External Services can properly support your schema and call your web service when both of these requirements are met.  

A Primer on Schema Validation

Although a schema is human-readable, it must also be machine-readable. It needs to follow a logical structure so that External Services can easily consume it. An incorrectly structured schema means that the external web service can’t communicate (returns error and exception messages) and, ultimately, External Services can’t ingest it. Meeting structural, logical, and syntax restrictions is a necessary first-pass of schema validation. The OpenAPI specification defines these general rules and takes the guesswork out of calling an external web service.

Supported External Services Schema 

In addition to general OpenAPI guidelines for schema validation, there are also schema limitations that are specific to External Services. You’ll want to review these requirements before you register your API spec with External Services. A supported schema in External Services means that both your schema is valid according to the OpenAPI specification, and it also adheres to the specific External Service requirements. For example, an API spec might fail the registration process if it exceeds the file size limitation, or exceeds the limit on total number of objects or actions.

For a list of key requirements for creating an External Services supported schema, see Salesforce Help: Enhanced External Services Considerations

So let’s delve into the nitty gritty of what a supported schema looks like. This next step sets everything up. It’s a basic, yet critical piece to get right so that tools like Flow Builder or Einstein Bots can successfully call external web services.

Note
If you use the open-source framework OpenAPI, you can use the Swagger Editor tool to validate that your schema complies with the OpenAPI specification. If you want to take a short detour, go ahead and copy the schema from https://th-external-services.herokuapp.com/accounts/schema into the Swagger Editor. You shouldn’t get any errors.

We covered some concepts about API specs and also some requirements. Want to dig in and get your hands dirty with External Services? Of course you do! We do just that in the next unit. Before moving on, though, let’s review the first two steps we discussed in the first unit.

  1. An external web services provider makes its REST-based API specification available: We've received the API spec from our fictional bank at https://th-external-services.herokuapp.com/accounts/schema.
  2. Based on the OpenAPI specification, the web service provider (like in our bank service example), a developer (or maybe even you) creates a JSON-based API spec that describes the API: While we didn’t create this spec ourselves, we reviewed the elements of the schema and the requirements to make sure it’s supported. When you work with external web services, you or your developer can create the API spec that fits your use case.

Resources

Keep learning for
free!
Sign up for an account to continue.
What’s in it for you?
  • Get personalized recommendations for your career goals
  • Practice your skills with hands-on challenges and quizzes
  • Track and share your progress with employers
  • Connect to mentorship and career opportunities