Documentation
Public Management API
Qmiix provides sets of public management API for partner app. These APIs are public accessible to partner apps with rate limit.
General API Requirments
The following subsections specify how to utilize Qmiix management API with regard to recipe execution.
HTTPS
Qmiix API is served over HTTPS.
API URL prefix
Headers with Authentication
Use UTF-8 as the response encoding and support HTTP-level compression. Requests to Qmiix have the following headers:
Authorization: Bearer {{partner app access_token}}
Qmiix-App-Key: {{qmiix_app_key}}
Accept: application/json
Accept-Charset: utf-8
Accept-Encoding: gzip, deflate
Content-Type: application/json
X-Request-ID: {{random_uuid}}
Headers without Authentication
Use UTF-8 as the response encoding and support HTTP-level compression. Requests to Qmiix have the following headers:
Qmiix-App-Key: {{qmiix_app_key}}
Accept: application/json
Accept-Charset: utf-8
Accept-Encoding: gzip, deflate
Content-Type: application/json
X-Request-ID: {{random_uuid}}
HTTP status codes
Qmiix will return the following set of HTTP response status codes.
Status Code
Description
200
The request was a success.
400
There was something wrong with incoming data from Qmiix. Provide an error response body to clarify what went wrong.
401
Invalid OAuth2 access token.
404
Trying to reach a URL that doesn’t exist.
500
Internal server error.
503
Qmiix service is not available at the moment, partner app should try again later.
Acquiring Qmiix OAuth Token
Qmiix OAuth2 Client ID and Secret:
Currently the OAuth2 client id and secret are manually provided through email communication.
Qmiix OAuth2 Grant Type Client Credential Flow:
The Qmiix public APIs are for public access, non-user specific information. To utilize these APIs, your app still needs to provide an access token. However, your app simply requests an access token by providing it's Qmiix oauth client id and secret, without asking user to login and approve. This flow is also known as the Client Credentials Grant defined in OAuth 2.0 specification. Please note that If access token has expired, app should make token request again to get a new access token.
Here are the steps of the flow:
-
Making Token Request: Application sends its Qmiix oauth client id and secret to backend token endpoint
-
Handling Response: If success, an access token is returned to application, application may store it for later use
Making Token Request:
The URL used to retrieve access token is token endpoint. App sends a HTTPS POST request to this url with parameters listed below.
Note that the Content-Type header must set to "application/x-www-form-urlencoded".
|
Parameter |
Description |
|
grant_type |
Must be client_credentials |
|
client_id |
the app_id of your application |
|
client_secret |
the secret of your application |
Example Request and Response
Request:
POST /oauth/token HTTP/1.1
Host: qmiix.com
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&
client_id=s6BhdRkqt3&
client_secret=7Fjfp0ZBr1KtDRbnfVdmIw
Response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 { "token_type": "Bearer", "access_token": "324878904ehioawhlkqewopque0492038", "expires_in" : 86500 }
Action Status
For each action api called to partner app, Qmiix will add an unique event execution id in the request for that event to be executed. If the event is executed asynchronously in partner app, e.g., download a huge file, Qmiix provide an aciton status api for partner app to update the execution status of that event. Other requirements and limitations are as followed:
-
It is mandatory to update the execution status to Qmiix, if partner specifies true to asynchronous field in action response.
-
Note that Qmiix assume sending actions to mobile app as asynchronous calls by nature. Therefore, the mobile app should update the action status to Qmiix.
Request
HTTP
|
Method |
PUT |
|
URL |
{{qmiix_api_url}}/v1/action/status |
Example
PUT /v1/action/status HTTP/1.1 Host: api.qmiix.com Authorization: Bearer {{partner app access_token}} Qmiix-App-Key: {{qmiix_app_key}} Accept: application/json Accept-Charset: utf-8 Accept-Encoding: gzip, deflate X-Request-ID: {{random_uuid}} Body: { "tasks": [ { "execution_id": "aabjkhc", "execution_status": "failed", "message": "file size is too big" }, { "execution_id": "12345", "execution_status": "success" } ] }
Response
HTTP/1.1 200 OK Content-Type application/json; charset=utf-8 { "code": "ok", "message": "OK." "result": { "fail_counts": 1, "results": [ { "code": "not_found", "message": "no such execution id", "execution_id": "12345" } ] } }
Realtime API
With Qmiix's Realtime API, you can have miixes involving user-oriented triggers from your app run near-instantly. Simply write a hook to notify Qmiix of any changes related to a given user which would correspond to a trigger they may be using. There are two types of Realtime API. Partner app could send Qmiix event data with specified trigger identity directly by Realtime Event API. Or on the other hand, rather than sending data directly, the Realtime Notification API is used to notify Qmiix that there are new events available at your app for a specific user_id or trigger identity that Qmiix can then fetch through polling.
If Realtime API is used for a trigger identity, we can limit the load on your app by polling less frequently. However, Qmiix is guaranteed to at least poll once about every 20 minutes (The period might be changed).
1. Realtime Event API
Partner app could send Qmiix event data with specified trigger identity directly by Realtime Event API.
Request
HTTP
|
Method |
POST |
|
URL |
https://realtime.qmiix.com/v1/events/{trigger_identity} |
Headers:
Authorization: Bearer {{partner app access_token}}
Accept: application/json
Accept-Charset: utf-8
Accept-Encoding: gzip, deflate
Content-Type: application/json
X-Request-ID: {{random_uuid}}
Body
"data": [ { "ingredient 1": "value for ingredient 1", "ingredient n": "value for ingredient n", "meta": { "id": "14b9-1fd2-acaa-5df5", //(string) a unique identifier for the item. "timestamp": 1383597267 // (integer) a Unix timestamp in seconds. }, ... } ]
Example
POST /v1/events HTTP/1.1 Host: realtime.qmiix.com Authorization: Bearer {{partner app access_token}} Accept: application/json Accept-Charset: utf-8 Accept-Encoding: gzip, deflate Content-Type: application/json X-Request-ID: {{random_uuid}} { "data": [ { "ingredient 1": "value for ingredient 1", "ingredient n": "value for ingredient n", "meta": { "id": "14b9-1fd2-acaa-5df5", //(string) a unique identifier for the item "timestamp": 1383597267 // (integer) a Unix timestamp in seconds. }, ... ] }
Response
{ "data": { // The value of `data` either an object or array } }
2. Realtime Notification API
Rather than sending data directly, the Realtime Notification API is used to notify Qmiix that there are new events available at your app for a specific user_id or trigger identity that Qmiix can then fetch through polling.
Request
HTTP
|
Method |
POST |
|
URL |
https://realtime.qmiix.com/v1/notifications |
Headers
Authorization: Bearer {{partner app access_token}}
Accept: application/json
Accept-Charset: utf-8
Accept-Encoding: gzip, deflate
Content-Type: application/json
X-Request-ID: {{random_uuid}}
Body
"data": [ { "user_id": "25794567" }, { "user_id": "99876426" }, { "trigger_identity": "f4448fg2hd74hgh673s364d891292e02233933a5" }, ... ]
Example
POST /v1/notifications HTTP/1.1 Host: realtime.qmiix.com Authorization: Bearer {{partner app access_token}} Accept: application/json Accept-Charset: utf-8 Accept-Encoding: gzip, deflate Content-Type: application/json X-Request-ID: {{random_uuid}} { "data": [ { "user_id": "25794567" }, { "user_id": "99876426" }, { "trigger_identity": "f4448fg2hd74hgh673s364d891292e02233933a5" }, ... ] }
Response
{ "data": { // The value of `data` either an object or array } }
Action Polling API
We provide an action polling API for our partners to actively polls for unexecuted actions on a non-realtime basis. This API is helpful for services which are inevitably unavailable from time to time. Take mobile devices as a example. There are often times mobile devices are offline (turned off or network disconnected) while Qmiix sending actions to them. In this manner, the mobile app should be polling for the non-executed actions temporarily queued in Qmiix cloud from time to time to ensure there are no missing actions especially when resuming network or restarted. However, the web channel framework might not need to use this API because web channel app are assumed to be always online whereas for mobile devices chances are they might be out of service from time to time.
Request
HTTP
|
Method |
GET |
|
URL |
{{qmiix_api_url}}/v1/action/poll?device_id={device_id}&since={last execution_id}&limit={limit} |
Example
GET /v1/action/poll?device_id=1212736187aceecd2179&since=oiea1268910acdr83212&limit=5 HTTP/1.1
Host: api.qmiix.com
Authorization: Bearer {{partner app access_token}}
Qmiix-App-Key: {{qmiix_app_key}}
Accept: application/json
Accept-Charset: utf-8
Accept-Encoding: gzip, deflate
X-Request-ID: {{random_uuid}}
Response
HTTP/1.1 200 OK Content-Type application/json; charset=utf-8 { "code": "ok", "message": "OK.", "result" :[ { "slug": "download_new_file", "action_essentials": { "folder_path": "/qmiix", "file_path": "http://image.com/123456" }, "qmiix_source": { "id": "2", "url": "https://qmiix.com/mymiixes/personal/2", "execution_id": "oiea1268910acdr83212" }, "user": { "timezone": "Pacific Time (US & Canada)" } }, { "slug": "append_to_a_file", "action_essentials": { "folder_path": "/qmiix", "file_path": "http://image.com/123247289h" }, "qmiix_source": { "id": "2", "url": "https://qmiix.com/mymiixes/personal/2", "execution_id": "oiea1268910acd213293" }, "user": { "timezone": "Pacific Time (US & Canada)" } } ] }
