Accessing API

  4 min read  

1. Accessing RESTful API

Your API-Gateway based RESTful API can be accessed with URL pattern:

https://ics.rapidomize.com/api/v1/agw/{icappId}/{paths}

Where:

• {icappId} - is your ’s ID. e.g. cfba0c2c-5f61-4866-a3ed-4c2e56f745e7
• {path} - is the endpoint path you defined in routing rules when configuring API-Gateway e.g. endpoint path pattern /customer/{id} for accessing customer with a given id.

For example you can call your APIs using cURL as follows:

curl -H 'Content-Type: application/json' \
     -H 'Authorization: Basic Base64Encoded_API_TOKEN' \
     -d '{ "id":1, "name":"John Smith", "address": {"street": "21 2nd Street", "city": "New York", "state": "NY", "zip": "10021-3100"}}' \
     -X POST \
    https://ics.rapidomize.com/api/v1/agw/{icappId}/{path}

curl -H 'Authorization: Basic Base64Encoded_API_TOKEN' \
     -X GET \
    https://ics.rapidomize.com/api/v1/agw/{icappId}/{path}

curl -H 'Content-Type: application/json' \
     -H 'Authorization: Basic Base64Encoded_API_TOKEN' \
     -d '{ "id":1, "name":"Jane Smith", "address": {"street": "123A Street", "city": "Boston", "state": "MA", "zip": "1567-1234"}}' \
     -X PUT \
    https://ics.rapidomize.com/api/v1/agw/{icappId}/{path}

curl -H 'Content-Type: application/json' \
     -H 'Authorization: Basic Base64Encoded_API_TOKEN' \
     -d '{ "name":"Jane Smith"}' \
     -X PATCH \
    https://ics.rapidomize.com/api/v1/agw/{icappId}/{path}

curl -H 'Authorization: Basic Base64Encoded_API_TOKEN' \
     -X DELETE \
    https://ics.rapidomize.com/api/v1/agw/{icappId}/{path}

2. Accessing Generic ICApp Based API

With this method s can be triggered through API using HTTP, Websocket, or MQTT protocols. When using HTTP, only POST, GET methods are supported. This type of APIs can also be used for data ingestion for ETL/ELT data pipelines build for data Analytics or for your Data Lakes to receive structured, semi-structured, and unstructured data.

Endpoint URIs

• HTTP/Websocket: https://ics.rapidomize.com/api/v1/icapp/{icappId}
• MQTT: ssl://ics.rapidomize.com:8883 - For more information refer to IoT API

Default path /api/v1/icapp/{icappId} is used to trigger an . This is somewhat resembles to a Webhook however, it supports HTTP, Websocket, or MQTT protocols and you can also receive configurable response payload from this API.

Note that, this type of API endpoints does not contain any custom {path} as in API-Gateway endpoints paths

Supported MIME types for this API are:

• JSON (application/json)
• Form Data(application/x-www-form-urlencoded),
• TEXT (text/plain, …),
• BINARY data (Base64 encoded).

All MIME types data are automatically converted to a JSON payload to make it consistent for configuration.

If using binary data encode the data as Base64. The server/cloud platform does not interpret or decode these data, so if you are not intending to process these data using ICApps, you can also send end-to-end encrypted binary data this way. As ICApp works using JSON and macros, on the server/cloud platform, when configuring ICApps you will use the field name “payload” to access binary data i.e. {"payload": base64 encoded data}

For example you can trigger your s via HTTP using cURL as follows:

    curl -H 'Content-Type: application/json' \
        -H 'Authorization: Basic Base64Encoded_API_TOKEN' \
        -d '{ "id":1, "name":"John Smith", "address": {"street": "21 2nd Street", "city": "New York", "state": "NY", "zip": "10021-3100"}}' \
        -X POST \
        https://ics.rapidomize.com/api/v1/icapp/{icappId}
  

  curl -H 'Authorization: Basic Base64Encoded_API_TOKEN' \
      -X GET \
      https://ics.rapidomize.com/api/v1/icapp/{icappId}


  OR

  curl -X GET \
       https://ics.rapidomize.com/api/v1/icapp/{icappId}?token=YOUR_TOKEN 

  

2.1 Endpoints Variants

2.1.1 File Upload

/api/v1/icapp/{icappId}/upload - Upload a files for processing

With this API endpoint you can upload a file (< 5mb) with some metadata to be processed by the . Payload JSON must contain a mandatory field ‘file’ to represent the file-name & ‘content-type’ to represent media-type of the file. e.g.

{
    "file": "data.txt",           <--- file-name
    "content-type": "text/plain",
    "my-meta1": ...,
    "my-meta2": ...,
    "payload": base64 encoded file data, 
}

2.1.2 Events

/api/v1/icapp/{icappId}/event - Events reporting

You can use this endpoint for data ingestion for Analytics

1. Web, Mobile, Server App/Device telemetry data capturing for Analytics.
2. Refer to App or Device Events reporting in IoT API for more info on how to use this API for reporting state changes in your App/Device properties to maintain digital twin model state.

Note that, all events must have a way to associate them with a unique instance/session id, and must have meaningful way to associate them with e.g. user id, resource id, asset id …etc. It is your responsibility to define such relationship in your data so that data can be meaningful for analytics.

For example you can capture online store user activity for Analytics using via HTTP (cURL example) as follows:

curl -H 'Content-Type: application/json' \
     -H 'Authorization: Basic Base64Encoded_API_TOKEN' \
     -d '{ "_evt":"Add To Cart", "item_code":"A00342", "q":2, "price":10.50}' \
     -X POST \
    https://ics.rapidomize.com/api/v1/icapp/{icappId}/event

OR    
    
curl -H 'Content-Type: application/x-www-form-urlencoded' \
     -d 'n=Add To Cart' \
     -d 'item_code=00342' \
     -d 'q=2' \
     -d 'price=10.50' \
     -X POST \
     https://ics.rapidomize.com/api/v1/icapp/{icappId}/event?token=YOUR_TOKEN 

Client SDK

Refer to Client SDK for a list of client SDKs that you can use in your favorite language to access the APIs.