GB/T 43960-2024Open application program interface requirements for cloud manufacturing service platform (English PDF)

3 Terms and definitions

The terms defined in GB/T 29826-2013 apply, together with three terms defined here.

3.1 open application program interface: the open application programming interface that a cloud manufacturing service platform offers to the outside.

3.2 application program interface for industrial application: the open application programming interface offered on a cloud manufacturing service platform to support the development and management of industrial applications.

3.3 application program interface for manufacturing resource/capability import: the open application programming interface offered on a cloud manufacturing service platform to support data transmission, resource management and identifier management when cloud manufacturing resources and capabilities are brought onto the platform.

5 Open interface model

5.1 General. The model architecture is shown in Figure 1 and holds two families of open interface: industrial application service interfaces, and manufacturing resource and capability access interfaces. Manufacturing resource and capability access shall comply with Clauses 6 to 8 of GB/T 39471-2020. Interface security shall comply with OWASP and with the relevant provisions of GB/T 39403-2020. Both families may use transport protocols such as HTTP and HTTPS and should follow the OpenAPI Specification, service level agreements and similar conventions.

5.2 Industrial application service interfaces are divided into industrial application development interfaces and industrial application management interfaces. The development interfaces cover data interfaces, model interfaces and micro-service interfaces, and shall make clear the data, models and micro-services that industrial application development calls. The management interfaces shall include application management interfaces and security interfaces, and shall provide interfaces for application deployment, monitoring management, identity authentication, access control and permission management.

5.3 Manufacturing resource and capability access interfaces are divided into access service interfaces and access management interfaces. The access service interfaces shall include device data interfaces, device control interfaces, system data interfaces and access security interfaces, and shall make clear the interfaces for data exchange between industrial equipment or enterprise information systems and the platform, for issuing device control commands, and for securing access. The access management interfaces shall include device management interfaces, edge management interfaces and identifier interfaces, providing for the management and identification of cloud manufacturing resources such as industrial equipment and edge gateways.

6 Interface types

6.1 The open interfaces of a cloud manufacturing service platform are mainly of seven kinds: data, model, micro-service, security, identifier, management and control. Examples are given in Annex A.

Each interface in Clause 6 is presented in a table with five fields: interface name, interface description, interface method, parameter description and return value. The parameter lists are stated as minimum sets, and each named parameter is given with its data type in the printed text.

6.2.1 Data interfaces. The data retrieval interface shall support queries on the state of a data resource; it uses POST, takes at least the data resource ID, enterprise ID, user ID and an authentication parameter, and returns data resource information such as data volume, data update time and data permissions. The data analysis interface shall support calling a data analysis task and obtaining its result; it uses POST, takes at least the enterprise ID, user ID, authentication parameter and data analysis task ID, and returns the analysis result.

6.2.2 Model interfaces. The model registration interface shall let models of different kinds be registered on the platform; it uses POST, takes at least the user ID, authentication parameter, model name, model description and model class, and returns whether registration succeeded. The model status query interface shall let the running state of models of different kinds be queried; it uses GET, takes at least the user ID, authentication parameter and model ID, and returns the running state data of the model.

6.2.3 Micro-service interfaces. The micro-service registration interface shall publish micro-service information; it uses POST, takes at least the user ID, authentication parameter, micro-service name, micro-service description and data centre address, and returns the micro-service information. The micro-service status query interface shall query the running state; it uses GET, takes at least the user ID, authentication parameter, micro-service ID, task ID and the user account that started the micro-service, and returns the running state data.

6.2.4 Application management interfaces. The application deployment and release interface shall support creating and releasing an application; it uses POST, takes at least the user ID, authentication parameter, application ID, application name and application version, and returns the application ID together with a release status value. The application health monitoring interface shall obtain the running state of an application; it uses GET, takes at least the user ID, authentication parameter and application ID, and returns whether the application is running normally.

6.2.5 Application security interfaces shall support identity authentication of application management users and the obtaining of access permissions. The application security authentication interface uses GET, takes at least the user ID, authentication parameter and application ID, and returns the authorisation status value of the application.

6.3 Manufacturing resource and capability access interfaces. The device status interface shall query the current state of a device, which is one of running, standby, fault or offline; it uses GET, takes at least the user ID, authentication parameter and device ID, and returns whether the call succeeded. The device data interface shall collect device running data and obtain the list of data points; it uses POST, takes at least the user ID, authentication parameter, gateway ID, device ID and a data key-value pair, and returns whether the call succeeded. The device control interface shall issue device control commands; it uses POST, takes at least the user ID, authentication parameter, device ID and the command content, and returns whether the command was sent and what the result of execution was.

The system data interfaces shall support the connection of enterprise information systems and data transmission between the platform and the connected system, and shall cover interfaces for exchange with ERP, PLM and MES systems; the worked example is a production material form saving interface, which uses POST, takes at least the user ID, authentication parameter and form name, and returns whether the call succeeded. The access security interfaces authenticate the identity of connected resources; the device security authentication interface uses POST, takes at least the user ID, authentication parameter, device ID and device certificate, and returns whether authentication succeeded.

