Skip to Content

Call SAP IoT APIs with Postman

test
0 %
Call SAP IoT APIs with Postman
Details

Call SAP IoT APIs with Postman

November 5, 2020
Created by
January 29, 2018
Use a REST client (Postman) to call SAP IoT APIs.

You will learn

  • How to Use Postman to access SAP IoT APIs.

Prerequisites

Application Router

Access to SAP IoT is usually routed through an application router as the single entry point for consumers. The application router handles the user authentication against SAP User Account and Authentication Service (UAA). In addition, the service retains the generated JWT token for the duration of the client logon session. You can define multiple application routers per tenant and you can use one of the router to access SAP IoT.

Tenant-specific Application Router

SAP IoT offers tenant-specific application router to access the different backend services such as configuration, business partner, and thing services. For example, you can access the configuration services for the tenant democompany using the application router URL https://democompany.iot-sap.cfapps.eu10.hana.ondemand.com/config-package-sap/Package/v1/Packages. You can use your system username and password when the system prompts for credentials.

The following illustrates the different parts of tenant-specific application router:

Field Description
democompany Tenant name
iot-sap Name of the application router used to access SAP IoT
cfapps.eu10 Technology and the region
Config-package-sap Name of the application you are accessing using the application router
Package/v1/Packages API endpoint you are accessing within the application

For more information about the authorization concept of the SAP IoT platform, see https://help.sap.com/viewer/fffd6ca18e374c2e80688dab5c31527f/latest/en-US | Authorization.


Step 1: Display package details

Use Postman client to retrieve the OAuth token specific for your tenant. For more information, see Accessing SAP IoT APIs Using OAuth Token. The retrieved token is used to access the API endpoints described in this tutorial.

  1. In Postman, choose the GET method.

  2. Enter the following request URL: https://config-package-sap.cfapps.eu10.hana.ondemand.com/Package/v1/Packages.

  3. In the Headers tab, enter Authorization in the Key column and enter Bearer <<your token>> in the Value column.

    bearertoken
  4. Click the Send button.
    The result set contains all packages to which the user has access authorization. It includes all packages with scope tenant and private from the same tenant to which the user has access.

    All Package response payload

    The response payload contains the following details for every package:

    Field Description
    Name Unique identifier of the package
    Description Text describing the package
    Scope Scope of the package (public and private)
    Status Status of the package (Active and Freeze)
  5. Enter the request URL https://config-package-sap.cfapps.eu10.hana.ondemand.com/Package/v1/Packages('iot.democompany.testpackage') to retrieve details of the package iot.democompany.testpackage.

  6. Click the Send button.

    Details of specific package

    The response payload contains the following details for every package:

    Field Description
    Name Unique identifier of the package
    Description Description of the configuration package for each language with the corresponding ISO language code
    Scope Scope of the package (private and tenant)
    Status Status of the package (Active and Freeze)
Log on to answer question
Step 2: Read thing type details

