Global Description

SmartHub API is a RESTFULAPI style based on the HTTPS protocol.

You can visit SmartHub APi with your favourite HTTP/REST Library (eg. Apache Http Client) or HTTP/REST Client (eg. Postman).

Version

Put the version number in your URI, for example:

https://xxx.smh.smarthing.com/v1/users

Schema

All SmartHub API based on the HTTPS protocol

the Production URL is https://xxx.smh.smarthing.com/v1.

the Trial URL is https://trial.api.smh.smarthing.com/v1.

All Request and Response data are in JSON format.

All of the time fields are formatted as “ISO 8601” and return in yyyy-MM-dd'T'HH:mm:ssZ.

Authentication

SmartHub API provide following methods of certification.

ApiKeyAuth

Please securely store your authentication information, DO NOT share with others.

Authentication Failed returns

Invalid authentication identity returns 401 Unauthorized:

{
  "type": "about:blank",
  "title": "Invalid api key",
  "status": 401
}

Unauthorized access to resources returns 403 Forbidden:

{
    "type": "about:blank",
    "title": "Access forbidden",
    "status": 403
}

Root endpoint

You can get all endpoints categories which provided by SmartHub API when you access the root endpoint:

Client Error

There are 3 possible client errors when you call the API

Sending invalid JSON format returns 400 Bad Request

{
    "type": "about:blank",
    "title": "Bad Request",
    "status": 400,
    "detail": "Body should be a JSON object"
}

Sending invalid JSON value type returns 400 Bad Request

{
    "type": "about:blank",
    "title": "Bad Request",
    "status": 400,
    "detail": "Body should be a JSON object"
}

Sending no value field returns 422 Unprocessable Entity

{
    "type": "about:blank",
    "title": "Validation Failed",
    "status": 422,
    "errors": [
        {
            "resource": "customFieldVO",
            "field": "custom1",
            "code": "invalid"
        }
    ]
}

All the error objects have the resources and the field properties, so that the client can find the problem:

error code	description
missing	resource doesn’t exist
missing_field	the required fields of the resource is not set
invalid	the field format is invalid, please see the documental descriptorion of the resource
already_exists	the resource already exists

The resources could customize error codes, customized error code provide message field for error description, for some error additional documentation_url field
is providing further description.

HTTP Redirect

SmartHub API use HTTP when neccessary.

Client side should always assume any request will be redirect, it is not an error for receiving http redirection. Client endpoint should following the
redirection, redirect response will carry Location field in the response, this field is the URI that client endpoint should resend the resource request to.

code	description
`301`	Permanently redirected. Oringnal 'URI' has been moved to the new `URI`, this request and future requests to the resource should be directed to the new `URI`.
`302`,`307`	temporarily redirected. This request should be redrected to `URI` in the `Location` field.

HTTP ACTIONS

SmartHub API will invoke every action with adaquate HTTP Actions.

action	description
`HEAD`	receive resource header information, resource content is not included.
`GET`	receive resource
`POST`	create resource
`PUT`	replace the resource or collection. For empty `body` request, please make sure `Content-Length` is 0.
`DELETE`	delete resource

Hypermedia

All resources containe *_url property may link to other resource, these linkages provide explicit URL so that API client use the URL without having
to reconstruct the URL, We strongly recommend API client to use this feature, so the developer can be easily upgrade the API.

All URL complies URL 6570 URI standard.

Pagination

By default, returned item-requests will return 30 items, client can use ?page parameter for return additional pages.
For some resource request, client can use ?size to specify number of item per page, max 100 per page

?page starts from 1, if request contain no such parameter, it will default to first page.

Link header

Strongly recommend using the URL provided by “Link Header”to call the resources.

Link Header includes paging information.

