Getting Started
- Que Nguyen
- allen li
- Tho Nguyen
- Xiaowei Chen
Table of Content
- 1 Table of Content
- 2 Naming
- 3 Action
- 4 Versioning
- 5 Request/Response Body Format
- 5.1 Data - Response body data
- 5.1.1.1 Serialized record
- 5.1.2 Date time / Timestamp
- 5.1.3 Error Object
- 5.1.4 Pagination
- 5.1 Data - Response body data
- 6 Response Status codes
- 6.1 Successful Responses
- 6.1.1 200 OK
- 6.1.2 201 Created
- 6.2 Client error messages
- 6.2.1 400 Bad Request
- 6.2.2 401 Unauthorized
- 6.2.3 403 Forbidden
- 6.2.4 404 Not Found
- 6.2.5 422 Unprocessable Entity
- 6.3 Server error responses
- 6.3.1 500 - Server errors
- 6.1 Successful Responses
- 7 Rate limit
- 7.1 Rate Limiting Overview
- 7.1.1 Global Policy 全局策略
- 7.1.2 Summary
- 7.1 Rate Limiting Overview
Naming
Type | Description | Example |
|---|---|---|
Language | Must use clear and concise English terms 必须使用清晰简洁的英文名称 |
|
Case | API resources must be in plural form using |
|
Request/Response Properties in Upper Camel Case (Pascal Case) as Java or .NET Style
| {
"LocalName": "Thành phố Hồ Chí Minh",
"Name": "Ho Chi Minh city"
} | |
Request / Response | To be consistent, we will use | Parameter:
Response:
|
Action
Use nouns instead of verbs in endpoint paths
The action should be indicated by the HTTP request method that we're making. The most common methods include GET, POST, PUT, and DELETE that follow CRUD operation
GET retrieves resources.
POST submits new data to the server.
PUT updates existing data.
DELETE removes data.
Versioning
URI Path
https://www.example.com/api/v1/devices
https://api.example.com/v1/devicesRequest/Response Body Format
Property | Description |
|---|---|
| Placeholder message:
|
| Http Status response format |
| Response body for success data |
| Response body for error data. Can null or empty list. See Error object define below |
| Meta data of response. Pagination properties or ref will go here |
Data - Response body data
Serialized record
{
"Message": "Success Or Error Message",
"StatusCode": 201,
"Data": {},
"Errors": [],
"Meta": null
}Date time / Timestamp
Format description | Value | Example |
|---|---|---|
Format: ISO 8601-1:2019 format in UTC time |
|
|
Error Object
Property | Description |
|---|---|
| Property name or Error Code |
| Error Message |
| Multiple Error Messages |
Pagination
Request Parameters
Parameter |
|
|
|---|---|---|
|
| Request field for pagination. The Page that you wish to view |
|
| The total items that return in the response Default: 10 Minimum: 1 |
|
| Sorting field, Default sorting is get all items sort by Values:
|
|
| Used in default: true |
Examples: /{apiURl}?CurrentPage=2&ItemPerPage=50&OrderBy=CreatedTime&IsDescending=false
Response body
Meta Property
Field | Type | Description |
|---|---|---|
|
| Current page returned |
|
| Total pages by items per page |
|
| Total items number |
|
| Total items per page |
Response Status codes
Everything worked as expected, the server will send a response message confirming the action. | |
The request was rejected, usually caused by a missing parameter or invalid request. | |
No valid API key was provided or has expired. | |
The request was valid but failed. | |
The user does not have permission to make this request. | |
The request URL does not exist or Item / resource is not found | |
Something went wrong with the REDEX platform. |
Successful Responses
200 OK
The request succeeded. The result meaning of "success" depends on the HTTP method:
GET: The resource has been fetched and transmitted in the message body.HEAD: The representation headers are included in the response without any message body.PUTorPOSTorPATCH: The resource describing the result of the action is transmitted in the message body.TRACE: The message body contains the request message as received by the server.
201 Created
The request succeeded, and a new resource was created as a result. This is typically the response sent after POST requests, or some PUT requests.
Client error messages
400 Bad Request
The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
Use case:
Invalid request payload, mostly request fails validation.
401 Unauthorized
Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response.
Use cases:
Authorization failed.
Authorization token is missing.
403 Forbidden
The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server.
404 Not Found
The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well-known due to its frequent occurrence on the web.
Use cases:
API URL is not found.
Can be use for
403 Forbidden
422 Unprocessable Entity
The request was well-formed but was unable to be followed due to semantic errors.
Use cases:
Invalid request payload: passed the validation but fails on logic layer.
Server error responses
500 - Server errors
The server has encountered a situation it does not know how to handle.
Rate limit
Rate Limit Algorithm: Fixed Window
限流算法：固定窗口
In fixed window rate limiting, a fixed time window (e.g., one minute, one hour) is used to track the number of requests or actions allowed within that window. Requests exceeding the limit are either rejected or throttled until the window resets.
在固定窗口限流算法中，一个固定窗口的时间（例如，一分钟，一小时）被用于跟踪记录在窗口时间中被允许的请求或者操作的数量。当请求数量超过设定的限制值，请求将被拒绝或者限流，直到时间窗口被重置。
Rate Limiting Overview
Our API employs rate limiting to ensure fair usage and protect the performance and availability of the service. Combination of Global Policy and Operation Policy.
我们的接口应用了限流策略确，保接口的能够被合理调用，并且确保服务的性能和可用性。这一保证是通过全局策略和操作策略的组合来实现的。
Global Policy 全局策略
Rate Limit: 3000 requests per 5 minute(s)
限流：3000 请求/ 5 分钟
Renewal Period: 300 second(s)
重置时间：300 秒
Key: IP Address
限流键值：IP 地址
Increment Condition: Any Request
请求书递增条件：任何类型的请求
Summary
Operation | API | Number of calls | Renewable period (in Seconds/Minutes) | Counter Key | Increment Condition |
Global Policy | 3000 | 300sec(s) or 5min(s) | Ip Address | Any Request | |
Authentication/验证 | 10 | 60sec(s) or 1min(s) | ApiKey | Any Request | |
10 | 60sec(s) or 1min(s) | Refresh Token | Any Request | ||
Documents/文档 | 50 | 60sec(s) or 1min(s) | Business Account Id | Success Request | |
Device Applications/设备应用 | 50 | 60sec(s) or 1min(s) | Business Account Id | Success Request | |
60 | 60sec(s) or 1min(s) | Business Account Id | Any Request | ||
60 | 60sec(s) or 1min(s) | Business Account Id | Any Request | ||
Metadata/元数据 | 5 | 5sec(s) | Business Account Id | Any Request | |
Generation Data/发电数据 | 5 | 5sec(s) | Business Account Id | Any Request | |
5 | 5sec(s) | Business Account Id | Any Request | ||
5 | 5sec(s) | Business Account Id | Any Request | ||
5 | 5sec(s) | Business Account Id | Any Request | ||
Device Applications/设备应用 | [GET] Get Grouped Device Application's devices and inverters | 60 | 60sec(s) or 1min(s) | Business Account Id | Any Request |
Generation Data/发电数据 | 5 | 5sec(s) | Business Account Id | Any Request | |
Inventory REC Inventory | 60 | 60sec(s) or 1min(s) | Business Account Id | Any Request | |
Inventory REC Transaction History | 60 | 60sec(s) or 1min(s) | Business Account Id | Any Request | |
REC Applications | 60 | 60sec(s) or 1min(s) | Business Account Id | Any Request | |
Generation Data/发电数据 | 5 | 5sec(s) | Business Account Id | Any Request | |