The Cumulocity platform offers a rich set of APIs to manage devices, measurements and many other functions. With the help of "API Portal" and "API Gateway" those APIs can be safely exposed and managed for a full-featured API-based solution.
To integrate the Cumulocity API into "API Portal" and "API Gateway" an API definition file is needed. It can be found on the Software AG GitHub repository cumulocity-swagger-openapi.
Before importing the definition file it is important to replace the {host} parameter with the Cumulocity URL that will be used to access the APIs. If a public cloud tenant is used, the URL would look like "YourTenantName.eu-latest.cumulocity.com" or "YourTenantName.us.cumulocity.com"
Importing the Cumulocity API into API Portal
There are 3 ways to import the definition file in API Portal
- Copy-paste
- Upload a file
- Provide URL
To use options 1 or 2, copy locally either the definition file "Cumulocity Swagger OpenAPI v2.0.json" or its contents from the GitHub repository and adjust the {hosts} parameter.
For option 3 you need to fork the GitHub repository, modify the {hosts} parameter and then provide the URL to the file in your repository.
Once the definition file is ready, log in to API Portal, click on the menu in the top right corner, select "Manage APIs" and then click on "ImportAPI" and select one of the three import methods described above.
When the API is successfully imported, you can try it by clicking on it and selecting "Try API" at the bottom of the page. Select for example the rest resource "alarm/alarms" and click on "GET". Now go to "Authorization", select "Basic" and enter your Cumulocity username and password. Click "Update" and then "Send". You should receive a response like this:
Importing the Cumulocity API into API Gateway
There are 3 ways to import the definition file in API Gateway
- Import API from URL
- Import API from File
- Create API from Scratch
For option 1 you need to fork the GitHub repository, modify the {hosts} parameter and then provide the URL to the file in your repository.
To use option 2, copy the definition file "Cumulocity Swagger OpenAPI v2.0.json" from the GitHub repository, open it with a text editor (i.e. Notepad or Notepad ++) and adjust the {hosts} parameter.
Once the definition file is ready, log in to API Gateway, click on "APIs" on the top left and then select "Create API" on the top right. Now select Import API from URL or File, select Type "Swagger" and import your Cumulocity APIs.
As the API is successfully loaded you will be taken to the API Details page. Click "Activate".
To test the API copy the "Gateway Endpoint" URL, paste it in a browser window and add to the URL ""/alarm/alarms" and load it. You will be asked for your API Gateway username and password. A successful response would look like this:
Related webMethods DevBytes video:
Integrating Cumulocity IoT with webMethods API