To create data for a thing, you must identify the property set type that is used to define property sets for a thing type. Firstly, identify thing types that belong to a package, and then read details of a thing type along with its property sets and properties.

  1. In Postman, choose the GET method.

  2. Enter the following request URL: https://config-thing-sap.cfapps.eu10.hana.ondemand.com/ThingConfiguration/v1/Packages('iot.democompany.computerdevice')/ThingTypes.

  3. Click the Send button. Thing types of the package iot.democompany.computerdevice are retrieved.


    { "d": { "results": [ { "__metadata": { "id": "https://config-thing-sap.cfapps.eu10.hana.ondemand.com:443/ThingConfiguration/v1/ThingTypes('iot.democompany.computerdevice%3Ageneric_computer')", "uri": "https://config-thing-sap.cfapps.eu10.hana.ondemand.com:443/ThingConfiguration/v1/ThingTypes('iot.democompany.computerdevice%3Ageneric_computer')", "type": "com.sap.appiot.ThingType" }, "Name": "iot.democompany.computerdevice:generic_computer", "PackageName": "iot.democompany.computerdevice", "Description": "generic use computer", "ExtendedThingType": "", "CopySource": null, "PropertySets": { "__deferred": { "uri": "https://config-thing-sap.cfapps.eu10.hana.ondemand.com:443/ThingConfiguration/v1/ThingTypes('iot.democompany.computerdevice%3Ageneric_computer')/PropertySets" } }, "Descriptions": { "__deferred": { "uri": "https://config-thing-sap.cfapps.eu10.hana.ondemand.com:443/ThingConfiguration/v1/ThingTypes('iot.democompany.computerdevice%3Ageneric_computer')/Descriptions" } }, "ThingTemplates": { "__deferred": { "uri": "https://config-thing-sap.cfapps.eu10.hana.ondemand.com:443/ThingConfiguration/v1/ThingTypes('iot.democompany.computerdevice%3Ageneric_computer')/ThingTemplates" } }, "ObjectAssociations": { "__deferred": { "uri": "https://config-thing-sap.cfapps.eu10.hana.ondemand.com:443/ThingConfiguration/v1/ThingTypes('iot.democompany.computerdevice%3Ageneric_computer')/ObjectAssociations" } } } ] } }
  4. To read details of a thing type iot.democompany.computerdevice:generic_computer along with its property sets and properties, enter the following request URL: https://config-thing-sap.cfapps.eu10.hana.ondemand.com/ThingConfiguration/v1/ThingTypes('iot.democompany.computerdevice:generic_computer')?$expand=PropertySets/Properties.

  5. Click the Send button. Thing type details along with the property sets and properties are retrieved.


    { "d": { "__metadata": { "id": "https://config-thing-sap.cfapps.eu10.hana.ondemand.com:443/ThingConfiguration/v1/ThingTypes('iot.democompany.computerdevice%3Ageneric_computer')", "uri": "https://config-thing-sap.cfapps.eu10.hana.ondemand.com:443/ThingConfiguration/v1/ThingTypes('iot.democompany.computerdevice%3Ageneric_computer')", "type": "com.sap.appiot.ThingType" }, "Name": "iot.democompany.computerdevice:generic_computer", "PackageName": "iot.democompany.computerdevice", "Description": "generic use computer", "ExtendedThingType": null, "CopySource": null, "PropertySets": { "results": [ { "__metadata": { "id": "https://config-thing-sap.cfapps.eu10.hana.ondemand.com:443/ThingConfiguration/v1/PropertySets('Model')", "uri": "https://config-thing-sap.cfapps.eu10.hana.ondemand.com:443/ThingConfiguration/v1/PropertySets('Model')", "type": "com.sap.appiot.PropertySet" }, "Name": "Model", "ThingType": "iot.democompany.computerdevice:generic_computer", "Description": "Model of the computer", "PropertySetType": "iot.democompany.computerdevice:Model", "DataCategory": "MasterData", "Operation": "", "ThingTypes": { "__deferred": { "uri": "https://config-thing-sap.cfapps.eu10.hana.ondemand.com:443/ThingConfiguration/v1/PropertySets('Model')/ThingTypes" } }, "PropertySetTypes": { "__deferred": { "uri": "https://config-thing-sap.cfapps.eu10.hana.ondemand.com:443/ThingConfiguration/v1/PropertySets('Model')/PropertySetTypes" } }, "Properties": { "results": [ { "Name": "Manufacturer", "PropertySetType": "iot.democompany.computerdevice:Model", "Description": "Manufacturer of the model", "Type": "String", "PropertyLength": "127", "QualityCode": "0", "UnitOfMeasure": "", "ReferenceProperty": null, "AttributeType": null, "Operation": "", "PropertyType": null, "IsMultiLingual": null }, { "Name": "Series", "PropertySetType": "iot.democompany.computerdevice:Model", "Description": "Series of the model", "Type": "String", "PropertyLength": "127", "QualityCode": "0", "UnitOfMeasure": "", "ReferenceProperty": null, "AttributeType": null, "Operation": "", "PropertyType": null, "IsMultiLingual": null } ] }, "Descriptions": { "__deferred": { "uri": "https://config-thing-sap.cfapps.eu10.hana.ondemand.com:443/ThingConfiguration/v1/PropertySets('Model')/Descriptions" } } }, { "__metadata": { "id": "https://config-thing-sap.cfapps.eu10.hana.ondemand.com:443/ThingConfiguration/v1/PropertySets('CPU_Data')", "uri": "https://config-thing-sap.cfapps.eu10.hana.ondemand.com:443/ThingConfiguration/v1/PropertySets('CPU_Data')", "type": "com.sap.appiot.PropertySet" }, "Name": "CPU_Data", "ThingType": "iot.democompany.computerdevice:generic_computer", "Description": "CPU type and usage data", "PropertySetType": "iot.democompany.computerdevice:CPU_Data", "DataCategory": "TimeSeriesData", "Operation": "", "ThingTypes": { "__deferred": { "uri": "https://config-thing-sap.cfapps.eu10.hana.ondemand.com:443/ThingConfiguration/v1/PropertySets('CPU_Data')/ThingTypes" } }, "PropertySetTypes": { "__deferred": { "uri": "https://config-thing-sap.cfapps.eu10.hana.ondemand.com:443/ThingConfiguration/v1/PropertySets('CPU_Data')/PropertySetTypes" } }, "Properties": { "results": [ { "Name": "cpu_type", "PropertySetType": "iot.democompany.computerdevice:CPU_Data", "Description": "type and model of the CPU", "Type": "String", "PropertyLength": "127", "QualityCode": "0", "UnitOfMeasure": "", "ReferenceProperty": null, "AttributeType": null, "Operation": "", "PropertyType": null, "IsMultiLingual": null }, { "Name": "cpu_usage", "PropertySetType": "iot.democompany.computerdevice:CPU_Data", "Description": "usage of the CPU", "Type": "Numeric", "PropertyLength": "", "QualityCode": "0", "UnitOfMeasure": "MHZ", "ReferenceProperty": null, "AttributeType": null, "Operation": "", "PropertyType": null, "IsMultiLingual": null } ] }, "Descriptions": { "__deferred": { "uri": "https://config-thing-sap.cfapps.eu10.hana.ondemand.com:443/ThingConfiguration/v1/PropertySets('CPU_Data')/Descriptions" } } } ] }, "Descriptions": { "__deferred": { "uri": "https://config-thing-sap.cfapps.eu10.hana.ondemand.com:443/ThingConfiguration/v1/ThingTypes('iot.democompany.computerdevice%3Ageneric_computer')/Descriptions" } }, "ThingTemplates": { "__deferred": { "uri": "https://config-thing-sap.cfapps.eu10.hana.ondemand.com:443/ThingConfiguration/v1/ThingTypes('iot.democompany.computerdevice%3Ageneric_computer')/ThingTemplates" } }, "ObjectAssociations": { "__deferred": { "uri": "https://config-thing-sap.cfapps.eu10.hana.ondemand.com:443/ThingConfiguration/v1/ThingTypes('iot.democompany.computerdevice%3Ageneric_computer')/ObjectAssociations" } } } }

    You can use the property set CPU_Data to create data for a thing.