# one page
Link: <https://xxx.smh.smarthing.com/points?page=0&size=20>;
rel="last",<https://xxx.smh.smarthing.com/points?page=0&size=20>;
rel="first"
X-Total-Count: 10
# multi pages
Link: <https://xxx.smh.smarthing.com/points?page=2&size=20>;
rel="next",<https://xxx.smh.smarthing.com/points?page=0&size=20>;
rel="prev",<https://xxx.smh.smarthing.com/points?page=5&size=20>;
rel="last",<https://xxx.smh.smarthing.com/points?page=0&size=20>;
rel="first"
X-Total-Count: 110

rel defined as follow

name	description
`next`	next page
`last`	last page
`first`	first page
`prev`	previous page

Restriction

API calls are limited to 5000 requests per hour per accunt. HTTP response header will indicate request limit status.

header name	description
`X-RateLimit-Limit`	Max allowed request count per hour
`X-RateLimit-Remaining`	remaining allowed request counts
`X-RateLimit-Reset`	current request limit reset time

If rate limit is exceeded, returns the following error message

X-RateLimit-Limit: 1
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 3600
{
  "type":"about:blank",
  "title":"API rate limit exceeded",
  "status":429
}

CORS

SmartHub API support cross domain visit (CORS), support AJAX request from other domain.

Following is an example of visit from http://example.com calling SmartHub API.

Following is CORS Pre-screen check response

Time zone

All SmartHub API request use UTC time as creation time and operation time.

Push

To Push message on SmartHub platform, User should configure Push URL, e.g: https://xxx.smh.smarthing.com/v1/mo-sms. The message format please refer to Push section in the API document. Specify URL should be set for each type of Push messages.

Push Certification

SmartHub Push should attach signature in the request boday, generation rules are:

Field	Type	Rule
signature	String	HEX(SHA256(`pushKey` + datePush))

pushKey user configuration on SmartHub

datePush request send time, precision to second

SHA256 using 'SHA256' alg to hash input data, note: the result is the 8bit octet array

HEX encoding input 8bit octets in hexadecimal notation

Code samples for making signature（Java）：

public class Signature {
    public static byte[] SHA256(byte[] data) throws java.security.NoSuchAlgorithmException {
        return java.security.MessageDigest.getInstance("SHA-256").digest(data);
    }

    public static String HEX(byte[] octets) {
        StringBuilder sb = new StringBuilder();

        for(byte b: octets) {
            if (b >= 0 && b < 16) sb.append("0");
            sb.append(Integer.toHexString(b & 0xFF));
        }

        return sb.toString();
    }

    public static String makeSignature(String pushKey, long epocSeconds) throws Exception {
        return HEX(SHA256((pushKey + epocSeconds).getBytes("UTF8")));
    }

    public static void main(String[] args) throws Exception {
        System.out.println(makeSignature("UzE4MDkxNDA2MTE1M", 1725499848L));
        // Output: 58210277eeea982589a3f2c5711ce5ac23a866298d77fcb5c30bb1e0aa9c345f
    }
}

Push FTP Cdr

SmartHub platform provides the function of pushing the CDRS to the client's ftp server, which requires the client to have the corresponding ftp server and connect the relevant configuration with the platform. The pushed traffic CDRS are in CDR_D_xx.cdr format and the SMS CDRS are in CDR_S_xx.cdr format. The contents of the file are as follows:

data cdr:

{"giccid":"8944501503181377993","data_usage":1302,"start_time":1713888842473,"duration":0,"mcc":"460","country_code":"CN","apn":"apn1","imsi":"460001234567890","sim_group":"groupA"}

sms cdr:

{"giccid":"8944500310194312699","event_time":1711889742473,"from_msisdn":"882360010341361","to_msisdn":"449086237252","imsi":"460001234567890","sim_group":"groupA"}

Version#

Schema#

Authentication#

Authentication Failed returns#

Root endpoint#

Client Error#

HTTP Redirect#

HTTP ACTIONS#

Hypermedia#

Pagination#

Link header#

Restriction#

CORS#

Time zone#

Push#

Push Certification#

Push FTP Cdr#