diff --git a/MEC033_IoT.json b/MEC033_IoT.json new file mode 100644 index 0000000000000000000000000000000000000000..e49cc9f5ebf9e80366814afa5096eef0c923f4d2 --- /dev/null +++ b/MEC033_IoT.json @@ -0,0 +1,1327 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "ETSI GS MEC 033 IoT API", + "version": "3.1.1", + "description": "ETSI GS MEC 033 IoT API described using OpenAPI.", + "license": { + "name": "BSD-3-Clause", + "url": "https://forge.etsi.org/legal-matters" + }, + "contact": { + "name": "ETSI Forge", + "url": "https://forge.etsi.org/rep/mec/gs021-amsi-api", + "email": "cti_support@etsi.org" + } + }, + "externalDocs": { + "description": "ETSI GS MEC 033 IoT API, v3.3.1", + "url": "https://www.etsi.org/deliver/etsi_gs/MEC/001_099/033/03.01.01_60/gs_mec033v030101p.pdf" + }, + "servers": [ + { + "url": "https://localhost/amsi/v1", + "variables": {} + } + ], + "tags": [ + { + "name": "reg-dev", + "description": "registered_devices" + }, + { + "name": "reg-iot-plat", + "description": "registered_iot_platforms" + } + ], + "paths": { + "/registered_devices": { + "get": { + "summary": "Retrieve information about all devices with a valid traffic rule association - see clause 5.2.2.", + "description": "The GET method may be used by a service consumer to retrieve information about all devices with a valid traffic rule association. This method is typically used in the \"registered devices query\" procedure as described in clause 5.2.2.", + "operationId": "registereddevicesGET", + "tags": [ + "reg-dev" + ], + "parameters": [ + { + "name": "filter", + "in": "query", + "description": "Attribute-based filtering parameters according to ETSI GS MEC 009 [i.1]. The API producer shall support receiving the following filtering parameters as part of the URI query string: \"(eq,enabled,TRUE)\".\n", + "style": "form", + "explode": true, + "schema": { + "type": "string" + } + }, + { + "name": "fields", + "in": "query", + "description": "The list may contain one or more of the following attributes from the DeviceInfo data type:\n- deviceMetadata\n- gpsi\n- msisdn\n- deviceId\n- requestedMecTrafficRule\n- requestedIotPlatformId\n- requestedUserTransportId\n", + "style": "form", + "explode": true, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + } + ], + "responses": { + "200": { + "description": "Upon success, a response body containing the list of registered devices is returned. The response body shall contain a list of resources that match the attribute filter.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "items": { + "$ref": "#/components/schemas/DeviceInfo" + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "404": { + "$ref": "#/components/responses/404" + } + } + }, + "post": { + "summary": "Register a new device - see clause 5.2.3.", + "description": "The POST method may be used by a service consumer to register a new device. This method is typically used in the \"device registration\" procedure as described in clause 5.2.3.", + "operationId": "registereddevicesPOST", + "tags": [ + "reg-dev" + ], + "requestBody": { + "description": "Payload body in the request contains the information associated to the IoT device to be registered.", + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "DeviceInfo": { + "$ref": "#/components/schemas/DeviceInfo" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Upon success, the HTTP response shall include a \"Location\" HTTP header that contains the resource URI of the registered device.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "DeviceInfo": { + "$ref": "#/components/schemas/DeviceInfo" + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "404": { + "$ref": "#/components/responses/404" + } + } + } + }, + "/registered_devices/{registeredDeviceId}": { + "get": { + "summary": "Retrieve information about a device - see clause 5.2.4.", + "description": "The GET method may be used by a service consumer to retrieve information about a device. This method is typically used in the \"device registration query\" procedure as described in clause 5.2.4.", + "operationId": "registereddevicesByIdGET", + "tags": [ + "reg-dev" + ], + "parameters": [ + { + "name": "registeredDeviceId", + "in": "path", + "required": true, + "description": "The unique identifier of the registered device.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Upon success, a response body containing information about the registered device is returned.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "DeviceInfo": { + "$ref": "#/components/schemas/DeviceInfo" + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "404": { + "$ref": "#/components/responses/404" + } + } + }, + "put": { + "summary": "Update information about a device including its association to a valid traffic rule - see clauses 5.2.5 and 5.4.3.", + "description": "The PUT method may be used by a service consumer to update a device registration including its association to a valid traffic rule. This method is typically used in the \"device registration update\" procedure as described in clause 5.2.5 and in the \"user transport assignment\" procedure as described in clause 5.4.3.", + "operationId": "registereddevicesByIdPUT", + "tags": [ + "reg-dev" + ], + "parameters": [ + { + "name": "registeredDeviceId", + "in": "path", + "required": true, + "description": "The unique identifier of the registered device.", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "One or more updated attributes that are allowed to be changed are included in the DeviceInfo data structure in the payload body of the request. .", + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "DeviceInfo": { + "$ref": "#/components/schemas/DeviceInfo" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Upon success, a response body containing data type describing the updated DeviceInfo is returned.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "DeviceInfo": { + "$ref": "#/components/schemas/DeviceInfo" + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "412": { + "$ref": "#/components/responses/412" + } + } + }, + "delete": { + "summary": "Deregister a device - see clause 5.2.6.", + "description": "The DELETE method may be used by a service consumer to deregister a device. This method is typically used in the \"device deregistration\" procedure as described in clause 5.2.6.", + "operationId": "registereddevicesByIdDELETE", + "tags": [ + "reg-dev" + ], + "parameters": [ + { + "name": "registeredDeviceId", + "in": "path", + "required": true, + "description": "The unique identifier of the registered device.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "$ref": "#/components/responses/204" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "404": { + "$ref": "#/components/responses/404" + } + } + } + }, + "/registered_iot_platforms": { + "get": { + "summary": "Retrieve information about all IoT platforms - see clause 5.3.2.", + "description": "The GET method may be used by an authorized service consumer to retrieve the information of all currently registered IoT platforms. This method is typically used in the \"registered IoT platforms query\" procedure as described in clause 5.3.2.", + "operationId": "registerediotplatformsGET", + "tags": [ + "reg-iot-plat" + ], + "parameters": [ + { + "name": "fields", + "in": "query", + "description": "The list shall contain the following attributes from the IotPlatformInfo data type:\n- iotPlatformId\n- enabled\n", + "style": "form", + "explode": true, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + } + ], + "responses": { + "200": { + "description": "Upon success, a response body containing the list of registered IoT platforms is returned.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IotPlatformInfo" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "404": { + "$ref": "#/components/responses/404" + } + } + }, + "post": { + "summary": "Register a IoT platform - see clause 5.3.4.", + "description": "The POST method may be used by a service consumer to register a new IoT platform. This method is typically used in the \"IoT platform registration\" procedure as described in clause 5.3.4.", + "operationId": "registerediotplatformsPOST", + "tags": [ + "reg-iot-plat" + ], + "requestBody": { + "description": "Payload body in the request contains the information associated to the IoT platform to be registered.", + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "IoTPlatformInfo": { + "$ref": "#/components/schemas/IotPlatformInfo" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Upon success, the HTTP response shall include a \"Location\" HTTP header that contains the resource URI of the registered IoT platform.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "IoTPlatformInfo": { + "$ref": "#/components/schemas/IotPlatformInfo" + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "404": { + "$ref": "#/components/responses/404" + } + } + } + }, + "/registered_iot_platforms/{registeredIotPlatformId}": { + "get": { + "summary": "Discover native services and obtain information about user transports provided by a IoT platform - see clauses 5.3.3 and 5.4.2.", + "description": "The GET method may be used by a service consumer to obtain information about a IoT platform. This method is typically used in the \"IoT platform information request\" procedure as described in clause 5.3.3 and in the \"user transport query\" procedure as described in clause 5.4.2. ", + "operationId": "registerediotplatformsByIdGET", + "tags": [ + "reg-iot-plat" + ], + "parameters": [ + { + "name": "registeredIotPlatformId", + "in": "path", + "required": true, + "description": "The unique identifier of the registered IoT platform.", + "schema": { + "type": "string" + } + }, + { + "name": "fields", + "in": "query", + "description": "The list may contain one or more of the following attributes from the IotPlatformInfo data type:\n- userTransportInfo\n- customServiceTransportInfo\n", + "style": "form", + "explode": true, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + } + ], + "responses": { + "200": { + "description": "Upon success, a response body containing information about the registered IoT platform is returned.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "IotPlatformInfo": { + "$ref": "#/components/schemas/IotPlatformInfo" + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "404": { + "$ref": "#/components/responses/404" + } + } + }, + "put": { + "summary": "Update information about a IoT platform - see clause 5.3.5.", + "description": "The PUT method may be used by a service consumer to update a IoT platform registration. This method is typically used in the \"IoT platform update\" procedure as described in clause 5.3.5.", + "operationId": "registerediotplatformsByIdPUT", + "tags": [ + "reg-iot-plat" + ], + "parameters": [ + { + "name": "registeredIotPlatformId", + "in": "path", + "required": true, + "description": "The unique identifier of the registered IoT platform.", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "One or more updated attributes that are allowed to be changed are included in the IotPlatformInfo data structure in the payload body of the request. .", + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "IotPlatformInfo": { + "$ref": "#/components/schemas/IotPlatformInfo" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Upon success, a response body containing data type describing the updated IotPlatformInfo is returned.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "IotPlatformInfo": { + "$ref": "#/components/schemas/IotPlatformInfo" + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "412": { + "$ref": "#/components/responses/412" + } + } + }, + "delete": { + "summary": "Deregister a IoT platform - see clause 5.3.6.", + "description": "The DELETE method may be used by a service consumer to deregister a IoT platform. This method is typically used in the \"IoT platform deregistration\" procedure as described in clause 5.3.6.", + "operationId": "registerediotplatformsByIdDELETE", + "tags": [ + "reg-iot-plat" + ], + "parameters": [ + { + "name": "registeredIotPlatformId", + "in": "path", + "required": true, + "description": "The unique identifier of the registered IoT platform.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "$ref": "#/components/responses/204" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "404": { + "$ref": "#/components/responses/404" + } + } + } + } + }, + "components": { + "schemas": { + "ProblemDetails": { + "type": "object", + "properties": { + "type": { + "type": "string", + "format": "uri", + "description": "A URI reference according to IETF RFC 3986 that identifies the problem type" + }, + "title": { + "type": "string", + "description": "A short, human-readable summary of the problem type" + }, + "status": { + "type": "integer", + "format": "uint32", + "description": "The HTTP status code for this occurrence of the problem" + }, + "detail": { + "type": "string", + "description": "A human-readable explanation specific to this occurrence of the problem" + }, + "instance": { + "type": "string", + "format": "uri", + "description": "A URI reference that identifies the specific occurrence of the problem" + } + } + }, + "DeviceInfo": { + "title": "DeviceInfo", + "type": "object", + "properties": { + "deviceAuthenticationInfo": { + "description": "Information needed for secondary authentication of the IoT device to the data network - see ETSI TS 129 561 [i.4] and ETSI TS 129 061 [i.5] for 5G and LTE procedures, respectively. This attribute is implementation dependent and should be logically linked to the identifiers of the IoT device listed hereafter.", + "type": "string" + }, + "deviceMetadata": { + "description": "Additional information about the IoT device. This attribute is implementation dependent and may be expressed as an array of keyvalue pairs. ", + "type": "string" + }, + "gpsi": { + "description": "GPSI of the IoT device if 5G-enabled (see note 1).", + "type": "string" + }, + "pei": { + "description": "PEI of the IoT device if 5G-enabled (see note 1).", + "type": "string" + }, + "supi": { + "description": "SUPI of the IoT device if 5G-enabled (see note 1).", + "type": "string" + }, + "msisdn": { + "description": "MSISDN of the IoT device if LTE-enabled (see note 1).", + "type": "string" + }, + "imei": { + "description": "IMEI of the IoT device if LTE-enabled (see note 1).", + "type": "string" + }, + "imsi": { + "description": "IMSI of the IoT device if LTE-enabled (see note 1).", + "type": "string" + }, + "iccid": { + "description": "ICCID of the IoT device (see note 1).", + "type": "string" + }, + "deviceId": { + "description": "Human-readable identifier of the IoT device.", + "type": "string" + }, + "requestedMecTrafficRule": { + "description": "MEC traffic rules the IoT device is requested to be associated to (see note 2). The data type definition is as per ETSI GS MEC 010-2 [i.6].", + "type": "array", + "items": { + "$ref": "#/components/schemas/TrafficRuleDescriptor" + } + }, + "requestedIotPlatformId": { + "description": "IoT platform to which the IoT device is requested to be associated to (see note 2).", + "type": "string" + }, + "requestedUserTransportId": { + "description": "User transport to which the IoT device is requested to be associated to (see note 2).", + "type": "string" + }, + "deviceSpecificMessageFormats": { + "$ref": "#/components/schemas/DeviceSpecificMessageFormats" + }, + "downlinkInfo": { + "$ref": "#/components/schemas/DownlinkInfo" + }, + "clientCertificate": { + "description": "Client-side SSL/TLS certificate to be used by the MEC IoTS to interact with the user transport provided by the associated IoT platform in case the MEC IoTS acts on behalf of the IoT device.", + "type": "string" + }, + "enabled": { + "description": "Indication whether the IoT device has a valid associated traffic rule (TRUE) or not (FALSE). See note 3.", + "type": "boolean" + } + }, + "required": [ + "deviceAuthenticationInfo", + "deviceId", + "enabled" + ], + "description": "NOTE 1: At least one attribute among gpsi, pei, supi, msisdn, imei, imsi, and iccid should be provided. Sufficient security\n measures shall be put in place when any attribute among PEI, SUPI, IMEI, and IMSI is disclosed over the API.\nNOTE 2: Until a valid traffic rule is not provided, the device will not be able to use the IoTS. A valid traffic rule is provided\n by one of the following options:\n • the requestedMecTrafficRule attribute;\n • the requestedIotPlatformId attribute when the IoT platform offers only one user transport;\n • the combination of requestedIotPlatformId and requestedUserTransportId.\nNOTE 3: Enabled is a pseudo-attribute which needs to be maintained by the IoTS based on the presence or not of a valid\n traffic rule associated to the device. It cannot be set directly by the service consumer. \n" + }, + "IotPlatformInfo": { + "title": "IotPlatformInfo", + "type": "object", + "properties": { + "iotPlatformId": { + "description": "Identifier of the IoT platform.", + "type": "string" + }, + "userTransportInfo": { + "description": "Information about the user transport(s) provided by the IoT platform.", + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/components/schemas/MBTransportInfo" + } + }, + "customServicesTransportInfo": { + "description": "Transport enabling access to vendor-specific services provided by the IoT platform. The data type definition is as per ETSI GS MEC 011 [i.2].", + "type": "array", + "minItems": 0, + "items": { + "$ref": "#/components/schemas/TransportInfo" + } + }, + "enabled": { + "description": "Indication whether the IoT platform is capable of providing user transports and vendor-specific services (TRUE) or not (FALSE).", + "type": "boolean" + } + }, + "required": [ + "iotPlatformId", + "userTransportInfo", + "enabled" + ] + }, + "MBTransportInfo": { + "title": "MBTransportInfo", + "type": "object", + "properties": { + "id": { + "description": "The identifier of this transport as per ETSI GS MEC 011 [i.2].", + "type": "string" + }, + "name": { + "description": "The name of this transport as per ETSI GS MEC 011 [i.2].", + "type": "string" + }, + "description": { + "description": "Human-readable description of this transport as per ETSI GS MEC 011 [i.2].", + "type": "string" + }, + "type": { + "description'": "Type of the transport. The attribute shall be set to \"MB_TOPIC_BASED.\"", + "$ref": "#/components/schemas/TransportType" + }, + "protocol": { + "description": "The name of the protocol used. Being the transport of MB_TOPIC_BASED type, this attribute should be typically set to \"MQTT\" or \"AMQP.\"", + "type": "string" + }, + "version": { + "description": "The version of the protocol used as per ETSI GS MEC 011 [i.2].", + "type": "string" + }, + "endpoint": { + "description'": "Information about the endpoint to access the transport as per ETSI GS MEC 011 [i.2].", + "$ref": "#/components/schemas/EndPointInfo" + }, + "security": { + "description": "Information about the security used by the transport as per ETSI GS MEC 011 [i.2].", + "$ref": "#/components/schemas/SecurityInfo" + }, + "implSpecificInfo": { + "$ref": "#/components/schemas/ImplSpecificInfo" + } + }, + "required": [ + "id", + "name", + "type", + "protocol", + "version", + "endpoint", + "security", + "implSpecificInfo" + ] + }, + "EventMsg": { + "title": "EventMsg", + "type": "object", + "properties": { + "eventTopic": { + "description": "Topic where the message containing application-specific information should be published. ", + "type": "string" + }, + "selectedSerializer": { + "description'": "Type of serializer to be used for the topic as per ETSI GS MEC 011 [i.2].", + "$ref": "#/components/schemas/SerializerType" + }, + "includeDeviceAddr": { + "description": "Indication whether to include the IP address of the IoT device (TRUE) or not (FALSE).", + "type": "boolean" + }, + "includeDeviceMetadata": { + "description": "Indication whether to include the metadata about the IoT device (TRUE) or not (FALSE).", + "type": "boolean" + }, + "includePei": { + "description": "Indication whether to include the PEI of the IoT device (TRUE) or not (FALSE).", + "type": "boolean" + }, + "includeSupi": { + "description": "Indication whether to include the SUPI of the IoT device (TRUE) or not (FALSE).", + "type": "boolean" + }, + "includeImei": { + "description": "Indication whether to include the IMEI of the IoT device (TRUE) or not (FALSE).", + "type": "boolean" + }, + "includeImsi": { + "description": "Indication whether to include the IMSI of the IoT device (TRUE) or not (FALSE).", + "type": "boolean" + }, + "includeIccid": { + "description": "Indication whether to include the ICCID of the IoT device (TRUE) or not (FALSE).", + "type": "boolean" + }, + "includeDeviceId": { + "description": "Indication whether to include the human-readable identified of the IoT device (TRUE) or not (FALSE).", + "type": "boolean" + } + }, + "required": [ + "eventTopic", + "selectedSerializer" + ] + }, + "UplinkMsg": { + "title": "UplinkMsg", + "type": "object", + "properties": { + "uplinkTopic": { + "description": "Topic where the message containing the data generated by the IoT device(s) should be published, in order to be consumed by the end IoT application(s).", + "type": "string" + }, + "selectedSerializer": { + "description'": "Type of serializer to be used for the topic as per ETSI GS MEC 011 [i.2].", + "$ref": "#/components/schemas/SerializerType" + }, + "includeDevicePort": { + "description": "Indication whether to include the UDP port of the remote IoT device (TRUE) or not (FALSE).", + "type": "boolean" + }, + "includeDeviceAddr": { + "description": "Indication whether to include the IP address of the IoT device (TRUE) or not (FALSE).", + "type": "boolean" + }, + "includeDeviceMetadata": { + "description": "Indication whether to include the metadata about the IoT device (TRUE) or not (FALSE).", + "type": "boolean" + }, + "includePei": { + "description": "Indication whether to include the PEI of the IoT device (TRUE) or not (FALSE).", + "type": "boolean" + }, + "includeSupi": { + "description": "Indication whether to include the SUPI of the IoT device (TRUE) or not (FALSE).", + "type": "boolean" + }, + "includeImei": { + "description": "Indication whether to include the IMEI of the IoT device (TRUE) or not (FALSE).", + "type": "boolean" + }, + "includeImsi": { + "description": "Indication whether to include the IMSI of the IoT device (TRUE) or not (FALSE).", + "type": "boolean" + }, + "includeIccid": { + "description": "Indication whether to include the ICCID of the IoT device (TRUE) or not (FALSE).", + "type": "boolean" + }, + "includeDeviceId": { + "description": "Indication whether to include the human-readable identified of the IoT device (TRUE) or not (FALSE).", + "type": "boolean" + } + }, + "required": [ + "uplinkTopic", + "selectedSerializer" + ] + }, + "DeviceSpecificMessageFormats": { + "description": "Format of the messages to be published by the MEC IoTS on the user transport provided by the associated IoT platform in case the MEC IoTS acts on behalf of the IoT device.", + "type": "object", + "properties": { + "eventMsgFormat": { + "description'": "Event message format configuration.", + "$ref": "#/components/schemas/EventMsg" + }, + "uplinkMsgFormat": { + "description'": "Uplink message format configuration.", + "$ref": "#/components/schemas/UplinkMsg" + } + } + }, + "DownlinkInfo": { + "description": "Downlink communication configuration of the user transport provided by the associated IoT platform in case the MEC IoTS acts on behalf of the IoT device.", + "type": "object", + "properties": { + "downlinkTopic": { + "description": "Topic associated to the IoT device. This topic should be used by an end IoT application to send downlink data to the IoT device.", + "type": "string" + }, + "devicePort": { + "description": "UDP port to be used by the MEC IoTS for the outgoing downlink packets towards the IoT device. In case a default value is used, this attribute is optional.", + "type": "integer" + } + } + }, + "ImplSpecificInfo": { + "description": "Additional implementation specific details of the transport.", + "type": "object", + "properties": { + "eventTopics": { + "description": "Topics used to publish events related to the established session between the IoT device(s) and the end IoT application(s) on the user transport.", + "type": "array", + "minItems": 0, + "items": { + "type": "string" + } + }, + "uplinkTopics": { + "description": "Topics used to publish data generated by the IoT device(s) on the user transport, in order to be consumed by the end IoT application(s).", + "type": "array", + "items": { + "type": "string" + } + }, + "downlinkTopics": { + "description": "Topics used to publish data generated by the IoT applications(s) on the user transport, in order to be consumed by the end IoT device(s).", + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "SerializerType": { + "type": "string", + "description": "The enumeration SerializerType represents types of serializers.", + "enum": [ + "JSON", + "XML", + "PROTOBUF3" + ] + }, + "TransportInfo": { + "title": "TransportInfo", + "type": "object", + "properties": { + "id": { + "description": "The identifier of this transport.", + "type": "string" + }, + "name": { + "description": "The name of this transport.", + "type": "string" + }, + "description": { + "description": "Human-readable description of this transport.", + "type": "string" + }, + "type": { + "description'": "Type of the transport.", + "$ref": "#/components/schemas/TransportType" + }, + "protocol": { + "description": "The name of the protocol used. Shall be set to \"HTTP\" for a REST API.", + "type": "string" + }, + "version": { + "description": "The version of the protocol used.", + "type": "string" + }, + "endpoint": { + "description'": "Information about the endpoint to access the transport.", + "$ref": "#/components/schemas/EndPointInfo" + }, + "security": { + "description'": "Information about the security used by the transport.", + "$ref": "#/components/schemas/SecurityInfo" + }, + "implSpecificInfo": { + "description": "Additional implementation specific details of the transport.", + "type": "string" + } + }, + "required": [ + "id", + "name", + "type", + "protocol", + "version", + "endpoint", + "security" + ] + }, + "TransportType": { + "type": "string", + "enum": [ + "REST_HTTP", + "MB_TOPIC_BASED", + "MB_ROUTING", + "MB_PUBSUB", + "RPC", + "RPC_STREAMING", + "WEBSOCKET" + ], + "description": "Enumeration representing types of transports." + }, + "EndPointInfo": { + "title": "EndPointInfo", + "type": "object", + "properties": { + "uris": { + "description": "Entry point information of the service as string, formatted according to URI syntax (see IETF RFC 3986 [8]). Shall be used for REST APIs. See note.", + "type": "array", + "items": { + "type": "string" + } + }, + "fqdn": { + "description": "Fully Qualified Domain Name of the service. See note.", + "type": "array", + "items": { + "type": "string" + } + }, + "addresses": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Addresses" + } + }, + "alternative": { + "description": "Entry point information of the service in a format defined by an implementation, or in an external specification. See note.", + "type": "string" + } + }, + "description": "NOTE: Exactly one of \"uris\", \"fqdn\", \"addresses\" or \"alternative\" shall be present. \n" + }, + "SecurityInfo": { + "type": "object", + "properties": { + "oAuth2Info": { + "$ref": "#/components/schemas/OAuth2Info" + }, + "extensions": { + "description": "Extensions for alternative transport mechanisms. These extensions depend on the actual transport and are out of scope of the present document. For instance, such extensions may be used to signal the necessary parameters for the client to use TLS-based authorization defined for alternative transports (see ETSI GS MEC 009 [5] for more information).\n", + "type": "string" + } + } + }, + "Addresses": { + "description": "Entry point information of the service as one or more pairs of IP address and port. See note.", + "type": "object", + "properties": { + "host": { + "description": "Host portion of the address.", + "type": "string" + }, + "port": { + "description": "Port portion of the address.", + "type": "integer" + } + }, + "required": [ + "host", + "port" + ] + }, + "OAuth2Info": { + "description": "Parameters related to use of OAuth 2.0. Shall be present in case OAuth 2.0 (see IETF RFC 6749 [13]) is supported to secure the provision of the service over the transport.", + "type": "object", + "properties": { + "grantTypes": { + "type": "array", + "description": "List of supported OAuth 2.0 grant types.\nEach entry shall be one of the following permitted values:\n- OAUTH2_AUTHORIZATION_CODE: Authorization code grant type\n- OAUTH2_IMPLICIT_GRANT: Implicit grant type\n- OAUTH2_RESOURCE_OWNER: Resource owner password credentials grant type\n- OAUTH2_CLIENT_CREDENTIALS: Client credentials grant type\nOnly the value \"OAUTH2_CLIENT_CREDENTIALS\" is supported in the present document.\n", + "items": { + "type": "string", + "enum": [ + "OAUTH2_AUTHORIZATION_CODE", + "OAUTH2_IMPLICIT_GRANT", + "OAUTH2_RESOURCE_OWNER", + "OAUTH2_CLIENT_CREDENTIALS" + ] + } + }, + "tokenEndpoint": { + "description": "The token endpoint. Shall be present unless the grant type is OAUTH2_IMPLICIT_GRANT.", + "type": "string", + "format": "uri" + } + }, + "required": [ + "grantTypes" + ] + }, + "TrafficRuleDescriptor": { + "title": "TrafficRuleDescriptor", + "type": "object", + "properties": { + "trafficRuleId": { + "description": "Identifies the traffic rule.", + "type": "string" + }, + "filterType": { + "type": "string", + "description": "Definition of filter type: per FLOW or PACKET\n\nIf it is per FLOW, the filter matches upstream (e.g. UE->EPC) packets and downstream (e.g. EPC->UE) packets are handled by the same context.\n", + "enum": [ + "per FLOW", + "per PACKET" + ] + }, + "priority": { + "description": "Priority of this traffic rule within the range 0 to 255. If traffic rule conflicts, the one with higher priority take precedence. See note 1.", + "type": "integer" + }, + "trafficFilter": { + "description": "The filter used to identify specific flow/packets that need to be handled by the MEC host.", + "type": "array", + "items": { + "$ref": "#/components/schemas/TrafficFilter" + } + }, + "action": { + "type": "string", + "description": "Identifies the action of the MEC host data plane, when a packet matches the trafficFilter, the example actions include:\nDROP,\nFORWARD_DECAPSULATED,\nFORWARD_ENCAPSULATED,\nPASSTHROUGH,\nDUPLICATE_DECAPSULATED,\nDUPLICATE_ENCAPSULATED ", + "enum": [ + "SEE_DESCRIPTION" + ] + }, + "dstInterface": { + "description'": "Describes the destination interface information. If the action is FORWARD_DECAPSULATED, FORWARD_ENCAPSULATED or PASSTHROUGH, one value shall be provided. If the action is DUPLICATE_DECAPSULATED or DUPLICATE_ENCAPSULATED, two values shall be provided. See note 2. If the action is DROP, no value shall be provided.", + "$ref": "#/components/schemas/InterfaceDescriptor" + } + }, + "required": [ + "trafficRuleId", + "filterType", + "priority", + "trafficFilter", + "action" + ], + "description": "NOTE 1: Value indicates the priority in descending order, i.e. with 0 as the highest priority and 255 as the lowest\n priority.\nNOTE 2: Some applications (like inline/tap) require two interfaces. The first interface in the case of inline/tap is on the\n client (e.g. UE) side and the second on the core network (e.g. EPC) side. \n" + }, + "TrafficFilter": { + "title": "TrafficFilter", + "type": "object", + "properties": { + "srcAddress": { + "description": "An IP address or a range of IP addresses.\nFor IPv4, the IP address could be an IP address plus mask, or an individual IP address, or a range of IP addresses.\nFor IPv6, the IP address could be an IP prefix, or a range of IP prefixes.", + "type": "array", + "items": { + "type": "string" + } + }, + "dstAddress": { + "description": "An IP address or a range of IP addresses.\nFor IPv4, the IP address could be an IP address plus mask, or an individual IP address, or a range of IP addresses.\nFor IPv6, the IP address could be an IP prefix, or a range of IP prefixes.", + "type": "array", + "items": { + "type": "string" + } + }, + "srcPort": { + "description": "A port or a range of ports.", + "type": "array", + "items": { + "type": "string" + } + }, + "dstPort": { + "description": "A port or a range of ports.", + "type": "array", + "items": { + "type": "string" + } + }, + "protocol": { + "description": "Specify the protocol of the traffic filter.", + "type": "array", + "items": { + "type": "string" + } + }, + "tag": { + "description": "Used for tag based traffic rule.", + "type": "array", + "items": { + "type": "string" + } + }, + "uri": { + "description": "An URI label, in application layer, i.e. in HTTP message, is used to filter the traffic.", + "type": "array", + "items": { + "type": "string" + } + }, + "packetLabel": { + "description": "A customized packet label in network layer, as defined by the owner of the MEC platform, is used to filter the traffic.", + "type": "array", + "items": { + "type": "string" + } + }, + "srcTunnelAddress": { + "description": "Used for GTP tunnel based traffic rule.", + "type": "array", + "items": { + "type": "string" + } + }, + "tgtTunnelAddress": { + "description": "Used for GTP tunnel based traffic rule.", + "type": "array", + "items": { + "type": "string" + } + }, + "srcTunnelPort": { + "description": "Used for GTP tunnel based traffic rule.", + "type": "array", + "items": { + "type": "string" + } + }, + "dstTunnelPort": { + "description": "Used for GTP tunnel based traffic rule.", + "type": "array", + "items": { + "type": "string" + } + }, + "qCI": { + "description": "Used to match all packets that have the same QCI.", + "type": "integer" + }, + "dSCP": { + "description": "Used to match all IPv4 packets that have the same DSCP.", + "type": "integer" + }, + "tC": { + "description": "Used to match all IPv6 packets that have the same TC.", + "type": "integer" + } + } + }, + "InterfaceDescriptor": { + "title": "InterfaceDescriptor", + "type": "object", + "properties": { + "interfaceType": { + "type": "string", + "description": "Type of interface: TUNNEL, MAC, IP, etc.", + "enum": [ + "TUNNEL", + "MAC", + "IP" + ] + }, + "tunnelInfo": { + "description'": "Included only if the destination address type is tunnel.", + "$ref": "#/components/schemas/TunnelInfo" + }, + "srcMACAddress": { + "description": "If the interface type is MAC, the source address identifies the MAC address of the interface.", + "type": "string" + }, + "dstMACAddress": { + "description": "If the interface type is MAC, the destination address identifies the MAC address of the destination. Only used for dstInterface.", + "type": "string" + }, + "dstIPAddress": { + "description": "If the interface type is IP, the destination address identifies the IP address of the destination. Only used for dstInterface.", + "type": "string" + } + }, + "required": [ + "interfaceType" + ] + }, + "TunnelInfo": { + "title": "TunnelInfo", + "type": "object", + "properties": { + "tunnelType": { + "type": "string", + "description": "Type of tunnel: GTP-U, GRE, etc.", + "enum": [ + "GTP-U", + "GRE" + ] + }, + "tunnelDstAddress": { + "description": "Destination address of the tunnel.", + "type": "string" + }, + "tunnelSrcAddress": { + "description": "Source address of the tunnel.", + "type": "string" + }, + "tunnelSpecificData": { + "description": "Parameters specific to the tunnel.", + "type": "string" + } + }, + "required": [ + "tunnelType", + "tunnelDstAddress", + "tunnelSrcAddress" + ] + } + }, + "responses": { + "200": { + "description": "OK" + }, + "204": { + "description": "No Content" + }, + "400": { + "description": "Bad Request: used to indicate that incorrect parameters were passed to the request.", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ProblemDetails" + } + } + } + }, + "403": { + "description": "Forbidden: operation is not allowed given the current status of the resource.", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ProblemDetails" + } + } + } + }, + "404": { + "description": "Not Found: used when a client provided a URI that cannot be mapped to a valid resource URI.", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ProblemDetails" + } + } + } + }, + "412": { + "description": "Precondition failed: used when a condition has failed during conditional requests, e.g. when using ETags to avoid write conflicts when using PUT", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ProblemDetails" + } + } + } + } + } + } +} \ No newline at end of file diff --git a/MEC033_IoT.yaml b/MEC033_IoT.yaml new file mode 100644 index 0000000000000000000000000000000000000000..409ed07427e9dadaf139f6cf41f188d582908fed --- /dev/null +++ b/MEC033_IoT.yaml @@ -0,0 +1,998 @@ +openapi: 3.1.0 +info: + title: ETSI GS MEC 033 IoT API + version: '3.1.1' + description: ETSI GS MEC 033 IoT API described using OpenAPI. + license: + name: BSD-3-Clause + url: 'https://forge.etsi.org/legal-matters' + contact: + name: ETSI Forge + url: https://forge.etsi.org/rep/mec/gs021-amsi-api + email: cti_support@etsi.org +externalDocs: + description: ETSI GS MEC 033 IoT API, v3.3.1 + url: https://www.etsi.org/deliver/etsi_gs/MEC/001_099/033/03.01.01_60/gs_mec033v030101p.pdf +servers: +- url: https://localhost/amsi/v1 + variables: {} + +tags: +- name: reg-dev + description: registered_devices +- name: reg-iot-plat + description: registered_iot_platforms + +paths: + /registered_devices: + get: + summary: Retrieve information about all devices with a valid traffic rule association - see clause 5.2.2. + description: The GET method may be used by a service consumer to retrieve information about all devices with a valid traffic rule association. This method is typically used in the "registered devices query" procedure as described in clause 5.2.2. + operationId: registereddevicesGET + tags: + - reg-dev + parameters: + - name: filter + in: query + description: | + Attribute-based filtering parameters according to ETSI GS MEC 009 [i.1]. The API producer shall support receiving the following filtering parameters as part of the URI query string: "(eq,enabled,TRUE)". + style: form + explode: true + schema: + type: string + + - name: fields + in: query + description: | + The list may contain one or more of the following attributes from the DeviceInfo data type: + - deviceMetadata + - gpsi + - msisdn + - deviceId + - requestedMecTrafficRule + - requestedIotPlatformId + - requestedUserTransportId + style: form + explode: true + schema: + type: array + items: + type: string + responses: + '200': + description: Upon success, a response body containing the list of registered devices is returned. The response body shall contain a list of resources that match the attribute filter. + content: + application/json: + schema: + type: object + properties: + items: + $ref: '#/components/schemas/DeviceInfo' + '400': + $ref: '#/components/responses/400' + '404': + $ref: '#/components/responses/404' + '403': + $ref: '#/components/responses/403' + post: + summary: "Register a new device - see clause\_5.2.3." + description: The POST method may be used by a service consumer to register a new device. This method is typically used in the "device registration" procedure as described in clause 5.2.3. + operationId: registereddevicesPOST + tags: + - reg-dev + requestBody: + description: Payload body in the request contains the information associated to the IoT device to be registered. + required: true + content: + application/json: + schema: + type: object + properties: + DeviceInfo: + $ref: '#/components/schemas/DeviceInfo' + responses: + '201': + description: Upon success, the HTTP response shall include a "Location" HTTP header that contains the resource URI of the registered device. + content: + application/json: + schema: + type: object + properties: + DeviceInfo: + $ref: '#/components/schemas/DeviceInfo' + '400': + $ref: '#/components/responses/400' + '404': + $ref: '#/components/responses/404' + '403': + $ref: '#/components/responses/403' + /registered_devices/{registeredDeviceId}: + get: + summary: Retrieve information about a device - see clause 5.2.4. + description: The GET method may be used by a service consumer to retrieve information about a device. This method is typically used in the "device registration query" procedure as described in clause 5.2.4. + operationId: registereddevicesByIdGET + tags: + - reg-dev + parameters: + - name: registeredDeviceId + in: path + required: true + description: The unique identifier of the registered device. + schema: + type: string + responses: + '200': + description: Upon success, a response body containing information about the registered device is returned. + content: + application/json: + schema: + type: object + properties: + DeviceInfo: + $ref: '#/components/schemas/DeviceInfo' + '400': + $ref: '#/components/responses/400' + '404': + $ref: '#/components/responses/404' + '403': + $ref: '#/components/responses/403' + put: + summary: Update information about a device including its association to a valid traffic rule - see clauses 5.2.5 and 5.4.3. + description: The PUT method may be used by a service consumer to update a device registration including its association to a valid traffic rule. This method is typically used in the "device registration update" procedure as described in clause 5.2.5 and in the "user transport assignment" procedure as described in clause 5.4.3. + operationId: registereddevicesByIdPUT + tags: + - reg-dev + parameters: + - name: registeredDeviceId + in: path + required: true + description: The unique identifier of the registered device. + schema: + type: string + requestBody: + description: One or more updated attributes that are allowed to be changed are included in the DeviceInfo data structure in the payload body of the request. . + required: true + content: + application/json: + schema: + type: object + properties: + DeviceInfo: + $ref: '#/components/schemas/DeviceInfo' + responses: + '200': + description: Upon success, a response body containing data type describing the updated DeviceInfo is returned. + content: + application/json: + schema: + type: object + properties: + DeviceInfo: + $ref: '#/components/schemas/DeviceInfo' + '400': + $ref: '#/components/responses/400' + '404': + $ref: '#/components/responses/404' + '403': + $ref: '#/components/responses/403' + '412': + $ref: '#/components/responses/412' + delete: + summary: "Deregister a device - see clause\_5.2.6." + description: The DELETE method may be used by a service consumer to deregister a device. This method is typically used in the "device deregistration" procedure as described in clause 5.2.6. + operationId: registereddevicesByIdDELETE + tags: + - reg-dev + parameters: + - name: registeredDeviceId + in: path + required: true + description: The unique identifier of the registered device. + schema: + type: string + responses: + '204': + $ref: '#/components/responses/204' + '404': + $ref: '#/components/responses/404' + '403': + $ref: '#/components/responses/403' + /registered_iot_platforms: + get: + summary: Retrieve information about all IoT platforms - see clause 5.3.2. + description: "The GET method may be used by an authorized service consumer to retrieve the information of all currently registered IoT platforms. This method is typically used in the \"registered IoT platforms query\" procedure as described in clause\_5.3.2." + operationId: registerediotplatformsGET + tags: + - reg-iot-plat + parameters: + - name: fields + in: query + description: | + The list shall contain the following attributes from the IotPlatformInfo data type: + - iotPlatformId + - enabled + style: form + explode: true + schema: + type: array + items: + type: string + + responses: + '200': + description: Upon success, a response body containing the list of registered IoT platforms is returned. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/IotPlatformInfo' + '400': + $ref: '#/components/responses/400' + '404': + $ref: '#/components/responses/404' + '403': + $ref: '#/components/responses/403' + post: + summary: "Register a IoT platform - see clause\_5.3.4." + description: The POST method may be used by a service consumer to register a new IoT platform. This method is typically used in the "IoT platform registration" procedure as described in clause 5.3.4. + operationId: registerediotplatformsPOST + tags: + - reg-iot-plat + requestBody: + description: Payload body in the request contains the information associated to the IoT platform to be registered. + required: true + content: + application/json: + schema: + type: object + properties: + IoTPlatformInfo: + $ref: '#/components/schemas/IotPlatformInfo' + responses: + '201': + description: Upon success, the HTTP response shall include a "Location" HTTP header that contains the resource URI of the registered IoT platform. + content: + application/json: + schema: + type: object + properties: + IoTPlatformInfo: + $ref: '#/components/schemas/IotPlatformInfo' + '400': + $ref: '#/components/responses/400' + '404': + $ref: '#/components/responses/404' + '403': + $ref: '#/components/responses/403' + /registered_iot_platforms/{registeredIotPlatformId}: + get: + summary: Discover native services and obtain information about user transports provided by a IoT platform - see clauses 5.3.3 and 5.4.2. + description: 'The GET method may be used by a service consumer to obtain information about a IoT platform. This method is typically used in the "IoT platform information request" procedure as described in clause 5.3.3 and in the "user transport query" procedure as described in clause 5.4.2. ' + operationId: registerediotplatformsByIdGET + tags: + - reg-iot-plat + parameters: + - name: registeredIotPlatformId + in: path + required: true + description: The unique identifier of the registered IoT platform. + schema: + type: string + - name: fields + in: query + description: | + The list may contain one or more of the following attributes from the IotPlatformInfo data type: + - userTransportInfo + - customServiceTransportInfo + style: form + explode: true + schema: + type: array + items: + type: string + responses: + '200': + description: Upon success, a response body containing information about the registered IoT platform is returned. + content: + application/json: + schema: + type: object + properties: + IotPlatformInfo: + $ref: '#/components/schemas/IotPlatformInfo' + '400': + $ref: '#/components/responses/400' + '404': + $ref: '#/components/responses/404' + '403': + $ref: '#/components/responses/403' + put: + summary: Update information about a IoT platform - see clause 5.3.5. + description: The PUT method may be used by a service consumer to update a IoT platform registration. This method is typically used in the "IoT platform update" procedure as described in clause 5.3.5. + operationId: registerediotplatformsByIdPUT + tags: + - reg-iot-plat + parameters: + - name: registeredIotPlatformId + in: path + required: true + description: The unique identifier of the registered IoT platform. + schema: + type: string + requestBody: + description: One or more updated attributes that are allowed to be changed are included in the IotPlatformInfo data structure in the payload body of the request. . + required: true + content: + application/json: + schema: + type: object + properties: + IotPlatformInfo: + $ref: '#/components/schemas/IotPlatformInfo' + responses: + '200': + description: Upon success, a response body containing data type describing the updated IotPlatformInfo is returned. + content: + application/json: + schema: + type: object + properties: + IotPlatformInfo: + $ref: '#/components/schemas/IotPlatformInfo' + '400': + $ref: '#/components/responses/400' + '404': + $ref: '#/components/responses/404' + '403': + $ref: '#/components/responses/403' + '412': + $ref: '#/components/responses/412' + delete: + summary: Deregister a IoT platform - see clause 5.3.6. + description: The DELETE method may be used by a service consumer to deregister a IoT platform. This method is typically used in the "IoT platform deregistration" procedure as described in clause 5.3.6. + operationId: registerediotplatformsByIdDELETE + tags: + - reg-iot-plat + parameters: + - name: registeredIotPlatformId + in: path + required: true + description: The unique identifier of the registered IoT platform. + schema: + type: string + responses: + '204': + $ref: '#/components/responses/204' + '404': + $ref: '#/components/responses/404' + '403': + $ref: '#/components/responses/403' +components: + schemas: + ProblemDetails: + type: object + properties: + type: + type: string + format: uri + description: A URI reference according to IETF RFC 3986 that identifies the problem type + title: + type: string + description: A short, human-readable summary of the problem type + status: + type: integer + format: uint32 + description: The HTTP status code for this occurrence of the problem + detail: + type: string + description: A human-readable explanation specific to this occurrence of the problem + instance: + type: string + format: uri + description: A URI reference that identifies the specific occurrence of the problem + DeviceInfo: + title: DeviceInfo + type: object + properties: + deviceAuthenticationInfo: + description: Information needed for secondary authentication of the IoT device to the data network - see ETSI TS 129 561 [i.4] and ETSI TS 129 061 [i.5] for 5G and LTE procedures, respectively. This attribute is implementation dependent and should be logically linked to the identifiers of the IoT device listed hereafter. + type: string + deviceMetadata: + description: 'Additional information about the IoT device. This attribute is implementation dependent and may be expressed as an array of keyvalue pairs. ' + type: array + items: + $ref: '#/components/schemas/KeyValuePair' + gpsi: + description: GPSI of the IoT device if 5G-enabled (see note 1). + type: string + pei: + description: PEI of the IoT device if 5G-enabled (see note 1). + type: string + supi: + description: SUPI of the IoT device if 5G-enabled (see note 1). + type: string + msisdn: + description: MSISDN of the IoT device if LTE-enabled (see note 1). + type: string + imei: + description: IMEI of the IoT device if LTE-enabled (see note 1). + type: string + imsi: + description: IMSI of the IoT device if LTE-enabled (see note 1). + type: string + iccid: + description: ICCID of the IoT device (see note 1). + type: string + deviceId: + description: Human-readable identifier of the IoT device. + type: string + requestedMecTrafficRule: + description: "MEC traffic rules the IoT device is requested to be associated to (see note 2). The data type definition is as per ETSI GS\_MEC 010-2 [i.6]." + type: array + items: + $ref: '#/components/schemas/TrafficRuleDescriptor' + requestedIotPlatformId: + description: IoT platform to which the IoT device is requested to be associated to (see note 2). + type: string + requestedUserTransportId: + description: User transport to which the IoT device is requested to be associated to (see note 2). + type: string + deviceSpecificMessageFormats: + $ref: '#/components/schemas/DeviceSpecificMessageFormats' + downlinkInfo: + $ref: '#/components/schemas/DownlinkInfo' + clientCertificate: + description: Client-side SSL/TLS certificate to be used by the MEC IoTS to interact with the user transport provided by the associated IoT platform in case the MEC IoTS acts on behalf of the IoT device. + type: string + enabled: + description: Indication whether the IoT device has a valid associated traffic rule (TRUE) or not (FALSE). See note 3. + type: boolean + required: + - deviceAuthenticationInfo + - deviceId + - enabled + description: | + NOTE 1: At least one attribute among gpsi, pei, supi, msisdn, imei, imsi, and iccid should be provided. Sufficient security + measures shall be put in place when any attribute among PEI, SUPI, IMEI, and IMSI is disclosed over the API. + NOTE 2: Until a valid traffic rule is not provided, the device will not be able to use the IoTS. A valid traffic rule is provided + by one of the following options: + • the requestedMecTrafficRule attribute; + • the requestedIotPlatformId attribute when the IoT platform offers only one user transport; + • the combination of requestedIotPlatformId and requestedUserTransportId. + NOTE 3: Enabled is a pseudo-attribute which needs to be maintained by the IoTS based on the presence or not of a valid + traffic rule associated to the device. It cannot be set directly by the service consumer. + IotPlatformInfo: + title: IotPlatformInfo + type: object + properties: + iotPlatformId: + description: Identifier of the IoT platform. + type: string + userTransportInfo: + description: Information about the user transport(s) provided by the IoT platform. + type: array + minItems: 1 + items: + $ref: '#/components/schemas/MBTransportInfo' + customServicesTransportInfo: + description: Transport enabling access to vendor-specific services provided by the IoT platform. The data type definition is as per ETSI GS MEC 011 [i.2]. + type: array + minItems: 0 + items: + $ref: '#/components/schemas/TransportInfo' + enabled: + description: Indication whether the IoT platform is capable of providing user transports and vendor-specific services (TRUE) or not (FALSE). + type: boolean + required: + - iotPlatformId + - userTransportInfo + - enabled + MBTransportInfo: + title: MBTransportInfo + type: object + properties: + id: + description: "The identifier of this transport as per ETSI GS\_MEC\_011 [i.2]." + type: string + name: + description: "The name of this transport as per ETSI GS\_MEC\_011\_[i.2]." + type: string + description: + description: "Human-readable description of this transport as per ETSI GS\_MEC 011 [i.2]." + type: string + type: + description': Type of the transport. The attribute shall be set to "MB_TOPIC_BASED." + $ref: '#/components/schemas/TransportType' + protocol: + description: The name of the protocol used. Being the transport of MB_TOPIC_BASED type, this attribute should be typically set to "MQTT" or "AMQP." + type: string + version: + description: "The version of the protocol used as per ETSI GS\_MEC\_011\_[i.2]." + type: string + endpoint: + description': Information about the endpoint to access the transport as per ETSI GS MEC 011 [i.2]. + $ref: '#/components/schemas/EndPointInfo' + security: + description: Information about the security used by the transport as per ETSI GS MEC 011 [i.2]. + $ref: '#/components/schemas/SecurityInfo' + implSpecificInfo: + $ref: '#/components/schemas/ImplSpecificInfo' + required: + - id + - name + - type + - protocol + - version + - endpoint + - security + - implSpecificInfo + EventMsg: + title: EventMsg + type: object + properties: + eventTopic: + description: 'Topic where the message containing application-specific information should be published. ' + type: string + selectedSerializer: + description': Type of serializer to be used for the topic as per ETSI GS MEC 011 [i.2]. + $ref: '#/components/schemas/SerializerType' + includeDeviceAddr: + description: Indication whether to include the IP address of the IoT device (TRUE) or not (FALSE). + type: boolean + includeDeviceMetadata: + description: Indication whether to include the metadata about the IoT device (TRUE) or not (FALSE). + type: boolean + includePei: + description: Indication whether to include the PEI of the IoT device (TRUE) or not (FALSE). + type: boolean + includeSupi: + description: Indication whether to include the SUPI of the IoT device (TRUE) or not (FALSE). + type: boolean + includeImei: + description: Indication whether to include the IMEI of the IoT device (TRUE) or not (FALSE). + type: boolean + includeImsi: + description: Indication whether to include the IMSI of the IoT device (TRUE) or not (FALSE). + type: boolean + includeIccid: + description: Indication whether to include the ICCID of the IoT device (TRUE) or not (FALSE). + type: boolean + includeDeviceId: + description: Indication whether to include the human-readable identified of the IoT device (TRUE) or not (FALSE). + type: boolean + required: + - eventTopic + - selectedSerializer + UplinkMsg: + title: UplinkMsg + type: object + properties: + uplinkTopic: + description: Topic where the message containing the data generated by the IoT device(s) should be published, in order to be consumed by the end IoT application(s). + type: string + selectedSerializer: + description': Type of serializer to be used for the topic as per ETSI GS MEC 011 [i.2]. + $ref: '#/components/schemas/SerializerType' + includeDevicePort: + description: Indication whether to include the UDP port of the remote IoT device (TRUE) or not (FALSE). + type: boolean + includeDeviceAddr: + description: Indication whether to include the IP address of the IoT device (TRUE) or not (FALSE). + type: boolean + includeDeviceMetadata: + description: Indication whether to include the metadata about the IoT device (TRUE) or not (FALSE). + type: boolean + includePei: + description: Indication whether to include the PEI of the IoT device (TRUE) or not (FALSE). + type: boolean + includeSupi: + description: Indication whether to include the SUPI of the IoT device (TRUE) or not (FALSE). + type: boolean + includeImei: + description: Indication whether to include the IMEI of the IoT device (TRUE) or not (FALSE). + type: boolean + includeImsi: + description: Indication whether to include the IMSI of the IoT device (TRUE) or not (FALSE). + type: boolean + includeIccid: + description: Indication whether to include the ICCID of the IoT device (TRUE) or not (FALSE). + type: boolean + includeDeviceId: + description: Indication whether to include the human-readable identified of the IoT device (TRUE) or not (FALSE). + type: boolean + required: + - uplinkTopic + - selectedSerializer + DeviceSpecificMessageFormats: + description: Format of the messages to be published by the MEC IoTS on the user transport provided by the associated IoT platform in case the MEC IoTS acts on behalf of the IoT device. + type: object + properties: + eventMsgFormat: + description': Event message format configuration. + $ref: '#/components/schemas/EventMsg' + uplinkMsgFormat: + description': Uplink message format configuration. + $ref: '#/components/schemas/UplinkMsg' + DownlinkInfo: + description: Downlink communication configuration of the user transport provided by the associated IoT platform in case the MEC IoTS acts on behalf of the IoT device. + type: object + properties: + downlinkTopic: + description: Topic associated to the IoT device. This topic should be used by an end IoT application to send downlink data to the IoT device. + type: string + devicePort: + description: UDP port to be used by the MEC IoTS for the outgoing downlink packets towards the IoT device. In case a default value is used, this attribute is optional. + type: integer + ImplSpecificInfo: + description: Additional implementation specific details of the transport. + type: object + properties: + eventTopics: + description: Topics used to publish events related to the established session between the IoT device(s) and the end IoT application(s) on the user transport. + type: array + minItems: 0 + items: + type: string + uplinkTopics: + description: Topics used to publish data generated by the IoT device(s) on the user transport, in order to be consumed by the end IoT application(s). + type: array + items: + type: string + downlinkTopics: + description: Topics used to publish data generated by the IoT applications(s) on the user transport, in order to be consumed by the end IoT device(s). + type: array + items: + type: string + SerializerType: + type: string + description: The enumeration SerializerType represents types of serializers. + enum: + - JSON + - XML + - PROTOBUF3 + TransportInfo: + title: TransportInfo + type: object + properties: + id: + description: The identifier of this transport. + type: string + name: + description: The name of this transport. + type: string + description: + description: Human-readable description of this transport. + type: string + type: + description': Type of the transport. + $ref: '#/components/schemas/TransportType' + protocol: + description: The name of the protocol used. Shall be set to "HTTP" for a REST API. + type: string + version: + description: The version of the protocol used. + type: string + endpoint: + description': Information about the endpoint to access the transport. + $ref: '#/components/schemas/EndPointInfo' + security: + description': Information about the security used by the transport. + $ref: '#/components/schemas/SecurityInfo' + implSpecificInfo: + description: Additional implementation specific details of the transport. + type: string + required: + - id + - name + - type + - protocol + - version + - endpoint + - security + TransportType: + type: string + enum: + - REST_HTTP + - MB_TOPIC_BASED + - MB_ROUTING + - MB_PUBSUB + - RPC + - RPC_STREAMING + - WEBSOCKET + description: Enumeration representing types of transports. + EndPointInfo: + title: EndPointInfo + type: object + properties: + uris: + description: Entry point information of the service as string, formatted according to URI syntax (see IETF RFC 3986 [8]). Shall be used for REST APIs. See note. + type: array + items: + type: string + fqdn: + description: Fully Qualified Domain Name of the service. See note. + type: array + items: + type: string + addresses: + type: array + items: + $ref: '#/components/schemas/Addresses' + alternative: + description: "Entry point information of the service in a format defined by an implementation, or in an external specification. See\_note." + type: string + description: | + NOTE: Exactly one of "uris", "fqdn", "addresses" or "alternative" shall be present. + SecurityInfo: + type: object + properties: + oAuth2Info: + $ref: '#/components/schemas/OAuth2Info' + extensions: + description: > + Extensions for alternative transport mechanisms. These extensions depend on the actual transport and are out of scope of the present document. + For instance, such extensions may be used to signal the necessary parameters for the client to use TLS-based authorization defined for alternative transports (see ETSI GS MEC 009 [5] for more information). + type: string + Addresses: + description: Entry point information of the service as one or more pairs of IP address and port. See note. + type: object + properties: + host: + description: Host portion of the address. + type: string + port: + description: Port portion of the address. + type: integer + required: + - host + - port + OAuth2Info: + description: Parameters related to use of OAuth 2.0. Shall be present in case OAuth 2.0 (see IETF RFC 6749 [13]) is supported to secure the provision of the service over the transport. + type: object + properties: + grantTypes: + type: array + description: | + List of supported OAuth 2.0 grant types. + Each entry shall be one of the following permitted values: + - OAUTH2_AUTHORIZATION_CODE: Authorization code grant type + - OAUTH2_IMPLICIT_GRANT: Implicit grant type + - OAUTH2_RESOURCE_OWNER: Resource owner password credentials grant type + - OAUTH2_CLIENT_CREDENTIALS: Client credentials grant type + Only the value "OAUTH2_CLIENT_CREDENTIALS" is supported in the present document. + items: + type: string + enum: + - OAUTH2_AUTHORIZATION_CODE + - OAUTH2_IMPLICIT_GRANT + - OAUTH2_RESOURCE_OWNER + - OAUTH2_CLIENT_CREDENTIALS + tokenEndpoint: + description: The token endpoint. Shall be present unless the grant type is OAUTH2_IMPLICIT_GRANT. + type: string + format: uri + required: + - grantTypes + TrafficRuleDescriptor: + title: TrafficRuleDescriptor + type: object + properties: + trafficRuleId: + description: Identifies the traffic rule. + type: string + filterType: + type: string + description: | + Definition of filter type: per FLOW or PACKET + + If it is per FLOW, the filter matches upstream (e.g. UE->EPC) packets and downstream (e.g. EPC->UE) packets are handled by the same context. + enum: + - per FLOW + - per PACKET + priority: + description: "Priority of this traffic rule within the range 0 to 255. If traffic rule conflicts, the one with higher priority take precedence. See note\_1." + type: integer + trafficFilter: + description: The filter used to identify specific flow/packets that need to be handled by the MEC host. + type: array + items: + $ref: '#/components/schemas/TrafficFilter' + action: + type: string + description: 'Identifies the action of the MEC host data plane, when a packet matches the trafficFilter, the example actions include: + + DROP, + + FORWARD_DECAPSULATED, + + FORWARD_ENCAPSULATED, + + PASSTHROUGH, + + DUPLICATE_DECAPSULATED, + + DUPLICATE_ENCAPSULATED ' + enum: + - SEE_DESCRIPTION + dstInterface: + description': Describes the destination interface information. If the action is FORWARD_DECAPSULATED, FORWARD_ENCAPSULATED or PASSTHROUGH, one value shall be provided. If the action is DUPLICATE_DECAPSULATED or DUPLICATE_ENCAPSULATED, two values shall be provided. See note 2. If the action is DROP, no value shall be provided. + $ref: '#/components/schemas/InterfaceDescriptor' + required: + - trafficRuleId + - filterType + - priority + - trafficFilter + - action + description: | + NOTE 1: Value indicates the priority in descending order, i.e. with 0 as the highest priority and 255 as the lowest + priority. + NOTE 2: Some applications (like inline/tap) require two interfaces. The first interface in the case of inline/tap is on the + client (e.g. UE) side and the second on the core network (e.g. EPC) side. + TrafficFilter: + title: TrafficFilter + type: object + properties: + srcAddress: + description: 'An IP address or a range of IP addresses. + + For IPv4, the IP address could be an IP address plus mask, or an individual IP address, or a range of IP addresses. + + For IPv6, the IP address could be an IP prefix, or a range of IP prefixes.' + type: array + items: + type: string + dstAddress: + description: 'An IP address or a range of IP addresses. + + For IPv4, the IP address could be an IP address plus mask, or an individual IP address, or a range of IP addresses. + + For IPv6, the IP address could be an IP prefix, or a range of IP prefixes.' + type: array + items: + type: string + srcPort: + description: A port or a range of ports. + type: array + items: + type: string + dstPort: + description: A port or a range of ports. + type: array + items: + type: string + protocol: + description: Specify the protocol of the traffic filter. + type: array + items: + type: string + tag: + description: Used for tag based traffic rule. + type: array + items: + type: string + uri: + description: An URI label, in application layer, i.e. in HTTP message, is used to filter the traffic. + type: array + items: + type: string + packetLabel: + description: A customized packet label in network layer, as defined by the owner of the MEC platform, is used to filter the traffic. + type: array + items: + type: string + srcTunnelAddress: + description: Used for GTP tunnel based traffic rule. + type: array + items: + type: string + tgtTunnelAddress: + description: Used for GTP tunnel based traffic rule. + type: array + items: + type: string + srcTunnelPort: + description: Used for GTP tunnel based traffic rule. + type: array + items: + type: string + dstTunnelPort: + description: Used for GTP tunnel based traffic rule. + type: array + items: + type: string + qCI: + description: Used to match all packets that have the same QCI. + type: integer + dSCP: + description: Used to match all IPv4 packets that have the same DSCP. + type: integer + tC: + description: Used to match all IPv6 packets that have the same TC. + type: integer + InterfaceDescriptor: + title: InterfaceDescriptor + type: object + properties: + interfaceType: + type: string + description: 'Type of interface: TUNNEL, MAC, IP, etc.' + enum: + - TUNNEL + - MAC + - IP + tunnelInfo: + description': Included only if the destination address type is tunnel. + $ref: '#/components/schemas/TunnelInfo' + srcMACAddress: + description: If the interface type is MAC, the source address identifies the MAC address of the interface. + type: string + dstMACAddress: + description: If the interface type is MAC, the destination address identifies the MAC address of the destination. Only used for dstInterface. + type: string + dstIPAddress: + description: If the interface type is IP, the destination address identifies the IP address of the destination. Only used for dstInterface. + type: string + required: + - interfaceType + TunnelInfo: + title: TunnelInfo + type: object + properties: + tunnelType: + type: string + description: 'Type of tunnel: GTP-U, GRE, etc.' + enum: + - GTP-U + - GRE + tunnelDstAddress: + description: Destination address of the tunnel. + type: string + tunnelSrcAddress: + description: Source address of the tunnel. + type: string + tunnelSpecificData: + description: Parameters specific to the tunnel. + type: string + required: + - tunnelType + - tunnelDstAddress + - tunnelSrcAddress + KeyValuePair: + description: 'Key-value pairs for device metadata' + type: object + properties: + key: + type: string + value: + type: string + + responses: + '200': + description: OK + '204': + description: No Content + '400': + description: 'Bad Request: used to indicate that incorrect parameters were passed to the request.' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ProblemDetails' + '403': + description: 'Forbidden: operation is not allowed given the current status of the resource.' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ProblemDetails' + '404': + description: 'Not Found: used when a client provided a URI that cannot be mapped to a valid resource URI.' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ProblemDetails' + '412': + description: 'Precondition failed: used when a condition has failed during conditional requests, e.g. when using ETags to avoid write conflicts when using PUT' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ProblemDetails' \ No newline at end of file diff --git a/README.md b/README.md index 241f008a2aad00ac8b7729188bc78b82d757b03b..ac9043c970b522e0a56db63ce96c8bf3eb91c3e6 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,15 @@ This repository contains OpenAPIs descriptions for the interfaces specified in ETSI MEC GS 033 +## Online resources +* [Specification Document](https://www.etsi.org/deliver/etsi_gs/MEC/001_099/033/03.01.01_60/gs_mec033v030101p.pdf) + +## Navigate with Swagger UI +* [IoT API](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/mec/gs033-iot-api/raw/stf644/MEC033_IoT.yaml) + +## Navigate with Redocly +* [IoT API](https://redocly.github.io/redoc/?url=https://forge.etsi.org/rep/mec/gs033-iot-api/raw/stf644/MEC033_IoT.yaml) + ## License diff --git a/proto3-gen.md b/proto3-gen.md new file mode 100644 index 0000000000000000000000000000000000000000..e98aaf46643f2060b3c1a0650c6454ad959b1a7a --- /dev/null +++ b/proto3-gen.md @@ -0,0 +1,135 @@ +# Protobuf Schema Generation + +[OpenAPI Generator](https://openapi-generator.tech) is used to generate protobuf schema (`.proto3`) files from OpenAPI specifications of MEC033 IoT API. + +>**NOTE:** At the time of writing, the tool does not support OAS 3.1 version and we have to first convert the [IoT API](./MEC033_IoT.yaml) to OAS 3.0 for generating protobuf schema. + +1. Convert OAS for [IoT API](./MEC033_IoT.yaml) from 3.1 to 3.0​ + + - Change the value of `openapi` field from 3.1.0 to 3.0.0​ + + - Use this [VS code extension](https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi) to see the errors in the downgraded YAML (v3.0)​ + + - Manually fix the errors​ + - mostly related to `examples` <--> `example` interchange​ + - or some 3.1 fields that are not supported in 3.0​ (comment them out) + +2. Generate proto files + - Install the `openapi-generator-cli.jar` using the installation procedure mentioned [here](https://openapi-generator.tech/docs/installation#jar). + - Generate the proto files using the following command + ```sh + $ java -jar openapi-generator-cli.jar generate -i MEC033_IoT.yaml -g protobuf-schema -o proto3/ --package-name mec033 + ``` + +3. Carefully inspect the generated `.proto` files for any inconsistencies. Some of the things to look out for: + - Proto3 generated files for enumerations, structures containing allOf, oneOf, anyOf etc. may need to be touched manually + - Check that all the nested models are being _imported_ correctly in their parent models + - Remove redundant proto files + + +4. Validate protobuf schema by generating code from proto3 descriptions in different languages. See [this section](#code-generation-from-proto3) for more details. + +# Code Generation from proto3 + +Below are some code generation examples for Python, Go and Ruby. For other languages, please refer to https://grpc.io/docs/quickstart/. + +### Python + +1. Install the grpcio-tools package + ```sh + $ pip install grpcio-tools + ``` + +2. Create a directory for generated Python stubs + ```sh + $ mkdir python-stubs + ``` + +3. Run the following commands from the root of the directory containing this README that you are reading. + + - Models: + + ```sh + $ python -m grpc_tools.protoc -I./proto3 --python_out=./python-stubs ./proto3/models/* + ``` + + The above command will generate .py files for all the data models in the ./models directory + + - Services: + + ```sh + $ python -m grpc_tools.protoc -I./proto3 --python_out=./python-stubs --grpc_python_out=./python-stubs ./proto3/services/reg_dev_service.proto + ``` + + ```sh + $ python -m grpc_tools.protoc -I./proto3 --python_out=./python-stubs --grpc_python_out=./python-stubs ./proto3/services/reg_iot_plat_service.proto + ``` + + The above command will generate four files for the IoT service: + - _reg_dev_service_pb2.py_ and _reg_iot_plat_service_pb2.py: containing the python data models used in the IoT service file + - _reg_dev_service_pb2_grpc.py_ and _reg_iot_plat_service_pb2_grpc.py: containing all the classes and functions needed for the supported HTTP methods in the IoT API + +### Go + +1. Install protocol buffer compiler + ```sh + $ apt install -y protobuf-compiler + ``` +2. Install Go plugins for `protoc` + ```sh + $ go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.28.1 + ``` + ```sh + $ go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.2.0 + ``` +3. Update `PATH` so `protoc` can find the plugins + ```sh + $ export PATH="$PATH:$(go env GOPATH)/bin" + ``` +4. Define a go package by appending `option go_package = "./mec033.services.IoTservice";` in all .proto files like this: + + ```Go + ... + + syntax = "proto3"; + + package mec033.services.IoTservice; + + option go_package = "./mec033.services.IoTservice"; + + import public "models/.proto"; + + ... + ``` +5. Generate Go code for models and services + ```sh + $ mkdir go-stubs + $ protoc --go_out=./go-stubs ./proto3/models/* -I./proto3 + $ protoc --go_out=./go-stubs ./proto3/services/* --go-grpc_out=go-stubs -I./proto3 + ``` + > The generated `.pb.go` files will contain all the protocol buffer code to populate, serialize, and retrieve request and response message types defined in the `models` folder. + > And the `reg_dev_service_grpc.pb.go` will contain the stubs for the methods defined in the `IoT_service.proto` file. + +### Ruby + +1. Install gRPC Ruby Plugin and required tools + ```sh + $ gem install grpc + $ sudo apt install ruby-grpc-tools + ``` + +2. Generate code + ```sh + $ mkdir ruby-stubs + ``` + + Run the following command to create Ruby modules for all the data models defined in the proto files. + + ```sh + $ grpc_tools_ruby_protoc -I./proto3 --ruby_out=ruby-stubs ./proto3/models/* + ``` + Run the following command to generate `reg_dev_service_pb.rb` and `reg_dev_service_grpc_pb.rb` files, containing stub and service classes for the endpoints and methods defined in MEC033 IoT service. + + ```sh + $ grpc_tools_ruby_protoc -I./proto3 --ruby_out=ruby-stubs --grpc_out=ruby-stubs ./proto3/services/* + ``` \ No newline at end of file diff --git a/proto3/.openapi-generator-ignore b/proto3/.openapi-generator-ignore new file mode 100644 index 0000000000000000000000000000000000000000..7484ee590a3894506cf063799b885428f95a71be --- /dev/null +++ b/proto3/.openapi-generator-ignore @@ -0,0 +1,23 @@ +# OpenAPI Generator Ignore +# Generated by openapi-generator https://github.com/openapitools/openapi-generator + +# Use this file to prevent files from being overwritten by the generator. +# The patterns follow closely to .gitignore or .dockerignore. + +# As an example, the C# client generator defines ApiClient.cs. +# You can make changes and tell OpenAPI Generator to ignore just this file by uncommenting the following line: +#ApiClient.cs + +# You can match any string of characters against a directory, file or extension with a single asterisk (*): +#foo/*/qux +# The above matches foo/bar/qux and foo/baz/qux, but not foo/bar/baz/qux + +# You can recursively match patterns against a directory, file or extension with a double asterisk (**): +#foo/**/qux +# This matches foo/bar/qux, foo/baz/qux, and foo/bar/baz/qux + +# You can also negate patterns with an exclamation (!). +# For example, you can ignore all files in a docs folder with the file extension .md: +#docs/*.md +# Then explicitly reverse the ignore rule for a single file: +#!docs/README.md diff --git a/proto3/.openapi-generator/FILES b/proto3/.openapi-generator/FILES new file mode 100644 index 0000000000000000000000000000000000000000..be30c588e36ded1791fcfd8bea11ccb9fbb10149 --- /dev/null +++ b/proto3/.openapi-generator/FILES @@ -0,0 +1,28 @@ +README.md +models/addresses.proto +models/device_info.proto +models/device_specific_message_formats.proto +models/downlink_info.proto +models/end_point_info.proto +models/event_msg.proto +models/impl_specific_info.proto +models/interface_descriptor.proto +models/iot_platform_info.proto +models/key_value_pair.proto +models/mb_transport_info.proto +models/o_auth2_info.proto +models/problem_details.proto +models/registereddevices_get200_response.proto +models/registereddevices_post_request.proto +models/registerediotplatforms_by_id_get200_response.proto +models/registerediotplatforms_post_request.proto +models/security_info.proto +models/serializer_type.proto +models/traffic_filter.proto +models/traffic_rule_descriptor.proto +models/transport_info.proto +models/transport_type.proto +models/tunnel_info.proto +models/uplink_msg.proto +services/reg_dev_service.proto +services/reg_iot_plat_service.proto diff --git a/proto3/.openapi-generator/VERSION b/proto3/.openapi-generator/VERSION new file mode 100644 index 0000000000000000000000000000000000000000..cd802a1ec4eb67560bbaa579fbb00de12c98a68f --- /dev/null +++ b/proto3/.openapi-generator/VERSION @@ -0,0 +1 @@ +6.6.0 \ No newline at end of file diff --git a/proto3/README.md b/proto3/README.md new file mode 100644 index 0000000000000000000000000000000000000000..51a7099cb5d8a9b7db0e14818bb57eed297555ab --- /dev/null +++ b/proto3/README.md @@ -0,0 +1,115 @@ +# gPRC for mec033 + +ETSI GS MEC 033 IoT API described using OpenAPI. + +## Overview +These files were generated by the [OpenAPI Generator](https://openapi-generator.tech) project. + +- API version: 3.1.1 +- Package version: +- Build package: org.openapitools.codegen.languages.ProtobufSchemaCodegen +For more information, please visit [https://forge.etsi.org/rep/mec/gs033-iot-api](https://forge.etsi.org/rep/mec/gs033-iot-api/) + +## Usage + +Below are some code generation examples for Python, Go and Ruby. For other languages, please refer to https://grpc.io/docs/quickstart/. + +### Python + +1. Install the grpcio-tools package + ```sh + $ pip install grpcio-tools + ``` + +2. Create a directory for generated Python stubs + ```sh + $ mkdir python-stubs + ``` + +3. Run the following commands from the root of the directory containing this README that you are reading. + + - Models: + + ```sh + $ python -m grpc_tools.protoc -I./proto3 --python_out=./python-stubs ./proto3/models/* + ``` + + The above command will generate .py files for all the data models in the ./models directory + + - Services: + + ```sh + $ python -m grpc_tools.protoc -I./proto3 --python_out=./python-stubs --grpc_python_out=./python-stubs ./proto3/services/reg_dev_service.proto + ``` + + ```sh + $ python -m grpc_tools.protoc -I./proto3 --python_out=./python-stubs --grpc_python_out=./python-stubs ./proto3/services/reg_iot_plat_service.proto + ``` + + The above command will generate four files for the IoT service: + - _reg_dev_service_pb2.py_ and _reg_iot_plat_service_pb2.py: containing the python data models used in the IoT service file + - _reg_dev_service_pb2_grpc.py_ and _reg_iot_plat_service_pb2_grpc.py: containing all the classes and functions needed for the supported HTTP methods in the IoT API + +### Go + +1. Install protocol buffer compiler + ```sh + $ apt install -y protobuf-compiler + ``` +2. Install Go plugins for `protoc` + ```sh + $ go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.28.1 + ``` + ```sh + $ go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.2.0 + ``` +3. Update `PATH` so `protoc` can find the plugins + ```sh + $ export PATH="$PATH:$(go env GOPATH)/bin" + ``` +4. Define a go package by appending `option go_package = "./mec033.services.IoTservice";` in all .proto files like this: + + ```Go + ... + + syntax = "proto3"; + + package mec033.services.IoTservice; + + option go_package = "./mec033.services.IoTservice"; + + import public "models/.proto"; + + ... + ``` +5. Generate Go code for models and services + ```sh + $ mkdir go-stubs + $ protoc --go_out=./go-stubs ./proto3/models/* -I./proto3 + $ protoc --go_out=./go-stubs ./proto3/services/* --go-grpc_out=go-stubs -I./proto3 + ``` + > The generated `.pb.go` files will contain all the protocol buffer code to populate, serialize, and retrieve request and response message types defined in the `models` folder. + > And the `reg_dev_service_grpc.pb.go` will contain the stubs for the methods defined in the `IoT_service.proto` file. + +### Ruby + +1. Install gRPC Ruby Plugin and required tools + ```sh + $ gem install grpc + $ sudo apt install ruby-grpc-tools + ``` + +2. Generate code + ```sh + $ mkdir ruby-stubs + ``` + + Run the following command to create Ruby modules for all the data models defined in the proto files. + + ```sh + $ grpc_tools_ruby_protoc -I./proto3 --ruby_out=ruby-stubs ./proto3/models/* + ``` + Run the following command to generate `reg_dev_service_pb.rb` and `reg_dev_service_grpc_pb.rb` files, containing stub and service classes for the endpoints and methods defined in MEC033 IoT service. + + ```sh + $ grpc_tools_ruby_protoc -I./proto3 --ruby_out=ruby-stubs --grpc_out=ruby-stubs ./proto3/services/* diff --git a/proto3/models/addresses.proto b/proto3/models/addresses.proto new file mode 100644 index 0000000000000000000000000000000000000000..6db8ceb17dfad29d1edd099bea00176f69766c68 --- /dev/null +++ b/proto3/models/addresses.proto @@ -0,0 +1,26 @@ +/* + ETSI GS MEC 033 IoT API + + ETSI GS MEC 033 IoT API described using OpenAPI. + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec033; + + +message Addresses { + + // Host portion of the address. + string host = 3208616; + + // Port portion of the address. + int32 port = 3446913; + +} diff --git a/proto3/models/device_info.proto b/proto3/models/device_info.proto new file mode 100644 index 0000000000000000000000000000000000000000..4b64145b70cd6c1e99a41da7b7e2fe157c0398a6 --- /dev/null +++ b/proto3/models/device_info.proto @@ -0,0 +1,73 @@ +/* + ETSI GS MEC 033 IoT API + + ETSI GS MEC 033 IoT API described using OpenAPI. + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec033; + +import public "models/device_specific_message_formats.proto"; +import public "models/downlink_info.proto"; +import public "models/key_value_pair.proto"; +import public "models/traffic_rule_descriptor.proto"; + +message DeviceInfo { + + // Information needed for secondary authentication of the IoT device to the data network - see ETSI TS 129 561 [i.4] and ETSI TS 129 061 [i.5] for 5G and LTE procedures, respectively. This attribute is implementation dependent and should be logically linked to the identifiers of the IoT device listed hereafter. + string deviceAuthenticationInfo = 231010367; + + // Additional information about the IoT device. This attribute is implementation dependent and may be expressed as an array of keyvalue pairs. + repeated KeyValuePair deviceMetadata = 227391580; + + // GPSI of the IoT device if 5G-enabled (see note 1). + string gpsi = 3179775; + + // PEI of the IoT device if 5G-enabled (see note 1). + string pei = 110868; + + // SUPI of the IoT device if 5G-enabled (see note 1). + string supi = 3541979; + + // MSISDN of the IoT device if LTE-enabled (see note 1). + string msisdn = 528072231; + + // IMEI of the IoT device if LTE-enabled (see note 1). + string imei = 3236040; + + // IMSI of the IoT device if LTE-enabled (see note 1). + string imsi = 3236474; + + // ICCID of the IoT device (see note 1). + string iccid = 100017508; + + // Human-readable identifier of the IoT device. + string deviceId = 35449363; + + // MEC traffic rules the IoT device is requested to be associated to (see note 2). The data type definition is as per ETSI GS MEC 010-2 [i.6]. + repeated TrafficRuleDescriptor requestedMecTrafficRule = 447629606; + + // IoT platform to which the IoT device is requested to be associated to (see note 2). + string requestedIotPlatformId = 382142773; + + // User transport to which the IoT device is requested to be associated to (see note 2). + string requestedUserTransportId = 440692748; + + DeviceSpecificMessageFormats deviceSpecificMessageFormats = 503076127; + + DownlinkInfo downlinkInfo = 457334378; + + // Client-side SSL/TLS certificate to be used by the MEC IoTS to interact with the user transport provided by the associated IoT platform in case the MEC IoTS acts on behalf of the IoT device. + string clientCertificate = 55457997; + + // Indication whether the IoT device has a valid associated traffic rule (TRUE) or not (FALSE). See note 3. + bool enabled = 535852225; + +} diff --git a/proto3/models/device_specific_message_formats.proto b/proto3/models/device_specific_message_formats.proto new file mode 100644 index 0000000000000000000000000000000000000000..29c90a34609edd6eadee5079c69a51266b1c0fc9 --- /dev/null +++ b/proto3/models/device_specific_message_formats.proto @@ -0,0 +1,26 @@ +/* + ETSI GS MEC 033 IoT API + + ETSI GS MEC 033 IoT API described using OpenAPI. + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec033; + +import public "models/event_msg.proto"; +import public "models/uplink_msg.proto"; + +message DeviceSpecificMessageFormats { + + EventMsg eventMsgFormat = 357883555; + + UplinkMsg uplinkMsgFormat = 410143422; + +} diff --git a/proto3/models/downlink_info.proto b/proto3/models/downlink_info.proto new file mode 100644 index 0000000000000000000000000000000000000000..2298da8a805eb8ebc509611dc0de049c8c238f9c --- /dev/null +++ b/proto3/models/downlink_info.proto @@ -0,0 +1,26 @@ +/* + ETSI GS MEC 033 IoT API + + ETSI GS MEC 033 IoT API described using OpenAPI. + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec033; + + +message DownlinkInfo { + + // Topic associated to the IoT device. This topic should be used by an end IoT application to send downlink data to the IoT device. + string downlinkTopic = 228920053; + + // UDP port to be used by the MEC IoTS for the outgoing downlink packets towards the IoT device. In case a default value is used, this attribute is optional. + int32 devicePort = 244191224; + +} diff --git a/proto3/models/end_point_info.proto b/proto3/models/end_point_info.proto new file mode 100644 index 0000000000000000000000000000000000000000..a6e9e59bbfe24fd5fbf68a6b09d82d40ad57b54b --- /dev/null +++ b/proto3/models/end_point_info.proto @@ -0,0 +1,32 @@ +/* + ETSI GS MEC 033 IoT API + + ETSI GS MEC 033 IoT API described using OpenAPI. + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec033; + +import public "models/addresses.proto"; + +message EndPointInfo { + + // Entry point information of the service as string, formatted according to URI syntax (see IETF RFC 3986 [8]). Shall be used for REST APIs. See note. + repeated string uris = 3598471; + + // Fully Qualified Domain Name of the service. See note. + repeated string fqdn = 3150485; + + repeated Addresses addresses = 337673123; + + // Entry point information of the service in a format defined by an implementation, or in an external specification. See note. + string alternative = 196794451; + +} diff --git a/proto3/models/event_msg.proto b/proto3/models/event_msg.proto new file mode 100644 index 0000000000000000000000000000000000000000..a7db055e84dd3e85a397e9978894f54f2fd5bdeb --- /dev/null +++ b/proto3/models/event_msg.proto @@ -0,0 +1,50 @@ +/* + ETSI GS MEC 033 IoT API + + ETSI GS MEC 033 IoT API described using OpenAPI. + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec033; + +import public "models/serializer_type.proto"; + +message EventMsg { + + // Topic where the message containing application-specific information should be published. + string eventTopic = 437189302; + + SerializerType selectedSerializer = 278593909; + + // Indication whether to include the IP address of the IoT device (TRUE) or not (FALSE). + bool includeDeviceAddr = 312382002; + + // Indication whether to include the metadata about the IoT device (TRUE) or not (FALSE). + bool includeDeviceMetadata = 228401774; + + // Indication whether to include the PEI of the IoT device (TRUE) or not (FALSE). + bool includePei = 303285069; + + // Indication whether to include the SUPI of the IoT device (TRUE) or not (FALSE). + bool includeSupi = 275136675; + + // Indication whether to include the IMEI of the IoT device (TRUE) or not (FALSE). + bool includeImei = 274830736; + + // Indication whether to include the IMSI of the IoT device (TRUE) or not (FALSE). + bool includeImsi = 274831170; + + // Indication whether to include the ICCID of the IoT device (TRUE) or not (FALSE). + bool includeIccid = 70481508; + + // Indication whether to include the human-readable identified of the IoT device (TRUE) or not (FALSE). + bool includeDeviceId = 501908777; + +} diff --git a/proto3/models/impl_specific_info.proto b/proto3/models/impl_specific_info.proto new file mode 100644 index 0000000000000000000000000000000000000000..a0ee89782204abb552b8a37a8207b2ba175546a3 --- /dev/null +++ b/proto3/models/impl_specific_info.proto @@ -0,0 +1,29 @@ +/* + ETSI GS MEC 033 IoT API + + ETSI GS MEC 033 IoT API described using OpenAPI. + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec033; + + +message ImplSpecificInfo { + + // Topics used to publish events related to the established session between the IoT device(s) and the end IoT application(s) on the user transport. + repeated string eventTopics = 131095646; + + // Topics used to publish data generated by the IoT device(s) on the user transport, in order to be consumed by the end IoT application(s). + repeated string uplinkTopics = 68167016; + + // Topics used to publish data generated by the IoT applications(s) on the user transport, in order to be consumed by the end IoT device(s). + repeated string downlinkTopics = 117199843; + +} diff --git a/proto3/models/interface_descriptor.proto b/proto3/models/interface_descriptor.proto new file mode 100644 index 0000000000000000000000000000000000000000..08c0e3f2ebc66c86be3a630ec6d4fbf9a2cb8093 --- /dev/null +++ b/proto3/models/interface_descriptor.proto @@ -0,0 +1,41 @@ +/* + ETSI GS MEC 033 IoT API + + ETSI GS MEC 033 IoT API described using OpenAPI. + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec033; + +import public "models/tunnel_info.proto"; + +message InterfaceDescriptor { + + // Type of interface: TUNNEL, MAC, IP, etc. + enum InterfaceTypeEnum { + InterfaceTypeEnum_TUNNEL = 0; + InterfaceTypeEnum_MAC = 1; + InterfaceTypeEnum_IP = 2; + } + + InterfaceTypeEnum interfaceType = 516041747; + + TunnelInfo tunnelInfo = 458558157; + + // If the interface type is MAC, the source address identifies the MAC address of the interface. + string srcMACAddress = 190916442; + + // If the interface type is MAC, the destination address identifies the MAC address of the destination. Only used for dstInterface. + string dstMACAddress = 439157945; + + // If the interface type is IP, the destination address identifies the IP address of the destination. Only used for dstInterface. + string dstIPAddress = 303696043; + +} diff --git a/proto3/models/iot_platform_info.proto b/proto3/models/iot_platform_info.proto new file mode 100644 index 0000000000000000000000000000000000000000..de459994e3dd3c32c05cb9d5830b731738888267 --- /dev/null +++ b/proto3/models/iot_platform_info.proto @@ -0,0 +1,34 @@ +/* + ETSI GS MEC 033 IoT API + + ETSI GS MEC 033 IoT API described using OpenAPI. + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec033; + +import public "models/mb_transport_info.proto"; +import public "models/transport_info.proto"; + +message IotPlatformInfo { + + // Identifier of the IoT platform. + string iotPlatformId = 298034279; + + // Information about the user transport(s) provided by the IoT platform. + repeated MBTransportInfo userTransportInfo = 317790572; + + // Transport enabling access to vendor-specific services provided by the IoT platform. The data type definition is as per ETSI GS MEC 011 [i.2]. + repeated TransportInfo customServicesTransportInfo = 456179513; + + // Indication whether the IoT platform is capable of providing user transports and vendor-specific services (TRUE) or not (FALSE). + bool enabled = 535852225; + +} diff --git a/proto3/models/key_value_pair.proto b/proto3/models/key_value_pair.proto new file mode 100644 index 0000000000000000000000000000000000000000..d3597deeba2e04ac662758a7ee42abe27f9cd14f --- /dev/null +++ b/proto3/models/key_value_pair.proto @@ -0,0 +1,24 @@ +/* + ETSI GS MEC 033 IoT API + + ETSI GS MEC 033 IoT API described using OpenAPI. + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec033; + + +message KeyValuePair { + + string key = 106079; + + string value = 111972721; + +} diff --git a/proto3/models/mb_transport_info.proto b/proto3/models/mb_transport_info.proto new file mode 100644 index 0000000000000000000000000000000000000000..711f44f24761a5800deaabf7135a8e3bd71d9908 --- /dev/null +++ b/proto3/models/mb_transport_info.proto @@ -0,0 +1,47 @@ +/* + ETSI GS MEC 033 IoT API + + ETSI GS MEC 033 IoT API described using OpenAPI. + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec033; + +import public "models/end_point_info.proto"; +import public "models/impl_specific_info.proto"; +import public "models/security_info.proto"; +import public "models/transport_type.proto"; + +message MBTransportInfo { + + // The identifier of this transport as per ETSI GS MEC 011 [i.2]. + string id = 3355; + + // The name of this transport as per ETSI GS MEC 011 [i.2]. + string name = 3373707; + + // Human-readable description of this transport as per ETSI GS MEC 011 [i.2]. + string description = 113933319; + + TransportType type = 3575610; + + // The name of the protocol used. Being the transport of MB_TOPIC_BASED type, this attribute should be typically set to \"MQTT\" or \"AMQP.\" + string protocol = 452292969; + + // The version of the protocol used as per ETSI GS MEC 011 [i.2]. + string version = 351608024; + + EndPointInfo endpoint = 130489752; + + SecurityInfo security = 412251969; + + ImplSpecificInfo implSpecificInfo = 109027520; + +} diff --git a/proto3/models/mb_transport_info_impl_specific_info.proto b/proto3/models/mb_transport_info_impl_specific_info.proto new file mode 100644 index 0000000000000000000000000000000000000000..79ff0395f38811c9f25bda2ccf7b99e222960fe5 --- /dev/null +++ b/proto3/models/mb_transport_info_impl_specific_info.proto @@ -0,0 +1,29 @@ +/* + ETSI GS MEC 033 IoT API + + ETSI GS MEC 033 IoT API described using OpenAPI. + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec033; + + +message MBTransportInfoImplSpecificInfo { + + // Topics used to publish events related to the established session between the IoT device(s) and the end IoT application(s) on the user transport. + repeated string eventTopics = 131095646; + + // Topics used to publish data generated by the IoT device(s) on the user transport, in order to be consumed by the end IoT application(s). + repeated string uplinkTopics = 68167016; + + // Topics used to publish data generated by the IoT applications(s) on the user transport, in order to be consumed by the end IoT device(s). + repeated string downlinkTopics = 117199843; + +} diff --git a/proto3/models/o_auth2_info.proto b/proto3/models/o_auth2_info.proto new file mode 100644 index 0000000000000000000000000000000000000000..a818d9116bc508fcd303506284a00bfd21cdb724 --- /dev/null +++ b/proto3/models/o_auth2_info.proto @@ -0,0 +1,33 @@ +/* + ETSI GS MEC 033 IoT API + + ETSI GS MEC 033 IoT API described using OpenAPI. + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec033; + + +message OAuth2Info { + + // List of supported OAuth 2.0 grant types. Each entry shall be one of the following permitted values: - OAUTH2_AUTHORIZATION_CODE: Authorization code grant type - OAUTH2_IMPLICIT_GRANT: Implicit grant type - OAUTH2_RESOURCE_OWNER: Resource owner password credentials grant type - OAUTH2_CLIENT_CREDENTIALS: Client credentials grant type Only the value \"OAUTH2_CLIENT_CREDENTIALS\" is supported in the present document. + enum GrantTypesEnum { + GrantTypesEnum_AUTHORIZATION_CODE = 0; + GrantTypesEnum_IMPLICIT_GRANT = 1; + GrantTypesEnum_RESOURCE_OWNER = 2; + GrantTypesEnum_CLIENT_CREDENTIALS = 3; + } + + GrantTypesEnum grantTypes = 303036606; + + // The token endpoint. Shall be present unless the grant type is OAUTH2_IMPLICIT_GRANT. + string tokenEndpoint = 117387951; + +} diff --git a/proto3/models/problem_details.proto b/proto3/models/problem_details.proto new file mode 100644 index 0000000000000000000000000000000000000000..cdac453b8ebbe800efd1e67391e2ac081e7a4446 --- /dev/null +++ b/proto3/models/problem_details.proto @@ -0,0 +1,35 @@ +/* + ETSI GS MEC 033 IoT API + + ETSI GS MEC 033 IoT API described using OpenAPI. + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec033; + + +message ProblemDetails { + + // A URI reference according to IETF RFC 3986 that identifies the problem type + string type = 3575610; + + // A short, human-readable summary of the problem type + string title = 110371416; + + // The HTTP status code for this occurrence of the problem + int32 status = 355610639; + + // A human-readable explanation specific to this occurrence of the problem + string detail = 261482417; + + // A URI reference that identifies the specific occurrence of the problem + string instance = 18257046; + +} diff --git a/proto3/models/registereddevices_get200_response.proto b/proto3/models/registereddevices_get200_response.proto new file mode 100644 index 0000000000000000000000000000000000000000..fb940bdaa97e21f30fe8a86ae22ab81d0385b3d2 --- /dev/null +++ b/proto3/models/registereddevices_get200_response.proto @@ -0,0 +1,23 @@ +/* + ETSI GS MEC 033 IoT API + + ETSI GS MEC 033 IoT API described using OpenAPI. + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec033; + +import public "models/device_info.proto"; + +message RegistereddevicesGET200Response { + + DeviceInfo items = 100526016; + +} diff --git a/proto3/models/registereddevices_post_request.proto b/proto3/models/registereddevices_post_request.proto new file mode 100644 index 0000000000000000000000000000000000000000..86ddce734b03c253949c90f9aad201011a595c29 --- /dev/null +++ b/proto3/models/registereddevices_post_request.proto @@ -0,0 +1,23 @@ +/* + ETSI GS MEC 033 IoT API + + ETSI GS MEC 033 IoT API described using OpenAPI. + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec033; + +import public "models/device_info.proto"; + +message RegistereddevicesPOSTRequest { + + DeviceInfo DeviceInfo = 446908350; + +} diff --git a/proto3/models/registerediotplatforms_by_id_get200_response.proto b/proto3/models/registerediotplatforms_by_id_get200_response.proto new file mode 100644 index 0000000000000000000000000000000000000000..75bb195044f766d3d675366b42641715bbd95965 --- /dev/null +++ b/proto3/models/registerediotplatforms_by_id_get200_response.proto @@ -0,0 +1,23 @@ +/* + ETSI GS MEC 033 IoT API + + ETSI GS MEC 033 IoT API described using OpenAPI. + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec033; + +import public "models/iot_platform_info.proto"; + +message RegisterediotplatformsByIdGET200Response { + + IotPlatformInfo IotPlatformInfo = 182006067; + +} diff --git a/proto3/models/registerediotplatforms_post_request.proto b/proto3/models/registerediotplatforms_post_request.proto new file mode 100644 index 0000000000000000000000000000000000000000..b5277b5651d3fe646b08d849304ad22e81070cd0 --- /dev/null +++ b/proto3/models/registerediotplatforms_post_request.proto @@ -0,0 +1,23 @@ +/* + ETSI GS MEC 033 IoT API + + ETSI GS MEC 033 IoT API described using OpenAPI. + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec033; + +import public "models/iot_platform_info.proto"; + +message RegisterediotplatformsPOSTRequest { + + IotPlatformInfo IoTPlatformInfo = 456786257; + +} diff --git a/proto3/models/security_info.proto b/proto3/models/security_info.proto new file mode 100644 index 0000000000000000000000000000000000000000..6efcd63729726debf01beeeb5fb846e587f06bf9 --- /dev/null +++ b/proto3/models/security_info.proto @@ -0,0 +1,26 @@ +/* + ETSI GS MEC 033 IoT API + + ETSI GS MEC 033 IoT API described using OpenAPI. + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec033; + +import public "models/o_auth2_info.proto"; + +message SecurityInfo { + + OAuth2Info oAuth2Info = 137361497; + + // Extensions for alternative transport mechanisms. These extensions depend on the actual transport and are out of scope of the present document. For instance, such extensions may be used to signal the necessary parameters for the client to use TLS-based authorization defined for alternative transports (see ETSI GS MEC 009 [5] for more information). + string extensions = 198808559; + +} diff --git a/proto3/models/serializer_type.proto b/proto3/models/serializer_type.proto new file mode 100644 index 0000000000000000000000000000000000000000..62b91ba55f7e5ebee15fac89828bc920c943bef5 --- /dev/null +++ b/proto3/models/serializer_type.proto @@ -0,0 +1,22 @@ +/* + ETSI GS MEC 033 IoT API + + ETSI GS MEC 033 IoT API described using OpenAPI. + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec033; + + +enum SerializerType { + SerializerType_JSON = 0; + SerializerType_XML = 1; + SerializerType_PROTOBUF3 = 2; +} diff --git a/proto3/models/traffic_filter.proto b/proto3/models/traffic_filter.proto new file mode 100644 index 0000000000000000000000000000000000000000..b6cec4b1114806f9afe5b8471757b63dc6e757dc --- /dev/null +++ b/proto3/models/traffic_filter.proto @@ -0,0 +1,65 @@ +/* + ETSI GS MEC 033 IoT API + + ETSI GS MEC 033 IoT API described using OpenAPI. + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec033; + + +message TrafficFilter { + + // An IP address or a range of IP addresses. For IPv4, the IP address could be an IP address plus mask, or an individual IP address, or a range of IP addresses. For IPv6, the IP address could be an IP prefix, or a range of IP prefixes. + repeated string srcAddress = 240897392; + + // An IP address or a range of IP addresses. For IPv4, the IP address could be an IP address plus mask, or an individual IP address, or a range of IP addresses. For IPv6, the IP address could be an IP prefix, or a range of IP prefixes. + repeated string dstAddress = 407279216; + + // A port or a range of ports. + repeated string srcPort = 343000958; + + // A port or a range of ports. + repeated string dstPort = 347416553; + + // Specify the protocol of the traffic filter. + repeated string protocol = 452292969; + + // Used for tag based traffic rule. + repeated string tag = 114586; + + // An URI label, in application layer, i.e. in HTTP message, is used to filter the traffic. + repeated string uri = 116076; + + // A customized packet label in network layer, as defined by the owner of the MEC platform, is used to filter the traffic. + repeated string packetLabel = 513464140; + + // Used for GTP tunnel based traffic rule. + repeated string srcTunnelAddress = 86899993; + + // Used for GTP tunnel based traffic rule. + repeated string tgtTunnelAddress = 5196918; + + // Used for GTP tunnel based traffic rule. + repeated string srcTunnelPort = 32028174; + + // Used for GTP tunnel based traffic rule. + repeated string dstTunnelPort = 320657582; + + // Used to match all packets that have the same QCI. + int32 qCI = 110743; + + // Used to match all IPv4 packets that have the same DSCP. + int32 dSCP = 3061020; + + // Used to match all IPv6 packets that have the same TC. + int32 tC = 3663; + +} diff --git a/proto3/models/traffic_rule_descriptor.proto b/proto3/models/traffic_rule_descriptor.proto new file mode 100644 index 0000000000000000000000000000000000000000..f27dab6fe1a675936a73480cfa07439c96fafdaf --- /dev/null +++ b/proto3/models/traffic_rule_descriptor.proto @@ -0,0 +1,48 @@ +/* + ETSI GS MEC 033 IoT API + + ETSI GS MEC 033 IoT API described using OpenAPI. + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec033; + +import public "models/interface_descriptor.proto"; +import public "models/traffic_filter.proto"; + +message TrafficRuleDescriptor { + + // Identifies the traffic rule. + string trafficRuleId = 157373036; + + // Definition of filter type: per FLOW or PACKET If it is per FLOW, the filter matches upstream (e.g. UE->EPC) packets and downstream (e.g. EPC->UE) packets are handled by the same context. + enum FilterTypeEnum { + FilterTypeEnum_FLOW = 0; + FilterTypeEnum_PACKET = 1; + } + + FilterTypeEnum filterType = 479309104; + + // Priority of this traffic rule within the range 0 to 255. If traffic rule conflicts, the one with higher priority take precedence. See note 1. + int32 priority = 91719262; + + // The filter used to identify specific flow/packets that need to be handled by the MEC host. + repeated TrafficFilter trafficFilter = 511989803; + + // Identifies the action of the MEC host data plane, when a packet matches the trafficFilter, the example actions include: DROP, FORWARD_DECAPSULATED, FORWARD_ENCAPSULATED, PASSTHROUGH, DUPLICATE_DECAPSULATED, DUPLICATE_ENCAPSULATED + enum ActionEnum { + ActionEnum_SEE_DESCRIPTION = 0; + } + + ActionEnum action = 349209036; + + InterfaceDescriptor dstInterface = 181384437; + +} diff --git a/proto3/models/transport_info.proto b/proto3/models/transport_info.proto new file mode 100644 index 0000000000000000000000000000000000000000..22ef9f83d11e759a9357ae1f5a49fdec4fd3e5a3 --- /dev/null +++ b/proto3/models/transport_info.proto @@ -0,0 +1,47 @@ +/* + ETSI GS MEC 033 IoT API + + ETSI GS MEC 033 IoT API described using OpenAPI. + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec033; + +import public "models/end_point_info.proto"; +import public "models/security_info.proto"; +import public "models/transport_type.proto"; + +message TransportInfo { + + // The identifier of this transport. + string id = 3355; + + // The name of this transport. + string name = 3373707; + + // Human-readable description of this transport. + string description = 113933319; + + TransportType type = 3575610; + + // The name of the protocol used. Shall be set to \"HTTP\" for a REST API. + string protocol = 452292969; + + // The version of the protocol used. + string version = 351608024; + + EndPointInfo endpoint = 130489752; + + SecurityInfo security = 412251969; + + // Additional implementation specific details of the transport. + string implSpecificInfo = 109027520; + +} diff --git a/proto3/models/transport_type.proto b/proto3/models/transport_type.proto new file mode 100644 index 0000000000000000000000000000000000000000..02d33b4fe07151acfe01a76bdd57a67c10c3f5d7 --- /dev/null +++ b/proto3/models/transport_type.proto @@ -0,0 +1,26 @@ +/* + ETSI GS MEC 033 IoT API + + ETSI GS MEC 033 IoT API described using OpenAPI. + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec033; + + +enum TransportType { + TransportType_REST_HTTP = 0; + TransportType_MB_TOPIC_BASED = 1; + TransportType_MB_ROUTING = 2; + TransportType_MB_PUBSUB = 3; + TransportType_RPC = 4; + TransportType_RPC_STREAMING = 5; + TransportType_WEBSOCKET = 6; +} diff --git a/proto3/models/tunnel_info.proto b/proto3/models/tunnel_info.proto new file mode 100644 index 0000000000000000000000000000000000000000..fc9473c892cca873cfe0ba8ee2336f1aba58082e --- /dev/null +++ b/proto3/models/tunnel_info.proto @@ -0,0 +1,37 @@ +/* + ETSI GS MEC 033 IoT API + + ETSI GS MEC 033 IoT API described using OpenAPI. + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec033; + + +message TunnelInfo { + + // Type of tunnel: GTP-U, GRE, etc. + enum TunnelTypeEnum { + TunnelTypeEnum_GTP_U = 0; + TunnelTypeEnum_GRE = 1; + } + + TunnelTypeEnum tunnelType = 458219585; + + // Destination address of the tunnel. + string tunnelDstAddress = 430153977; + + // Source address of the tunnel. + string tunnelSrcAddress = 263772153; + + // Parameters specific to the tunnel. + string tunnelSpecificData = 160961404; + +} diff --git a/proto3/models/uplink_msg.proto b/proto3/models/uplink_msg.proto new file mode 100644 index 0000000000000000000000000000000000000000..84257a59e0f521544add036a0991c008b70c4b86 --- /dev/null +++ b/proto3/models/uplink_msg.proto @@ -0,0 +1,53 @@ +/* + ETSI GS MEC 033 IoT API + + ETSI GS MEC 033 IoT API described using OpenAPI. + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec033; + +import public "models/serializer_type.proto"; + +message UplinkMsg { + + // Topic where the message containing the data generated by the IoT device(s) should be published, in order to be consumed by the end IoT application(s). + string uplinkTopic = 348567273; + + SerializerType selectedSerializer = 278593909; + + // Indication whether to include the UDP port of the remote IoT device (TRUE) or not (FALSE). + bool includeDevicePort = 312839874; + + // Indication whether to include the IP address of the IoT device (TRUE) or not (FALSE). + bool includeDeviceAddr = 312382002; + + // Indication whether to include the metadata about the IoT device (TRUE) or not (FALSE). + bool includeDeviceMetadata = 228401774; + + // Indication whether to include the PEI of the IoT device (TRUE) or not (FALSE). + bool includePei = 303285069; + + // Indication whether to include the SUPI of the IoT device (TRUE) or not (FALSE). + bool includeSupi = 275136675; + + // Indication whether to include the IMEI of the IoT device (TRUE) or not (FALSE). + bool includeImei = 274830736; + + // Indication whether to include the IMSI of the IoT device (TRUE) or not (FALSE). + bool includeImsi = 274831170; + + // Indication whether to include the ICCID of the IoT device (TRUE) or not (FALSE). + bool includeIccid = 70481508; + + // Indication whether to include the human-readable identified of the IoT device (TRUE) or not (FALSE). + bool includeDeviceId = 501908777; + +} diff --git a/proto3/services/reg_dev_service.proto b/proto3/services/reg_dev_service.proto new file mode 100644 index 0000000000000000000000000000000000000000..c3cdd670418e4f4cb3a0c4443ae6f33cbe83ba0b --- /dev/null +++ b/proto3/services/reg_dev_service.proto @@ -0,0 +1,68 @@ +/* + ETSI GS MEC 033 IoT API + + ETSI GS MEC 033 IoT API described using OpenAPI. + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec033.services.regdevservice; + +import "google/protobuf/empty.proto"; +import public "models/problem_details.proto"; +import public "models/registereddevices_get200_response.proto"; +import public "models/registereddevices_post_request.proto"; + +service RegDevService { + rpc RegistereddevicesByIdDELETE (RegistereddevicesByIdDELETERequest) returns (google.protobuf.Empty); + + rpc RegistereddevicesByIdGET (RegistereddevicesByIdGETRequest) returns (RegistereddevicesPOSTRequest); + + rpc RegistereddevicesByIdPUT (RegistereddevicesByIdPUTRequest) returns (RegistereddevicesPOSTRequest); + + rpc RegistereddevicesGET (RegistereddevicesGETRequest) returns (RegistereddevicesGET200Response); + + rpc RegistereddevicesPOST (RegistereddevicesPOSTRequest) returns (RegistereddevicesPOSTRequest); + +} + +message RegistereddevicesByIdDELETERequest { + // The unique identifier of the registered device. + string registeredDeviceId = 1; + +} + +message RegistereddevicesByIdGETRequest { + // The unique identifier of the registered device. + string registeredDeviceId = 1; + +} + +message RegistereddevicesByIdPUTRequest { + // The unique identifier of the registered device. + string registeredDeviceId = 1; + // One or more updated attributes that are allowed to be changed are included in the DeviceInfo data structure in the payload body of the request. . + RegistereddevicesPOSTRequest registereddevicesPOSTRequest = 2; + +} + +message RegistereddevicesGETRequest { + // Attribute-based filtering parameters according to ETSI GS MEC 009 [i.1]. The API producer shall support receiving the following filtering parameters as part of the URI query string: \"(eq,enabled,TRUE)\". + string filter = 1; + // The list may contain one or more of the following attributes from the DeviceInfo data type: - deviceMetadata - gpsi - msisdn - deviceId - requestedMecTrafficRule - requestedIotPlatformId - requestedUserTransportId + repeated string fields = 2; + +} + +message RegistereddevicesPOSTRequest { + // Payload body in the request contains the information associated to the IoT device to be registered. + RegistereddevicesPOSTRequest registereddevicesPOSTRequest = 1; + +} + diff --git a/proto3/services/reg_iot_plat_service.proto b/proto3/services/reg_iot_plat_service.proto new file mode 100644 index 0000000000000000000000000000000000000000..cbbba4952f000fea732d1b05d423b13d7d8ca18b --- /dev/null +++ b/proto3/services/reg_iot_plat_service.proto @@ -0,0 +1,73 @@ +/* + ETSI GS MEC 033 IoT API + + ETSI GS MEC 033 IoT API described using OpenAPI. + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec033.services.regiotplatservice; + +import "google/protobuf/empty.proto"; +import public "models/iot_platform_info.proto"; +import public "models/problem_details.proto"; +import public "models/registerediotplatforms_by_id_get200_response.proto"; +import public "models/registerediotplatforms_post_request.proto"; + +service RegIotPlatService { + rpc RegisterediotplatformsByIdDELETE (RegisterediotplatformsByIdDELETERequest) returns (google.protobuf.Empty); + + rpc RegisterediotplatformsByIdGET (RegisterediotplatformsByIdGETRequest) returns (RegisterediotplatformsByIdGET200Response); + + rpc RegisterediotplatformsByIdPUT (RegisterediotplatformsByIdPUTRequest) returns (RegisterediotplatformsByIdGET200Response); + + rpc RegisterediotplatformsGET (RegisterediotplatformsGETRequest) returns (RegisterediotplatformsGETResponse); + + rpc RegisterediotplatformsPOST (RegisterediotplatformsPOSTRequest) returns (RegisterediotplatformsPOSTRequest); + +} + +message RegisterediotplatformsByIdDELETERequest { + // The unique identifier of the registered IoT platform. + string registeredIotPlatformId = 1; + +} + +message RegisterediotplatformsByIdGETRequest { + // The unique identifier of the registered IoT platform. + string registeredIotPlatformId = 1; + // The list may contain one or more of the following attributes from the IotPlatformInfo data type: - userTransportInfo - customServiceTransportInfo + repeated string fields = 2; + +} + +message RegisterediotplatformsByIdPUTRequest { + // The unique identifier of the registered IoT platform. + string registeredIotPlatformId = 1; + // One or more updated attributes that are allowed to be changed are included in the IotPlatformInfo data structure in the payload body of the request. . + RegisterediotplatformsByIdGET200Response registerediotplatformsByIdGET200Response = 2; + +} + +message RegisterediotplatformsGETRequest { + // The list shall contain the following attributes from the IotPlatformInfo data type: - iotPlatformId - enabled + repeated string fields = 1; + +} + +message RegisterediotplatformsGETResponse { + repeated IotPlatformInfo data = 1; +} + +message RegisterediotplatformsPOSTRequest { + // Payload body in the request contains the information associated to the IoT platform to be registered. + RegisterediotplatformsPOSTRequest registerediotplatformsPOSTRequest = 1; + +} +