Calling APIs

APIs that are exposed through the API Platform console can be called from recipes in accounts other than one owning the recipe, as well as from third-party tools, programs, and scripts. The API manager must provide the Auth Token or JWT token value to the client to call any endpoints in an API Collection.

With raw content support, the API platform allow clients to send text based (for example, XML/SOAP) requests and receive custom responses from the API recipes exposed as endpoints. This extends the security benefits of Workato's recipes to API calls from other systems. Learn more.

---

Authorization Headers

If the Access Profile specifies the Auth Token method of authentication, then the Auth Token value must be passed by the client as the value of the API-Token header. If the authorization method is OAuth2.0 or JSON Web Token, then the value of the encoded and signed token is passed in the Authorization header, using the Bearer scheme.

Header	Authentication method	cURL Example
API-Token	Auth token	-H 'API-TOKEN: 24ea2bf52b42b7345b9'
Authorization	OAuth 2.0 & JWT token	-H 'Authorization: Bearer 12cb1a7d5233'

---

Calling An API Endpoint From A Recipe

An API endpoint that belongs to another user can be called from a recipe using the HTTP Connector. Select the Send request action of the Connector. The following screen shows a typical configuration for this action (in this case a POST request):

API Client Request

Make sure that the type of request (POST, PUT, GET) matches the API that you are calling. Any required fields need to be specified in the body (for POST and PUT) or as query parameters in the URL (for GET).

Also, note that an API-Token request header has been added. Its value should be set to the token that the API owner has supplied to you. (This assumes the Auth Token method of authentication).

WARNING

Do not hard-code API tokens into input fields. Check out the recommended security best practices for guidance.

---

Response Codes

Using the recipe test feature, you can run the recipe a single time and have it generate a call to the API. If successful, the API will return a 200 status and the recipe execution will continue to completion. There are several possible errors that can occur. These are the common ones:

Error code	Error message	Details
401 Unauthorized	"access to this API has been disallowed"	There is a problem with the API token, path, or a violation of the access policy.
404 Not found		The URL is incorrect in the request configuration, the recipe you are calling is not running, or the API collection or your client configuration is set to Disabled.
422 Processing error		There is an issue with the API recipe and the job failed. It could be due to a mismatch between the request syntax and the expected syntax written in the recipe.
429 Too many requests	"concurrency limit exceeded" or "rate/quota limit exceeded"	The request exceeded either the concurrency limit or the rate/quote limit set by the access policy.
500 Server error		The request parameters were missing or invalid for the API.
504 Gateway timeout	"recipe execution takes too long"	The job took too long to respond. The limit for API jobs is 30 seconds.

In addition to the standard error codes in the preceding table, you may see custom response codes as defined in the API recipe.

---

Calling The API From Other Clients

Clients can access the Open API description for the service by performing a GET request on the API URL and adding /swagger to the path. This URL should also have the API token as a query parameter.

For example, if the API URL is https://workato.com/doc/service/sales-api-v1, the Open API description is available at a URL similar to the following:

https://workato.com/doc/service/sales-api-v1/swagger?token=e6883d64843aaed62d48bcdf3cf4ebbf

The Open API description can be used by tools such as the Swagger UI (opens new window) to make requests. For programmers, it is possible to generate API client code using Swagger Codegen (opens new window).

Any other standard HTTP request tool, such as the command-line tool cURL (opens new window) or the popular open-source tool Postman (opens new window), can be used to make requests.