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 Scribe REST connector connection.
•JSON Authentication method identified
•Custom Headers (optional)
OpenAPI Spec 2.0:
Scribe 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 Scribe 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, Scribe 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 Scribe 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==
•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 into Scribe.
Example of Scribe’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 to Scribe. 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 Scribe. If you have any questions about your Scribe 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 Scribe map!
•Common integration patterns with REST