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/.

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.

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.

You can set a token validity period in the Access token validity period text box. By default, it is set to one hour. If you set a minus value (e.g., -1), the token never expires.

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.

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.

API Service Provider

How to publish an API

Your signup account only allows you to subscribe to API store. If you need a publisher role, please contact us.

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.

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

Your signup account only allows you to subscribe to API store. If you need a publisher role, please contact us.

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.

Please note that if user subscribed to your API and accessing via sandbox access token, it is not counted as API consumption for your published API. So make sure that your sandbox API is just an environment that testers can use to mimic the characteristics of your production environment and not your production environment itself.

Contact Us

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