đź“Ł Attention Salesforce Certified Trailblazers! Link your Trailhead and Webassessor accounts and maintain your credentials by December 14th. Learn more.
close
trailhead

Define a Schema for an External Service

Learning Objectives

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

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

What’s a Schema Good For?

Whether or not you’re the one who ends up defining a schema for your External Services registration, it’s helpful to understand what it’s good for and how it’s used. If you’re already familiar with defining a schema from a REST-based API, feel free to skip to the next section, And... What’s a Good Schema?

Let’s start with the schema specification—the REST-based API that comes from an external service provider, such as a bank. We mentioned in the previous unit that you can think of the specification as a contract: It contains what types of inputs and outputs you can include in the calls, or requests, that your org makes to the external service. For example, your calls might include ID as numerical input or name as text output.

It 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 endpoint from a fictional bank includes methods for adding and deleting accounts. https://th-external-services.herokuapp.com/accounts/schema
Note

Note

Typically you’d perform an authentication step before accessing a bank’s API!

On the other hand, the schema definition is human-readable, structured data. Let’s look at this schema together. This snippet from the schema definition contains information about a GET method. If you don’t know, a GET method simply retrieves resource information from a 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"
                  }
               },
               ....
There’s a lot more to the schema, of course. But you can see that while it’s designed for consumption by External Services, it’s certainly human-readable. It’s just that it’s formatted in a logical way that allows External Services to process the data so that it can generate Apex actions. These Apex actions are what we later use as inputs and outputs in a flow.

The next steps are to use declarative tools to register your service. But first, let’s cover the elements that make up a good schema definition.

And...What’s a Good Schema?

OK. We now know what a schema, or more precisely, a schema definition, is good for. But what makes a schema definition good? And, can they really be bad?

Well, yes, a schema can be bad. Although a schema is human-readable, it also requires a logical structure that allows External Services to consume it. If a schema isn’t structured correctly, the external service returns error and exception messages. So let’s get the skinny on what a good schema looks like to ensure that our flow can successfully consume our External Services–generated Apex classes. When creating a schema, we must ensure that:
  • Schemas include up to 100,000 characters but no more.
  • Reserved names are not used.
  • Only supported Methods are included.
  • Properties include values.
  • Parameters have names.
  • Response code output doesn’t contain complex objects.
Oh, and we use Interagent hyper-schema using JSON or Swagger Open API 2.0.
Tip

Tip

If you use Swagger, you can use the Swagger Editor to validate that your schema complies with the Swagger 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 receive any errors.

We covered some concepts about schemas 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 look at the first two steps we discussed in the first unit.
  1. An external services provider such, as a bank, shares its REST-based API schema specification: We received this information from our fictional bank.
  2. Based on the specification, a developer (or maybe even you) creates a schema definition that describes the API: While we didn’t create this schema ourselves, we reviewed the elements of a schema and the requirements for a good one. When you work with external services, you or your developer can define the schema you need for your use case.
retargeting