Build a new connector in SAP Cloud Platform Open Connectors
Since the beginning of Q4/2018, I’ve been following some interesting posts about one of the latest SAP Cloud Platform services called Open Connectors. Divya Mary has been covering this subject during the last months and provided interesting ideas of how you can use Open Connectors in different development scenarios. Check some of her blog posts below:
SAP Cloud Platform Open Connectors is Live
Blog Series: Simplify Integration with third-party application with SAP Cloud Platform Open Connectors
To understand the value provided by this service let’s have a look in one of the statements available in the Open Connectors Official Page.
SAP Cloud Platform Open Connectors provides pre-built and feature-rich connectors to simplify the connectivity and seamless integration with over 150 non-SAP cloud applications. Customers benefit from connectivity to third-party APIs via harmonized RESTful APIs and can develop and map canonical data models to extend pre-built connectors. Furthermore customers can easily build API compositions across the different connectors.
Open Connectors is definitely an excellent option to simplify and accelerate the integration between SAP and third-party solutions, the list of pre-built connectors available is extensive: Slack, LinkedIn, Twitter, Google Drive, Facebook, Paypal, etc. If you want to check the full list of available connectors access the link below:
Full List of Available Connectors | SAP Cloud Platform Open Connectors
After reading about the features and benefits offered I had a simple question afflicting my mind, what if my API is not available in the list of pre-built connectors? Is there any way to take advantage of the features provided by Open Connectors?
Curious to find the answer I accessed my trial account and started to play with the options available. With +150 connectors is quite difficult to find an interesting scenario that is not ready for consumption, for this reason I selected a unconventional Web API and decided to integrate Spotify with an UI5 application.
Note: Spotify API will be used as example in this article but the real intent is to explain how you can make use of Open Connectors even in the case your API is not available in list of pre-built connectors. Hope you abstract the concepts and make use of this information in future challenges.
Building a new connector
If we search for Spotify in the Open Connectors list we can’t find any connector available, only the option to Build a new connector.
Select this option and click on Import in the next screen.
Currently, there are four options available for import:
- OData V4
Connector is the pattern delivered by Open Connectors itself, you can export custom connectors and re-import in different tenants, Swagger is an open-source software framework that helps developers design, build, document, and consume RESTful Web services, SOAP is the message protocol used by web services to exchange data in XML and the OData V4 is the open data protocol, largely adopted by SAP nowadays and it provides a set of best practices for building and consuming RESTful APIs with extra features like metadata and querying options embedded in the URL.
Now that we are aware about the options available let’s explore the Spotify for Developers page to understand the best way to access the data. Checking the documentation we can find the following options for consumption:
Let’s have a closer look in the Web API documentation.
Spotify Web API is based on simple REST principles, the Spotify Web API endpoints return JSON metadata about music, artists, albums, and tracks, directly from the Spotify Data Catalogue, perfect integration scenario for an UI5 application!
In the Developer Portal is possible to find the definition of their Web API in their GitHub account, you can access through the link GitHub Spotify Web API.
There is only an issue at this moment, the current definition is based on RAML (RESTful API Modeling Language) and we need to find a way to convert this specification to Swagger before we build our connector.
There are different ways to solve this issue but I found the best way with APIMATIC. This service provides an API Transformer that solves this issue quickly. Register to the service and press the button Convert Now.
Insert the URL of the api.raml file available in the GitHub project and press Convert Now. The system executes the scripts and in a few seconds you receive the download of a new Swagger Web API definition.
- Spotify Web API RAML: https://github.com/spotify/web-api/blob/master/specifications/raml/api.raml
Let’s get back to the Open Connectors and continue from the previous steps.
Import the Swagger file and press CONTINUE IMPORT.
Select all the resources, provide an Element Key and click on Import to conclude the assistant.
The connectors are generated based on the specification in the Swagger file and you can see the following screen with the configuration of the new connector.
Note: The RAML specification stores the version of the API in a parameter but during the conversion and upload of the Swagger there is a small bug that needs to be fixed in the connector properties, adapt the Base URL removing the DefaultParameterValue and replacing by v1.
- Expected Base URL: https://api.spotify.com/v1
Move to the Information tab and update the documentation and logo of the connector. You can download their logo from the Branding Guidelines page.
Now that our specification is successfully loaded we just need to adjust the settings for Authentication and execute a connection test.
To understand the authentication methods available let’s explore one more time the Spotify developer documentation, we can find all the relevant information we need in the Authorization Guide.
As mentioned in the official guide, there are two ways to be authenticated by Spotify API:
- App Authorization
- User Authorization
Before selecting an option we need first to Register an Application in the Developer Dashboard. Open the dashboard and select the option Create an App.
Define a Name, Description and Type of application.
In the second screen select a Non-commercial app, move to the third screen, confirm the agreements and Submit. The application is now created and you have your Client ID and Client Secret ready for consumption.
Press the button Edit Settings…
… and include the Redirect URL for OAuth authentication used by SAP Cloud Platform in the White-list: https://auth.cloudelements.io/oauth.
With the app configured it is time to evaluate the documentation and discover how we can authenticate the API. In the official documentation we can see three different Authorization Flows.
For the sake of this exercise we will authenticate the application in the most complex scenario using the Authorization Code flow. With this option we are able to access user resources and refresh the token automatically after the expiration time (usually 1 hour).
Let’s check all the steps involved in the Authorization Code flow:
Notice that the application (openconnectors) triggers the initial authentication request redirecting the user to Spotify Accounts Service where he/she needs to confirm the access, after the confirmation the application is redirected back to the OAuth redirect URL with a new access token. With this token the application can execute all the Web API operations in behalf of the user and if the token expires a new token is requested via Spotify Accounts Service without the interaction of the user.
Now it is time to get back to Open Connectors and conclude the Authentication configuration of this new connector. Select the OAuth2 authentication method and you will see several parameters provided out-of-the-box.
Note: If you never heard about OAuth2 I advise to have a look in the official documentation to understand how this authorization protocol works.
The parameters in the image above are provided automatically by Open Connectors and they are based in the OAuth2 specification. Let’s update them with the data available in the Authorization Code Flow:
- OAuth Authorization URL: https://accounts.spotify.com/authorize
- OAuth API Key: <YOUR_CLIENT_ID>
- OAuth API Secret: <YOUR_CLIENT_SECRET>
- OAuth Callback URL: https://auth.cloudelements.io/oauth
- OAuth Token URL: https://accounts.spotify.com/api/token
- OAuth Scope: user-read-private user-read-email
- OAuth Token Refresh URL: https://accounts.spotify.com/api/token
- OAuth Refresh Interval: 3600
- OAuth Token Revoke URL: https://accounts.spotify.com/api/token
- OAuth basic header: true
After you finish this configuration press Save, open the Connectors page once again and this time when you search for Spotify you will see a new connector available for consumption.
When you pass the mouse over the tile it is possible to see some extra options, click on Authenticate to start the process and create a new instance.
Select a name for the instance (in my example feliperodrigues), open the optional fields and confirm the Client ID and Client Secret. In the end press the button Create Instance.
Open Connectors redirects automatically to Spotify authorization page and requests the access confirmation.
Press the button Agree and Spotify Accounts Service will redirect to SAP Cloud Platform, after receiving the token SCP redirects back again to Open Connectors and the following success message is displayed:
In the user’s Spotify account, open the link Apps and check the openconnectors application in the list of authorized apps, through this page it is also possible to revoke the access.
Let’s get back to the Open Connectors and access the tile Test in the API docs.
In this page you can see the authenticated instance with the name of feliperodrigues and the API operations available for test.
Scroll-down and open the method GET /browse/categories, press the button Try Out.
Now the fields are available for edition with the authorization token already populated, feel free to update the filters or just press the button Execute to test the Web API for the first time.
If everything runs as expected you should receive 200 as response code and the the list of categories in JSON available in the response body. Check the results below:
With this successful test we reach the end of this article.
I am not going to cover the UI5 application development in this article because we have other posts in the community covering this subject already.
If you want to proceed with this step I advise to check Divya’s blog series mentioned in the beginning of this article (search for the part 3 and 4):
Blog Series: Simplify Integration with third-party application with SAP Cloud Platform Open Connectors
As always I hope you enjoyed the content and see you next time. 🙂
Thanks for the detailed blog!!
No worries mate, thank you for the feedback! 🙂
This is seriously cool! Great blog! Can I ask you to estimate how long this would take to do as I would love to have a crack at this blog and follow the steps you provided however need time to put away for this.
Hi Phil Cooley,
Thank you for the feedback! 🙂
In the whole process of writing the blog and reading/understanding the API specifications I spent probably couple of days.
I've faced a few issues that contributed to the overall time such as:
In a real scenario, I believe I would spend between 4 to 8 hours to study a new API documentation and configure the whole process through Open Connectors, counting also with all the possible issues in the path.
If your intent is basically just replicate the same content of this blog I believe you would spend maximum a couple of hours to assemble everything. The configuration through Open Connectors is pretty simple and straightforward, the study of the API documentation is the most complicated step in my opinion.
Hope this information helps.
Thanks for the detailed reply, will schedule this sometime soon. Thanks again!
Very nice. Thanks for sharing?
Thank you for sharing the knowledge
That’s why the SAP community is one of the best for the developers.
I also believe that our community is one of the best and this kind of feedback motivates me to contribute every time I find an interesting topic to discuss.
Thank you for your time and feedback.
Nice blog. It's not something I need to use as I am on-premise. I'm still learning so much my head is spinning. So this is probably something I'll skip for now. 🙂
It's also something I'm bookmarking as I never know when I'll need something.
Hi Michelle Crapo,
Indeed. There are so many new things going on in the SAP technical space that is pretty difficult to cover all the subjects at the same time.
If you have an opportunity to work with SAP Cloud Platform in a near future I advise you to explore the Open Connectors, it is a pretty interesting service and I believe it will receive more traction in the next months.
Thank you! Any recommendation on what to try next is an excellent thing for me. I am feeling so behind these days. Getting caught up on both the technical and the functional side of SAP at the same time is really hard. Although to be honest - not a huge change (yet) on the functional side. Just some slight changes here and there. Otherwise the GUI transactions were simply moved to the web. 😉 At least on the on-premise side of things.
Hi Michelle Crapo,
I've published a new blog that may help you through this learning journey:
SAP new technologies and the impacts in the life of consultants
Hope this content brings some ideas.
Thank you! Yes, it has given me some great ideas on what I want to learn next.
Thanks for sharing this. Tried to import an Open API 3.0 json file but it doesn't seem to work. Do you know if only 2.0 is supported?
Hi Jan Almkvist,
Thank you for the comment.
Unfortunately, I don't know if we have a limitation based on the version of the Open API / Swagger. I would suggest you to check your file with an Open API Validator in the web just to make sure the content is okay.
I tried to have a look via SAP Help Portal but didn't find anything relevant.
Let me know if you find the answer.
Thanks for your answer Felipe,
Yes the Swagger file is created with Swagger Hub so it definitely validates ok. There are some major differences between 2.0 and 3.0 and in the roadmap for API Management it's stated that 3.0 support is(was) scheduled for 1Q 2019. However, when creating APIs from within APIM it's still 2.0...
I have tried to get an answer using several channels but it's totally silent...
Thanks for your help!
Hi Jan Almkvist,
Sorry to hear about that, hope you find the answer soon.
Could you please share the information through this thread if you have any news?