REST Connector Series: Connector Configuration
In my last post, we looked at the OpenAPI spec, productivity tools I use, and hopefully gave you enough high-level content to start comfortably working on your first spec. In this post, we’ll take a working OpenAPI spec and configure your REST connector connection in the Connect capability of TIBCO Cloud Integration.
- OpenAPI Spec/Swagger
- Version 2.0
- JSON Authentication method identified
- Custom Headers (optional)
OpenAPI Spec 2.0:
TIBCO Cloud Integration is looking for an OpenAPI/Swagger specification, version 2.0, in JSON.
If your spec has any errors or warnings in the Swagger Editor, you’ll probably have issues in TIBCO Cloud Integration too. I’ve seen many vendors publish their specifications with errors or it doesn’t meet the framework requirements; try to resolve those if possible, otherwise, TIBCO Cloud Integration may not support that specification either.
At the time of writing this, there is no support extensions or customizations (for example: https://swagger.io/docs/specification/openapi-extensions/).
There are a few types of authentication the OpenAPI spec allows. You’ll define authentication at the Connection level. Putting your authentication (even if it’s Basic Auth Headers) means you won’t need to map credentials within a solution/map.
The Scribe REST connector will support these:
None: no authentication.
Basic: – Performs Basic Authentication on a username and password. For example, to authorize as demo / p@55w0rd the client would send a Header: Authorization: Basic ZGVtbzpwQDU1dzByZA==
- OAuth 2.0
User Token: – Adds a Key and Value to either a Header or Query Parameter.
There are a few different Flows/Grant Types, and depending on the specification or documentation you’re reading, they may be named differently:
|OAS 2.0||OAS 3.0/Scribe|
|Password||Resource owner password credentials|
|Access Code||Authorization Code|
At the time of writing this, the REST Connector supports Client Credentials (previously called application in OpenAPI 2.0)
Example of Swagger UI’s OAuth 2.0 Client Credentials/Application flow
Note that the REST connector is not reading the Security Definitions in the spec, you’ll just need to pull values from there and paste them in.
Example of TIBCO Cloud Integration's OAuth 2 Client Credentials/Application flow
You can also add Headers at the connection-level if you don’t want to save the time from adding them in each of your operations. Some API’s support “test” or “debug” modes using custom headers; this will allow you to have a “REST Connector-Debug” connection.
If you have a valid JSON specification loaded and have chosen an Authentication type, you can test your connection to ensure there are no issues converting from OAS. This will not test your credentials, though.
If you care about testing the credentials you input, there is a Test URI parameter is on the Specification Tab. Here’s where you can put a URI to perform a GET to test an API call with the given credentials(such as GET ../currentUser). Most REST API’s don’t have a login method, so you can put any call in here that you’d expect would return a 200.
Hopefully, you have a good understanding of getting your OpenAPI spec into TIBCO Cloud Integration. If you have any questions about your connection, feel free to post on our Community with any supporting information. Next, I’m going to share some of the common integration patterns inside your map!
•Common integration patterns with REST
First published June 04, 2018
About the Author
Nate Keefe is a Product Manager at TIBCO Software.