Skip to content

Commit

Permalink
MCS-3954: update some api references. (#109)
Browse files Browse the repository at this point in the history 
* MCS-3954: update some api references.
  • Loading branch information
@dariachen
dariachen authored Apr 26, 2018
1 parent 4404c0e commit fe4f6ff
Show file tree
Hide file tree
Showing 9 changed files with 1,205 additions and 930 deletions.
130 changes: 86 additions & 44 deletions content/en/api_references/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,100 +1,142 @@
# API references

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.
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.

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

## Request URL

Standard MCS RESTful API request has the following URL construct:
The base URL of MCS services is

```
https://api.mediatek.com/v2
https://api.mediatek.com/mcs/v2/
```

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.

## Parameters
```
https://api.mediatek.com/mcs/v2/devices/{deviceID}/datachannels/{dataChannelID}/datapoints.csv
```

The parameters that are part of URL are used to identify a specific resource.
**Example**

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.

```
https://api.mediatek.com/v2/devices/{deviceId}/retrieveDataPoints
curl -X GET \
https://api.mediatek.com/mcs/v2/devices/{deviceID}/datachannels/{dataChannelID}/datapoints.csv \
-H 'devicekey: {deviceKey}' \
```

In the example above, the **device ID** is specified in the URL.

## Request Method

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.
The MCS RESTful APIs can be accessed with the following HTTP methods:

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

**POST** - To create resources.

## Client Errors
**PUT** - To update resources.

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:
**DELETE** - To delete resources.

**200 OK** - The request is successful.
## Request Header
###1. Access Token

**201 Created**- The request has been fulfilled and a new resource is being created.
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.

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

**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.
* **Service provider account**:

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.

Add **appID** and **appSecret** in the header for all your MCS API requests.

```
appId: {your_appId}
appSecret: {your_appSecret}
```

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

**401 Unauthorized** -Authorization has failed or it hasn’t been provided. A header for Authorization is required.
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.
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.
```
deviceKey: {your_device_key}
```
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.

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

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

**405 Method Not Allowed** - The request was made from a resource that used a method which is not supported.
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.

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

## Request Body

## HTTP Verbs
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.

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

**GET** - To retrieve resources.
## Parameters

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

**PUT** - To update resources.
* **Timestamp**

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.

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:

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


* **Resource ID**

## Authentication
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.

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.

Here are 3 major resource types in MCS:

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.

MCS provides RESTful APIs to easily retrieve data from the data channels and update the data channel.

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.
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.


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.

## Resource IDs

## Client Errors

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.
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:

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.
**200 OK** - The request is successful.

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

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

Following is a shortlist of useful terms of MCS:
**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.

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

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.
**401 Unauthorized** - Authorization has failed or it hasn’t been provided. A header for Authorization is required.

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

### Devices
**404 Not Found** - The requested resource could not be found.

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.
**405 Method Not Allowed** - The request was made from a resource that used a method which is not supported.

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.
**500, 502 Server Error** - MCS server has encountered an error.

### 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.
Loading

0 comments on commit fe4f6ff

Please sign in to comment.