The device management interfaces shall support creating, querying, grouping, editing, deleting, importing and exporting devices and managing device templates; the device query interface uses GET, takes at least the user ID, authentication parameter and device ID, and returns whether the call succeeded. The edge management interfaces shall support edge gateway management, cloud-edge coordination node management and edge application management; the edge gateway creation interface uses POST, takes at least the user ID, authentication parameter, gateway name, communication protocol code, communication protocol address and gateway type code, and returns whether the call succeeded. The identifier interfaces cover a device identifier saving interface and a gateway identifier saving interface, both using POST and both taking, in addition to the user ID and authentication parameter, the device or gateway ID, the identifier class ID, the identifier template version and the identifier template attributes.

7 Requirements for writing interfaces

7.1 Practicality. The data format shall use a cross-platform and general-purpose file format, for example JSON or ProtoBuf; XML and TXT may also be used as an aid during development. The data volume shall be allocated as needed.

7.2 Usability. Interface and parameter names shall be accurate, shall carry the necessary content and shall be easy to understand. For both successful and failed transmission, the interface shall give clear data status information and a return value. The interface shall be extensible so that functions can be adjusted or added.

7.3 Security. An agreed algorithm shall be used to validate and match the parameter values passed. When a user name and password are passed, a proper encryption algorithm shall be used for the data communication request, and domestic encryption algorithms are recommended. Interfaces shall be version controlled, the interface version shall be updated when the platform or the software and hardware are upgraded, and the status of new and old interface versions should be dealt with periodically.

8 Requirements for designing interfaces

8.1 General. Interface design shall keep parameter passing to a minimum and pass parameters according to the request. It shall avoid duplicate interfaces, raise interface reuse, cut the number of HTTP requests and improve program stability.

8.2 Data type conventions. The data type of each parameter shall be annotated, together with whether it may be empty and whether it is a default field. The data type of a parameter shall match the corresponding return data type; mismatched parameter fields readily cause data type parsing exceptions in the application.

8.3 Encoding conventions. The encoding of the interface shall be annotated during development, and UTF-8 should be used.

8.4 Request method. The request method shall be annotated when the interface is written; the usual methods are GET, POST, PUT and DELETE. GET is used for small amounts of data, and POST shall be used when the data volume exceeds 1024 bytes, to avoid failed or abnormal requests.

8.5 Call status returns. All interfaces shall use unified success and failure identifiers, unified error code information and the necessary prompt fields. 8.6 Security mechanism: the interface design shall use a signature verification mechanism and may support interface security verification. 8.7 Parameter description: the interface shall state the parameter name, whether it is mandatory, the data type and range, and whether a default parameter is passed.

9 Requirements for registering and calling interfaces

HTTPS is recommended, with POST and PUT used to submit data.

Interface definitions follow RFC 1945 (HTTP 1.0), RFC 2616 (HTTP 1.1), RFC 0959 (FTP), RFC 1866 (HTML) or RFC 4627 (JSON).

Interface calls shall be subject to identity verification and permission checking, call information shall be recorded, and the feedback result of a call shall be parsed correctly.

10 Packet format

10.1.1 Common parameters are listed in Table 19, which has four columns: parameter name, type, whether mandatory, and description. An application authorisation and authentication interface method may be used. The mandatory string parameter api_key is the key assigned to the user at registration for access to the service. The mandatory string parameter Timestamp is the timestamp of the request, in the date format of ISO 8601 and in UTC. The optional string parameter format is the return format, either XML or JSON, defaulting to JSON. The optional string parameter encoding is the encoding of the request packet, either UTF-8 or GBK, defaulting to UTF-8. The mandatory string parameter body_sig is the parameter signature, which shall be the signature of all parameter strings other than body_sig itself, including business-level parameters.

10.1.2 Business parameter conventions are listed in Table 20, which has three columns: parameter name, type and description. The integer parameter page_no is used by paged APIs to indicate the page number, defaulting to 1. The integer parameter page_size indicates how many records a page returns, with a default and an upper limit of 25. The integer parameter device_type is the terminal type.

10.2 Error response output format. The error response shall consist of the two attributes error_code and error_msg, describing the error code and the error message respectively.

10.3 Error codes are defined in Table 21, which has three columns: ErrorCode, ErrorMsg and Description. Code 200 is Success. Code 100100 is Error, an interface call failure. Code 100101 is failure to obtain the access token. Code 100102 is a missing mandatory parameter. Code 100103 is invalid conditional information, meaning no information meets the condition. Code 100201 is an invalid access key. Code 100202 is an invalid access token, expired or non-existent. Code 100203 is permission denied. Code 100301 is incorrect user information parameter. Code 100302 is incorrect app information parameter. Code 100404 is Not Found. Code 100501 is API unavailable. Code 100502 is an input parameter that is incorrect or absent. Code 100505 is an incorrect path parameter. Code 100507 is a missing input parameter.

Annex A Examples of open interfaces of a cloud manufacturing service platform (informative)

The annex prints paired samples of the JSON body sent on a call and the JSON returned on success and on failure. The industrial application service examples cover the data retrieval interface, the model registration interface, the micro-service registration interface, the application deployment and release interface, and the application security authentication interface.

The manufacturing resource and capability access examples cover the device status interface, the device control interface, the production material form saving interface, the device security authentication interface, the device query interface, the edge gateway creation interface and the device identifier saving interface.

In every sample the call body carries a user identifier and an access token at the top level and the interface-specific fields inside a data object, while the failure return carries a status field holding one of the error codes of Table 21 together with the matching message.