Common Data Service API Specifications¶
Common Data Service offers data providers a series of unified API specifications. Only APIs that have completed standardization according to the specifications can be registered as data sources for Common Data Service. For more information about how to register data sources, see Registering a Data Source.
Common Data Service supports registering APIs of the Metrics
, Accumulative Points
, Attributes
, and Records
types as data sources. The following describes the general specifications to be followed by all API types, and the special specifications to be followed by each API type.
General Specifications¶
All APIs of the Metrics
, Accumulative Points
, Attributes
, and Records
types need to follow the specifications below:
The response code for successful API calls is
0
.Common Data Service does not require authentication to call the data source APIs for data.
If historical, current, and future data are to be provided at the same time, use one of the following two options:
Use the
Metrics
APIs, which provide historical data, in conjunction with theAccumulative Points
APIs, which provide current and future data. Do not return current and future data through theMetrics
APIs unless they are used in a special future-data scenario such as planned production.Current and future data are provided through the
Metrics
APIs and there is no separateAccumulative Points
API.
In the
Metrics
andAccumulative Points
APIs, the time format specification for thetimeGroup
(aggregation time granularity) parameter is as follows.Time Granularity
Description
Time Format
Example
RAW
Raw Data
YYYY-MM-DD hh:mm:ss
2021-03-25 00:00:01
1m
1 Minute
YYYY-MM-DD hh:mm:ss
2021-03-25 00:01:00
5m
5 Minutes
YYYY-MM-DD hh:mm:ss
2021-03-25 00:05:00
10m
10 Minutes
YYYY-MM-DD hh:mm:ss
2021-03-25 00:10:00
15m
15 Minutes
YYYY-MM-DD hh:mm:ss
2021-03-25 00:15:00
30m
30 Minutes
YYYY-MM-DD hh:mm:ss
2021-03-25 00:30:00
H
Hour
YYYY-MM-DD hh:mm:ss
2021-03-25 01:00:00
D
Day
YYYY-MM-DD
2021-03-25
W
Week
YYYY-Wxx
2021-W12
M
Month
YYYY-MM
2021-03
Q
Quarter
YYYY-Qx
2021-Q1
Y
Year
YYYY
2021
T
Total
1970
1970
L
Latest
YYYY-MM-DD hh:mm:ss
2021-03-25 00:00:01
In the
Metrics
APIs, the specifications for the returned results vary according to thetimeGroup
(aggregation time granularity) parameter:If
timeGroup
isL
, users do not need to pass in thestartTime
andendTime
request parameters, and the data source API needs to return the latest time if the time of multiple requested metrics is inconsistent.If
timeGroup
is a time granularity other thanL
, users need to specify a time range in the request, and the data source API needs to return data in a left-closed and right-closed interval according to the granularity. For example, the Production metric supports the D, M, and Y aggregation granularity and the data to be returned in different scenarios are as follows:If the specified time range is 2021-01-01 00:00:00 to 2021-01-05 00:00:00 and
timeGroup
is D, the daily production from 2021-01-01 to 2021-01-05 is returned.If the specified time range is 2021-01-05 00:00:00 to 2021-02-05 00:00:00 and
timeGroup
is M, the monthly aggregated production from 2021-01-05 to 2021-01-31 and from 2021-02-01 to 2021-02-05 is returned respectively.If the specified time range is 2020-01-05 00:00:00 to 2021-02-05 00:00:00 and
timeGroup
is Y, the yearly aggregated production from 2020-01-05 to 2020-12-31 and from 2021-01-01 to 2021-02-05 is returned respectively.