Log on to answer question
Step 3: Onboard computer device as a thing

Object group is a technical object used for assigning object-based authorizations to user groups. When you assign an object group to a thing, you are allowed to carry out the functions based on the capabilities defined for the user group. You must identify what object group to use while creating a thing.

  1. In Postman, choose the GET method.

  2. Enter the following request URL: https://appiot-mds.cfapps.eu10.hana.ondemand.com/Things.

  3. You can choose an object group ID from one of the things listed in the response payload. You must specify this ID in the request payload for creating a thing.

  4. In Postman, choose the POST method.

  5. Enter the following request URL: https://appiot-mds.cfapps.eu10.hana.ondemand.com/Things.

  6. Go to the Body tab.

  7. Choose the raw option.

  8. Choose JSON (application/json) from the dropdown list.

  9. Enter the following request payload.


    { "_externalId": "lenova_a3", "_alternateId": "lenova_a3_altId", "_name": "lenova_a3", "_description": { "en": "Lenova A3 series" }, "_thingType": [ "iot.democompany.computerdevice:generic_computer" ], "_objectGroup": "45758A9B7CB041B98A13977F92E7AD50" }
  10. In the Headers tab, enter Authorization in the Key column and enter Bearer <<your token>> in the Value column.

    Token for the POST Request

    Note: While working on tutorials in a shared environment, for easy identification of your own objects, use your own user IDs (S-user or P-user depending on the system used) for the object names. To know your ID, see https://iotae-handson.accounts400.ondemand.com/ui/protected/profilemanagement or https://accounts.sap.com/ui/protected/profilemanagement.

  11. Click the Send button. Digital twin of your computer device as a thing is created. The URL of the thing created is returned in the Location field of the Header in the response payload.

    Thing created successfully

    For example, the digital twin lenova_a3 of your computer device is created with a unique thing ID F6395E54A6C643B58B86E7FB1A2E231B. You can use this unique ID to retrieve details of the thing.

  12. In Postman, choose the GET method.

  13. Enter the following request URL: https://appiot-mds.cfapps.eu10.hana.ondemand.com/Things('F6395E54A6C643B58B86E7FB1A2E231B'). Thing details are retrieved and displayed in the response payload.

    {
      "_id": "F6395E54A6C643B58B86E7FB1A2E231B",
      "_externalId": "lenova_a3",
      "_alternateId": "lenova_a3_altId",
      "_name": "lenova_a3",
      "_description": {
        "en": "Lenova A3 series"
      },
      "_thingType": [
        "iot.democompany.computerdevice:generic_computer"
      ],
      "CreatedByUser": "8afb7261-49e8-4f24-8b2b-9d5abd9b81d6",
      "CreatedTime": "2020-02-03T08:30:07.660Z",
      "LastChangedByUser": "8afb7261-49e8-4f24-8b2b-9d5abd9b81d6",
      "LastChangedTime": "2020-02-03T08:30:07.660Z",
      "_objectGroup": "45758A9B7CB041B98A13977F92E7AD50"
    }
    
