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:
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.
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:
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.
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:
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.
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.
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:
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:
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):
As always I hope you enjoyed the content and see you next time. 🙂
SAP Cloud Platform Open Connectors is Live
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:
- Connector
- Swagger
- SOAP
- 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 Connecto...
As always I hope you enjoyed the content and see you next time. 🙂
- SAP Managed Tags:
19 Comments
