Skip to content

Commit fe4f6ff

Browse files
dariachendariachen
authored
MCS-3954: update some api references. (#109)
* MCS-3954: update some api references.
1 parent 4404c0e commit fe4f6ff

File tree

9 files changed

+1205
-930
lines changed

9 files changed

+1205
-930
lines changed

‎content/en/api_references/README.md

Lines changed: 86 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,100 +1,142 @@
11
# API references
22

3-
MediaTek Cloud Sandbox (MCS) provides RESTful APIs for building applications and services that are able to make meaningful communications with MCS including data point uploads and retrievals as well as commands via TCP socket. MCS also provides eady-to-read visual charts based on the uploaded data, including time-series data for real time applications.
3+
MediaTek Cloud Sandbox (MCS) provides a bunch of RESTful APIs by which you can build your IoT applications and services. For example, you can upload the data points generated by the devices to MCS and retrieve them back for analysis later on.
44

5+
MCS also provide an easy-to-read charts and reports to visualize your data and devices in real time.
56

67
## Request URL
78

8-
Standard MCS RESTful API request has the following URL construct:
9+
The base URL of MCS services is
910

1011
```
11-
https://api.mediatek.com/v2
12+
https://api.mediatek.com/mcs/v2/
1213
```
1314

15+
You can access and operate a specific resource by specifying a **resource ID** in the request URL. Take the request below as an example, we can access data points under a specific device and channel by providing their ID in the request.
1416

15-
## Parameters
17+
```
18+
https://api.mediatek.com/mcs/v2/devices/{deviceID}/datachannels/{dataChannelID}/datapoints.csv
19+
```
1620

17-
The parameters that are part of URL are used to identify a specific resource.
21+
**Example**
22+
23+
Here is the complete HTTP request for retrieving data points (please replace {variable} to your real device data), we will go into details of each API in later section.
1824

1925
```
20-
https://api.mediatek.com/v2/devices/{deviceId}/retrieveDataPoints
26+
curl -X GET \
27+
https://api.mediatek.com/mcs/v2/devices/{deviceID}/datachannels/{dataChannelID}/datapoints.csv \
28+
-H 'devicekey: {deviceKey}' \
2129
```
2230

23-
In the example above, the **device ID** is specified in the URL.
24-
31+
## Request Method
2532

26-
Also, the perementers can be in the message body of a POST request. The request body must be formatted as either JSON or CSV. For each POST request, please specify the **content-type** in the header.
33+
The MCS RESTful APIs can be accessed with the following HTTP methods:
2734

28-
* `content-type: application/json` stands for JSON format.
29-
* `content-type: text/csv` stands for CSV format.
35+
**GET** - To retrieve resources.
3036

37+
**POST** - To create resources.
3138

32-
## Client Errors
39+
**PUT** - To update resources.
3340

34-
MediaTek Cloud Sandbox (MCS) uses the standard HTTP status code to indicate if an API request is successful or failed. The HTTP status codes users may encounter are:
41+
**DELETE** - To delete resources.
3542

36-
**200 OK** - The request is successful.
43+
## Request Header
44+
###1. Access Token
3745

38-
**201 Created**- The request has been fulfilled and a new resource is being created.
46+
The request attempt is allowed only after it successfully pass the authentication. Therefore, you have to add some special HTTP headers in the request for MCS services to deal with authentication.
3947

40-
**202 Accepted** - The request has been accepted for processing, but the process has not been completed yet.
48+
There are 2 different types of authentication.
4149

42-
**204 No Content** - The server processed the request successfully, but isn’t returning any content. This is usually used as a response for a successful delete request.
50+
* **Service provider account**:
51+
52+
If you are going to develop your own application, including a mobile App or web application, you can apply for an appID and appSecret on Profile -> Service provider page and use this credential to access all MCS open APIs.
53+
54+
Add **appID** and **appSecret** in the header for all your MCS API requests.
55+
56+
```
57+
appId: {your_appId}
58+
appSecret: {your_appSecret}
59+
```
4360

44-
**400 Bad Request** - The server cannot process the request due to an unexpected parameter received from the client.
61+
* **Device key**:
4562

46-
**401 Unauthorized** -Authorization has failed or it hasn’t been provided. A header for Authorization is required.
63+
If you are developing device application and only need to use device-related APIs, such as uploading and retrieving data points, you can use device ID and key directly for authentication.
64+
You can find the device ID and key in the device details page, and then add **deviceKey** in the header for all your device-related API requests.
65+
66+
```
67+
deviceKey: {your_device_key}
68+
```
69+
Since the device ID is already used in the request URL to specify the resource to be accessed, it is not necessary to add it into the header.
4770

48-
**403 Forbidden** - The server is refusing to respond to a valid request.
4971

50-
**404 Not Found** - The requested resource could not be found.
72+
###2. content-type
5173

52-
**405 Method Not Allowed** - The request was made from a resource that used a method which is not supported.
74+
You must add **content-type** to the request header. This field allows the MCS service to know the format of request body and how to process the data subsequently.
5375

54-
**500, 502 Server Error** - MCS server has encountered an error.
76+
* `content-type: application/json` the body is in JSON format.
77+
* `content-type: text/csv` the body is in CSV format.
5578

79+
## Request Body
5680

57-
## HTTP Verbs
81+
MCS supports request content in either **JSON** or **CSV** format. The parameters required by each API is different. Therefore, the detailed request content will be described in the chapter of individual APIs.
5882

59-
The MCS RESTful APIs can be accessed with following HTTP methods:
6083

61-
**GET** - To retrieve resources.
84+
## Parameters
6285

63-
**POST** - To create resources.
86+
Here are some basic parameters using in MCS APIs.
6487

65-
**PUT** - To update resources.
88+
* **Timestamp**
89+
90+
The timestamp is used to record the exact time when a resource was created or updated, such as the time when the data point was uploaded, the time the prototype was created, and so on.
91+
92+
In the MCS system, timestamp is in **Unix Epoch** format and the time unit is milliseconds. If you want to convert the Unix Epoch to human readable time format, please refer to [http://www.epochconverter.com/](http://www.epochconverter.com/). For example:
6693

67-
**DELETE** - To delete resources.
94+
> *Timestamp in milliseconds: 1524720177000*
95+
> is converted to
96+
> *Human time (GMT): Thursday, April 26, 2018 5:22:57 AM*
97+
6898

99+
* **Resource ID**
69100

70-
## Authentication
101+
Each time a prototype, test device, data channel, or firmware file is created, a unique ID is assigned to the resource. This ID is not editable and then you can access the resource by specifying the ID.
102+
103+
For example, to retrieve data from a specific data channel, you will need to know the ID of this data channel and test device. And then specify these 2 IDs in the request URL.
104+
105+
Here are 3 major resource types in MCS:
106+
107+
108+
1. **Data channel**：Data channel is a logical placeholder in the cloud for data generated from a specific component of a physical device, or a command from the cloud to be pushed into a specific component of the connected physical device. In other words, data channel is designed for one-way or two-way communications between the cloud and the connected physical device.
109+
110+
MCS provides RESTful APIs to easily retrieve data from the data channels and update the data channel.
71111

72-
Except for data point uploads and retrievals APIs, all requests sent to the API server need to be authenticated. A Bearer token for **Authorization** key in the HTTP header is required. If it is not provided, the server will respond with an **Unauthorized** message.
112+
2. **Device**：There are two types of devices which you can create in MCS: test device and Beta device. The test device enables you to test the functionality of the prototype before it is Beta-released. The Beta device can be created after a prototype is Beta-released and it’s used by the end user.
73113

114+
115+
3. **Prototype**：A prototype is a service that’s delivered as a result. The MSC provides several APIs to make use of the prototype. The developer can add data channels in a prototype and test the prototype by creating a test device before releasing it.
74116

75-
## Resource IDs
117+
118+
## Client Errors
76119

77-
When a prototype or a data channel is created, or when a device is added, a unique ID is assigned to each prototype, data channel or device. This unique ID is not editable, but it can be used to access data with which it is associated. However, the key cannot access data from any other resource.
120+
MediaTek Cloud Sandbox (MCS) uses the standard HTTP status code to indicate if an API request is successful or failed. The HTTP status codes users may encounter are:
78121

79-
For example, to GET data from a specific data channel of a test device, you will need to use a data channel ID for the data channel of the test device.
122+
**200 OK** - The request is successful.
80123

124+
**201 Created** - The request has been fulfilled and a new resource is being created.
81125

82-
## Resources
126+
**202 Accepted** - The request has been accepted for processing, but the process has not been completed yet.
83127

84-
Following is a shortlist of useful terms of MCS:
128+
**204 No Content** - The server processed the request successfully, but isn’t returning any content. This is usually used as a response for a successful delete request.
85129

86-
### Data Channels
130+
**400 Bad Request** - The server cannot process the request due to an unexpected parameter received from the client.
87131

88-
The data channel is a logical placeholder in the cloud for data generated from a specific component of a physical device, or a command from the cloud to be pushed into a specific component of the connected physical device. In other words, data channel is designed for one-way or two-way communications between the cloud and the connected physical device.
132+
**401 Unauthorized** - Authorization has failed or it hasn’t been provided. A header for Authorization is required.
89133

90-
MCS provides RESTful APIs to easily retrieve data from the data channels and update the data channel.
134+
**403 Forbidden** - The server is refusing to respond to a valid request.
91135

92-
### Devices
136+
**404 Not Found** - The requested resource could not be found.
93137

94-
There are two types of devices which you can create in MCS: test device and Beta device. The test device enables you to test the functionality of the prototype before it is Beta-released. The Beta device can be created after a prototype is Beta-released and it’s used by the end user.
138+
**405 Method Not Allowed** - The request was made from a resource that used a method which is not supported.
95139

96-
MCS provides RESTful APIs for you and the end user. For example, APIs that enable data retrieval from a device and that allow remote control using the device.
140+
**500, 502 Server Error** - MCS server has encountered an error.
97141

98-
### Prototype
99142

100-
A prototype is a service that’s delivered as a result. The MSC provides several APIs to make use of the prototype. The developer can add data channels in a prototype and test the prototype by creating a test device before releasing it.

0 commit comments

Comments
 (0)