Log on to answer question
Step 4: Create time series data

Using API endpoints is one of the ways to directly ingest data for a thing. Alternatively, using device management too you can ingest data for a thing.

  1. In Postman, choose the PUT method.

  2. Enter the following request URL: https://appiot-mds.cfapps.eu10.hana.ondemand.com/Things('F6395E54A6C643B58B86E7FB1A2E231B')/iot.democompany.computerdevice:generic_computer/CPU_Data.

    Field Description
    Thing ID F6395E54A6C643B58B86E7FB1A2E231B
    Thing Type iot.democompany.computerdevice:generic_computer
    Property Set CPU_Data
    Property cpu_usage
  3. Go to the Body tab.

  4. Choose the raw option.

  5. Choose JSON (application/json) from the dropdown list.

  6. Enter the request payload as illustrated below:

    {
    "value": [{
    	"_time": "2020-02-01T09:20:00Z",
    	"cpu_usage": 120
    },
    {
    	"_time": "2020-02-01T09:10:00Z",
    	"cpu_usage": 110
    }
    ]
    }
    
  7. In the Headers tab, enter the Authorization in the Key column and enter Bearer <<your token>> in the Value column.

  8. Click the Send button. A numeric value is created for the property cpu_usage with time stamp for the thing F6395E54A6C643B58B86E7FB1A2E231B.

Log on to answer question
Step 5: Read time series data
  1. In Postman, choose the GET method.

  2. Enter the following request URL:
    https://appiot-mds.cfapps.eu10.hana.ondemand.com/Things('F6395E54A6C643B58B86E7FB1A2E231B')/iot.democompany.computerdevice:generic_computer/CPU_Data?timrange=1W.

    Data is requested for a time range=1 week. The other possible values are:

    • #D - For the specified number days
    • #M - For the specified number months
    • #H - For the specified number of hours
    • From time - To time

    Data retrieved successfully.

    {
    "value": [
        {
            "_time": "2020-02-01T09:20:00.000Z",
            "cpu_type": null,
            "cpu_usage": 120
        },
        {
            "_time": "2020-02-01T09:10:00.000Z",
            "cpu_type": null,
            "cpu_usage": 110
        },
        {
            "_time": "2020-02-01T09:00:00.000Z",
            "cpu_type": null,
            "cpu_usage": 100
        }]
      }
    

    Similarly, you can retrieve thing data in various other ways such as Snapshot data, using M4 algorithm, and aggregates using OData services. For more information, see https://help.sap.com/viewer/p/SAP_IoT > Develop > SAP IoT Services.

Select the correct application name to create a thing:
×
Step 6: Explore IoT APIs in SAP API Hub (optional)

To better understand SAP IoT APIs, you can go to SAP API Hub at https://api.sap.com/package/IOTAE?section=Artifacts and review and execute different APIs in its sandbox.

Log on to answer question

Next Steps

Back to top