Getting Started

Lets start by creating an account here. Already have an account? Login here.

Sign up

1. Please enter your first name, last name followed by your email and check the "I am not robot" box before clicking the submit button.

2.. You should see GREEN checked icon for both of the service account creation. Now click on the proceed button.

3. You should get status ok for both of the service account creation. Click on close and check your email to get the temporary password.

Login

1. Check your email to get the temporary password. Copy the password to clipboard.

2. Now go to service exchange site page and click on sign in button.

3. Please enter your email and the temporary password. To change the temporary password click on change password. Skip step 3 to 6 if you wish to keep using the temporary password.

4. Please enter your email to receive the link to reset your password.

5. Check your email for the reset password link.

6. Click on the Reset Password button in the reset password link to change your temporary password.

7. Please enter your new password and click on submit button.

Service Exchange Platform

How to Subscribe to API

You have to subscribe to an published API before using it in your applications. Subscription to an API enables you to receive access tokens and be authenticated to invoke the API.

TM Service Exchange platform offers varierty of API stores from several providers. You can browse through the API store and view the API available. The list of API store available can be found at https://store.oip.tm.com.my/stores/.

In this tutorial we will be using the APIs in the service hub store. Visit https://store.oip.tm.com.my/stores/ and click on SERVICE HUB store.

The SERVICE HUB will contain APIs from 3rd party service providers.

As an example we will demonstrate the use of Weather-API using service exchange platform. All the API will be used in the same way as desribed here.

1. Sign in to the TM API Store https://store.oip.tm.com.my/apimanager/store/site/pages/login.jag and go to SERVICE HUB. In the search bar search for weather to get weather API.

2. click on an API (e.g., Weather-API 1.0) to open it. You will see a page mentioning details of weather API as show below:

3. Note the subscription options for the REST API.

4. Click the Applications menu and click Add Application to create a new application.

5. Enter the name as TestApp and select the per token quota as 50PerMin for the application and click Add.

6. Click APIs and click on the Weather-API to view the API's subscription options.

7. Select the application that you just created, a tier, and click Subscribe.

8. Click the View Subscriptions button when prompted. The Subscriptions tab will open.

9. Click the Production Keys tab and click Generate Keys to create an application access token. You can use this token to invoke all APIs that you subscribe to using the same application.

10. Install cURL if it is not there in your environment.

11. Open the command line and execute the cURL command on the right side of the screen:

curl -k -H "Authorization: Bearer <access_token>" -v '<api_url><payload>'

Be sure to replace the placeholders as follows:

• access token: Give the test token generated in step 9. Click Applications, click on the respective application, which in this case is TestApp, click Production Key, and click on show keys.

Then copy the Access token

• api_url: Click on the respective API, which in this case is "Weather-API". When the API's Overview tab appears in the API Store copy the production URL and append the payload to it. For example, https://api.oip.tm.com.my/info/1.0/data/2.5/weather?q=london&appid=b6907d289e10d714a6e88b30761fae22

Troubleshooting

If you get an error that states "Invalid Credentials", carryout the following steps to overcome the error.

• Optionally, you can update the token validity period in the Access token validity period text box so that the access token will be valid for a longer period, or you can even set a minus value (e.g., -1) so that the token never expires.
• Re-generate the access token. Click Applications, click on the respective application (i.e., TestApp), click Production Key, and click Re-generate. Thereafter, use the new access token when running the cURL commands.

You have subscribed to an API and invoked it. To unsubscribe from an API, click the Applications menu and click View next to the application used for the subscription. Go to the Subscriptions tab, locate the API, and click the Unsubscribe link associated with it.

How to Use Integrated API Console

Swagger is a 100% open source, standard, language-agnostic specification and a complete framework for describing, producing, consuming, and visualizing RESTful APIs, without the need of a proxy or third-party services. Swagger allows consumers to understand the capabilities of a remote service without accessing its source code and interacts with the service with a minimal amount of implementation logic. Swagger helps describe a service in the same way that interfaces describe lower-level programming code.

The Swagger UI is a dependency-free collection of HTML, JavaScript, and CSS that dynamically generate documentation from a Swagger-compliant API. Swagger-compliant APIs give you interactive documentation, client SDK generation and more discoverability. The Swagger UI has JSON code and its UI facilitates easier code indentation, keyword highlighting, and shows syntax errors on the fly. You can add resource parameters, summaries, and descriptions to your APIs using the Swagger UI.

The examples here use the Weather-API REST API, which is created in the section Create and Publish an API.

1. Sign in to the TM API Store and click an API (e.g., Weather-API). https://store.oip.tm.com.my/apimanager/store/apis/

2. Subscribe to the API (e.g., Weather-API) using the default application and an available tier.

3. Click on the Applications menu and open the default application which you used to subscribe to the API. Click the Production Keys tab and click Generate keys to generate a production key.

4. Click on the APIs menu and then click on the API that you want to invoke. When the API opens, go to its API Console tab.

5. Expand the GET method by clicking on it, provide the required parameters and click Try it Out. For example,

q	London,uk
appid	b6907d289e10d714a6e88b30761fae22
Authorization	The API console is automatically populated by the access token that you generated in step 3 after subscribing to the API.The token is prefixed by the string "Bearer" as per the OAuth bearer token profile. OAuth security is enforced on all published APIs. If the application key is invalid, you get a 401 Unauthorized response in return.
Base URL	This appears at the bottom of the console. Using the base URL and the parameters, the system creates the API URL in the form https://api.oip.tm.com.my/{context}/version/resource/{backend_service}

Where

• {resource} - The resource of the URL, if any.
• {backend_service} - This refers to the backend service requirements included as parameters, if any.
• For example, in the following API URL, /info is the context, 1.0.0 is the version, and /data/2.5/weather is the resource: https://api.oip.tm.com.my/info/1.0.0/data/2.5/weather?q=london&appid=b6907d289e10d714a6e88b30761fae22

Note the response for the API invocation. It will return the weather in London.

How to interact with IoT devices via Service Creation Platform

1. Go to https://store.oip.tm.com.my/stores/ and click on the Telekom Malaysia Research and Development store. You will see a page like shown below in the Image.

Select the service creation platform API.

2. Subscribe to the API by clicking the subscribe button. Please note that you have to select the application first from the dropdown menu and selecting the tier also.

3 To see the list of application that have been created under your account click on the application tab on the left.

4. To see what APIs the particular application has been used to subscribe click on the view button in the list of application shown. You will see the list APIS that has been subscribed using particular application.

5. Click the Production Keys tab and click Generate Keys to create an application access token. You can use this token to invoke all APIs that you subscribe to using the same application.

6. Click on the API console tab after you have subscribed to the API and generated the access token. This will list down all the API that you can use.

7. To use the first API which provides you the token to use service creation platform you need to provide the username and password in JSON format as shown.

{
"username" : "demo@mmu.edu.my"
"password" : "Demo_123"
}

Enter the above information in the payload box.

8. After entering the JSON information in the payload box click the try it out button. You should get the access token in the response body.

9. The next API is used to get timeseries data keys. You need to enter three information entity type, entityid and X-Authorization as shown. X-Authorization is the access token you received in the previous API.

X-Authorization : Bearer <Your access token>

entityType can be:  TENANT, CUSTOMER, USER, RULE, PLUGIN, DASHBOARD, ASSET, DEVICE, ALARM

entityID is unique id of the device that you will get from service creation platform dashboard.

10. Enter all the information identified in the previous step as shown in the figure.

11. Click on try it out button and you will get all the keys of the timeseries data associated with particular entity.

12. The following API provides the data based on the keys that are obtained in the previous step. Enter all the information in the box plus the keys you want the data. For example we want data on Temperature and humidity so will enter in the key box Temperature,humidity as shown in figure below.

13. On clicking try it out button we will get the data of the keys we have entered.

14. The following API gives the attributes keys associated with particular device. Enter all the information in the box as shown.

15. You will get the keys associated with the device attributes when you hit the try it out button.

16. After you have the attribute key you can get the attribute value by choosing the key just as you did for time series data. For example we want attribute data identified by key named "model". So we enter the "model" in the key box.

17. When you hit try it out you will receive the data.

18. Issue a control command via Remote Procedure Call (RPC) to your device. Your device is required to subscribe to the topic "v1/devices/me/rpc/request/+" to receive the command.

19. Response code should be 200 indicating that the command is successfully sent to the Service Creation Platform. Your device should receive the command then. !

Data Visualization

If you are interested to design your own frontend (UI) and backend (BE) integrating with our SEP via API calls, we have make our sample codes available here.

• Dash by Plotly crunching IoT device data
• Weather Forecast UI and BE
• Oxford Dictionary UI and BE

API Service Provider

How to publish an API

1. Go to the publisher page and login as the administrator. Click here

2. Click on the ADD NEW API button to add new API.

3. Click on Design a New REST API to expand the window and click on Start Creating button.

4. Fill up the general details and add URL Pattern (i.e: /TestPattern) in the API Definition. Check the GET checkbox (assuming the backend service offering HTTP GET method) and then click on Add button.

5. Click on the created URL Pattern to add parameters.

6. Enter parameter name as PhoneNumber and click on add parameter button.

7. Once the parameter is added, click on Description, Paramater Type and Data Type fields to configure the values accordingly.

8. Click on the Required field and change the value to True.

9. Click on Produces field and type in application/xml. Then, click on Consumes field and type in application/json.

10. Click on next button to proceed to Implement tab.

11. Click on Managed API and add the following URL "http://ws.cdyne.com/phoneverify/phoneverify.asmx" to Production Endpoint and Sandbox Endpoint. Save and click Next to proceed to the Manage tab.

12. Fill up the configurations and throttling settings as displayed in the picture. Click Save & Publish.

13. You should see the following notifications upon successful publish of your API.

Dynamic Endpoint

1. If you happen to have multiple backend endpoints in your system and would like to locate it in one single APIs service, please select Dynamic Endpoint in Endpoint Type of Implement tab.

2. Click Check to select a message mediation policy to be executed in the message flow to enable message mediation.

3. Please modify the below XML script, i.e. Path to Resouce 1 mapped to the resource path that you have configured in Design tab, 1st URL mapped to your endpoint URL and resource to endpoint URL's resource. This permits constructing the service_ep property dynamically and assigned the value of this property to the To header.

<?xml version="1.0" encoding="UTF-8"?>
<sequence name="default-endpoint-seq" trace="disable" xmlns="http://ws.apache.org/ns/synapse">
    <switch source="get-property('To')">
        <case regex=".*/<Path to Resource 1>">
            <property name="service_ep" value="http://<1st URL>/<resource>"/>
        </case>
        <case regex=".*/<Path to Resource 2>">
            <property name="service_ep" value="http://<2nd URL>/<resource>"/>
        </case>
        <default>
            <property name="service_ep" value="http://<3rd URL>/<resource>"/>
        </default>
    </switch>
    <header name="To" expression="get-property('service_ep')"></header>
    <property expression="get-property('service_ep')" name="ENDPOINT_ADDRESS"></property>
</sequence>

4. Select this XML script and click Upload In Flow.

5. Make sure that In Flow has been set to default-endpoint-seq as API specific mediation policies.

6. Click Save & Publish and you are done.

Dynamic Endpoint with Sandbox and Production Endpoints

1. If you would like to have dynamic endpoints supporting traffic reroute to your sandbox and production endpoints separately, you can the use following XML script.

<?xml version="1.0" encoding="UTF-8"?>
<sequence name="default-endpoint-seq" trace="disable" xmlns="http://ws.apache.org/ns/synapse">
    <filter source="$ctx:AM_KEY_TYPE" regex="PRODUCTION">
        <then>
            <switch source="get-property('To')">
                <case regex=".*/<Path to Resource 1>">
                    <property name="service_ep" value="http://<1st Production URL>/<resource>"/>
                </case>
                <case regex=".*/<Path to Resource 2>">
                    <property name="service_ep" value="http://<2nd Production URL>/<resource>"/>
                </case>
                <default>
                    <property name="service_ep" value="http://<3rd Production URL>/<resource>"/>
                </default>
             </switch>
             <header name="To" expression="get-property('service_ep')"></header>
             <property expression="get-property('service_ep')" name="ENDPOINT_ADDRESS"></property>
        </then>
        <else>
            <switch source="get-property('To')">
                <case regex=".*/<Path to Resource 1>">
                    <property name="service_ep" value="http://<1st Sandbox URL>/<resource>"/>
                </case>
                <case regex=".*/<Path to Resource 2>">
                    <property name="service_ep" value="http://<2nd Sandbox URL>/<resource>"/>
                </case>
                <default>
                    <property name="service_ep" value="http://<3rd Sandbox URL>/<resource>"/>
                </default>
             </switch>
             <header name="To" expression="get-property('service_ep')"></header>
             <property expression="get-property('service_ep')" name="ENDPOINT_ADDRESS"></property>
        </else>
    </filter>
</sequence>

2. Apply the similar steps as previous Dynamic Endpoint section.

Contact Us

If you are facing any technical issue while using the OIP platform, please contact us at ''oip@tmrnd.com.my''