MECwiki - User contributions [en]

MEC Deployment Trials Framework

2018-09-07T10:10:04Z

Featherstone: Edits following acceptance of MEC(18)000369, 370r1 & 371r1 at MEC F2F#2

<big>
After the successful campaign of MEC Proof of Concepts (PoC), ETSI ISG MEC has developed the '''MEC Deployment Trial (MDT) Framework'''.

The goal of MDTs is to demonstrate the '''viability of MEC in commercial trials/deployments''' and to provide feedback to the standardisation work.
</big>

== How does it work ==

The MDT Framework describes the process and criteria that a MDT demonstration must adhere to. The process aligns with that defined for MEC PoCs. A key differentiator to PoCs is that '''MDT proposals are expected to be deployed/tested in a commercial network or a field trial network'''.

== How to propose a MEC Deployment Trial ==

A MDT Proposal can be submitted by a MDT team that will have at a minimum 2 different stakeholder members among:
* network operator;
* infrastructure provider;
* content/application provider.
The MDT Point of Contact will be an ISG MEC Member or an ISG MEC Participant.

MDT proposals are expected to be scoped around PoC Topics identified and agreed by the ISG MEC. See details and current list [https://mecwiki.etsi.org/index.php?title=PoC_Topics here].

MDT proposals are expected to be deployed in a commercial network or a field trial network relying on the principles of the MEC reference architecture and APIs as much as applicable for the demonstrated use case.

The MDT Team will commit to demonstrating their MDT Proposal at a public event, e.g. Public Exhibition, ISG MEC meeting, or other events outlined in the MDT Proposal.

To submit a MDT Proposal, the Proposal template must be completed and uploaded on the ETSI Portal as a contribution to ISG MEC and a link to the contribution emailed to:

MEC_PoC_support_team at etsi.org

<center>
<big>
'''[https://mecwiki.etsi.org/images/MEC_Deployment_Trial_Proposal.doc Download the MDT Proposal template]'''
</big>
</center>

== How to report a the concluded MDT ==

To report on the conclusion of a MDT, the Report template must be completed and emailed to:

MEC_PoC_support_team at etsi.org

<center>
<big>
'''[https://mecwiki.etsi.org/images/MEC_Deployment_Trial_Report_Template.doc Download the MDT Report template]'''
</big>
</center>

OpenAPI development guidelines

2017-12-11T22:25:31Z

Featherstone: /* General guidelines */

OpenAPI development guidelines for ETSI MEC ISG API specifications.
More general recommendations can be found at [https://forge.etsi.org/wiki/index.php/Main_Page Forge OpenAPI Guidelines].

= How to review the latest versions =

<big>If you are interested to access and download the raw YAML files built for each interface (currently only MEC-012 is built in this manner, the other interfaces will follow) visit [https://forge.etsi.org/jenkins/view/all/job/MEC%20-%20Multi-access%20Edge%20Computing/ latest succesful builds].</big>

<big>[[ShortGuideToReviewInGerrit|A short guide to review in Gerrit]]</big>

If you are willing to contribute or if you want more information, contact [mailto:cti_support@etsi.org?subject=MEC%20openapis%20development: ETSI CTI]. ETSI CTI have also made a [https://www.youtube.com/watch?v=YXO0R61Dcg8 YouTube] tutorial available, which although based on NFV rather than MEC provides a valuable overall guide.

= API development =

== General guidelines ==

MEC APIs are currently described using the [https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md OpenAPI 2.0 specification]. Members of the ETSI MEC ISG can view a tutorial [https://docbox.etsi.org/ISG/MEC/05-CONTRIBUTIONS/2017//MEC(17)000541_MEC023_Creating_a_OpenAPI_spec_compliant_API_description.pptx presentation] on creating a OpenAPI based description using the MEC-011 Mp1 API as the basis. That can be made available outside the ISG on request.

A migration to the latest version of the [https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md OpenAPI 3.0 specification] is being actively pursued within the ISG. However, it is desirable that auto-generation of client and server stubs are supported through [https://github.com/swagger-api/swagger-codegen swagger-codegen], which is still in development (reference 3.0.0_enhancements branch).

=== Root API files ===

Since the specification requires the <code>apiVersion</code> be after <code>apiName</code> in the resource path, each API will have a separate OpenAPI root file.

In detail, paths are required to start with:
<pre>
<apiRoot>/<apiName>/<apiVersion>
</pre>

the only way to model this with OAS is using separate files for each interface. This will also help readability and clarity.

=== Definitions ===
Definitions are currently not shared across API descriptions and there is no cross-referencing. This is also the case in the group specifications themselves.

=== Resources ===
It is encouraged to create a separate file for each resource (as is the case for Mp1 and Location), although only the overall description file is provided for most APIs.

== Branching strategy ==

* Within the repository there will be a branch for each ''active'' version of the interfaces. A version is ''active'' if it is still under maintenance in the WG.
* Git tags will be used to label a commit on a branch with a specific revision of the deliberable.

== Folder structure and file names ==

=== Repository structure ===

<pre>
repository_root i.e. MEC
|- Group Specification (GS) x e.g. MEC.GS-011
|- Readme.md General API information
|- APIx.json Auto-generated JSON
|- APIx.yaml Main OAS file (auto-generated using the APIx.split.yaml file: multi-file-swagger Mp1.split.yaml > Mp1.json), e.g. Mp1.yaml
|- APIx.split.yaml Definition file split into its component parts, to bring it together use [https://github.com/mohsen1/multi-file-swagger-example multi-file-swagger]
|- definitions
| - DataType1.yaml e.g. CurrentTime.yaml
| - DataType2.yaml
|- examples Example responses
| - Example1.yaml e.g. ServiceInfo.yaml
| - Example2.yaml
|- externalDocs Links to external docs, i.e. the GS
| - index.yaml
|- info General info regarding API, e.g. Copyright
| - index.yaml
|- parameters API Body/Query/Path Parameters
| - Parameter1.yaml e.g. Body.DnsRule.yaml
| - Parameter2.yaml e.g. Path.DnsRuleId.yaml
|- paths Paths associated with the API
| - PathA.yaml High level path, e.g. Services.yaml
| - PathA.{method}.yaml Lower level path, e.g. Services.GET.yaml
|- Group Specification y
|- ...
|- Group Specification z
|- ...
|- Readme.md
|- LICENSE
</pre>

=== File names ===

The naming schema provided in the examples for the "Repository structure" above is followed.

OpenAPI development guidelines

2017-12-11T22:21:32Z

Featherstone:

OpenAPI development guidelines for ETSI MEC ISG API specifications.
More general recommendations can be found at [https://forge.etsi.org/wiki/index.php/Main_Page Forge OpenAPI Guidelines].

= How to review the latest versions =

<big>If you are interested to access and download the raw YAML files built for each interface (currently only MEC-012 is built in this manner, the other interfaces will follow) visit [https://forge.etsi.org/jenkins/view/all/job/MEC%20-%20Multi-access%20Edge%20Computing/ latest succesful builds].</big>

<big>[[ShortGuideToReviewInGerrit|A short guide to review in Gerrit]]</big>

If you are willing to contribute or if you want more information, contact [mailto:cti_support@etsi.org?subject=MEC%20openapis%20development: ETSI CTI]. ETSI CTI have also made a [https://www.youtube.com/watch?v=YXO0R61Dcg8 YouTube] tutorial available, which although based on NFV rather than MEC provides a valuable overall guide.

= API development =

== General guidelines ==

MEC APIs are currently described using the [https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md OpenAPI 2.0 specification]. Members of the ETSI MEC ISG can view a tutorial [https://docbox.etsi.org/ISG/MEC/05-CONTRIBUTIONS/2017//MEC(17)000541_MEC023_Creating_a_OpenAPI_spec_compliant_API_description.pptx presentation]. That can be made available outside the ISG on request.

A migration to the latest version of the [https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md OpenAPI 3.0 specification] is being actively pursued within the ISG. However, it is desirable that auto-generation of client and server stubs are supported through [https://github.com/swagger-api/swagger-codegen swagger-codegen], which is still in development (reference 3.0.0_enhancements branch).

=== Root API files ===

Since the specification requires the <code>apiVersion</code> be after <code>apiName</code> in the resource path, each interface will have a separate OpenAPI root file.

In details, paths are required to start with:
<pre>
<apiRoot>/<apiName>/<apiVersion>
</pre>

the only way to model this with OAS is using separate files for each interface. This will also help readability and clarity.

=== Definitions ===
Definitions are currently not shared across API descriptions and there is no cross referencing. This is also the case in the group specifications themselves.

=== Resources ===
It's encouraged to create a separate file for each resource (as is the case for Mp1 and Location), although only the complete description file is provided for several APIs.

== Branching strategy ==

* Within the repository there will be a branch for each ''active'' version of the interfaces. A version is ''active'' if it is still under maintenance in the WG.
* Git tags will be used to label a commit on a branch with a specific revision of the deliberable.

== Folder structure and file names ==

=== Repository structure ===

<pre>
repository_root i.e. MEC
|- Group Specification (GS) x e.g. MEC.GS-011
|- Readme.md General API information
|- APIx.json Auto-generated JSON
|- APIx.yaml Main OAS file (auto-generated using the APIx.split.yaml file: multi-file-swagger Mp1.split.yaml > Mp1.json), e.g. Mp1.yaml
|- APIx.split.yaml Definition file split into its component parts, to bring it together use [https://github.com/mohsen1/multi-file-swagger-example multi-file-swagger]
|- definitions
| - DataType1.yaml e.g. CurrentTime.yaml
| - DataType2.yaml
|- examples Example responses
| - Example1.yaml e.g. ServiceInfo.yaml
| - Example2.yaml
|- externalDocs Links to external docs, i.e. the GS
| - index.yaml
|- info General info regarding API, e.g. Copyright
| - index.yaml
|- parameters API Body/Query/Path Parameters
| - Parameter1.yaml e.g. Body.DnsRule.yaml
| - Parameter2.yaml e.g. Path.DnsRuleId.yaml
|- paths Paths associated with the API
| - PathA.yaml High level path, e.g. Services.yaml
| - PathA.{method}.yaml Lower level path, e.g. Services.GET.yaml
|- Group Specification y
|- ...
|- Group Specification z
|- ...
|- Readme.md
|- LICENSE
</pre>

=== File names ===

The naming schema provided in the examples for the "Repository structure" above is followed.

OpenAPI development guidelines

2017-12-11T21:53:34Z

Featherstone: /* General guidelines */

OpenAPI development guidelines for ETSI MEC ISG API specifications.
More general recommendations can be found at [https://forge.etsi.org/wiki/index.php/OpenAPI_Guidelines Forge OpenAPI Gudelines].

= How to review the latest versions =

<big>If you are interested to access and download the raw YAML files built for each interface (currently only MEC-012 is built in this manner, the other interfaces will follow) visit [https://forge.etsi.org/jenkins/view/all/job/MEC%20-%20Multi-access%20Edge%20Computing/ latest succesful builds].</big>

<big>[[ShortGuideToReviewInGerrit|A short guide to review in Gerrit]]</big>

If you are willing to contribute or if you want more information, contact [mailto:cti_support@etsi.org?subject=MEC%20openapis%20development: ETSI CTI].

= API development =

== General guidelines ==

MEC APIs are currently described using the [https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md OpenAPI 2.0 specification].

A migration to the latest version of the [https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md OpenAPI 3.0 specification] is being actively pursued within the ISG. However, it is desirable that auto-generation of client and server stubs are supported through [https://github.com/swagger-api/swagger-codegen swagger-codegen], which is still in development (reference 3.0.0_enhancements branch).

=== Root API files ===

Since the specification requires the <code>apiVersion</code> be after <code>apiName</code> in the resource path, each interface will have a separate OpenAPI root file.

In details, paths are required to start with:
<pre>
<apiRoot>/<apiName>/<apiVersion>
</pre>

the only way to model this with OAS is using separate files for each interface. This will also help readability and clarity.

=== Definitions ===
Definitions are currently not shared across API descriptions and there is no cross referencing. This is also the case in the group specifications themselves.

=== Resources ===
It's encouraged to create a separate file for each resource (as is the case for Mp1 and Location), although only the complete description file is provided for several APIs.

== Branching strategy ==

* Within the repository there will be a branch for each ''active'' version of the interfaces. A version is ''active'' if it is still under maintenance in the WG.
* Git tags will be used to label a commit on a branch with a specific revision of the deliberable.

== Folder structure and file names ==

=== Repository structure ===

<pre>
repository_root i.e. MEC
|- Group Specification (GS) x e.g. MEC.GS-011
|- Readme.md General API information
|- APIx.json Auto-generated JSON
|- APIx.yaml Main OAS file (auto-generated using the APIx.split.yaml file: multi-file-swagger Mp1.split.yaml > Mp1.json), e.g. Mp1.yaml
|- APIx.split.yaml Definition file split into its component parts, to bring it together use [https://github.com/mohsen1/multi-file-swagger-example multi-file-swagger]
|- definitions
| - DataType1.yaml e.g. CurrentTime.yaml
| - DataType2.yaml
|- examples Example responses
| - Example1.yaml e.g. ServiceInfo.yaml
| - Example2.yaml
|- externalDocs Links to external docs, i.e. the GS
| - index.yaml
|- info General info regarding API, e.g. Copyright
| - index.yaml
|- parameters API Body/Query/Path Parameters
| - Parameter1.yaml e.g. Body.DnsRule.yaml
| - Parameter2.yaml e.g. Path.DnsRuleId.yaml
|- paths Paths associated with the API
| - PathA.yaml High level path, e.g. Services.yaml
| - PathA.{method}.yaml Lower level path, e.g. Services.GET.yaml
|- Group Specification y
|- ...
|- Group Specification z
|- ...
|- Readme.md
|- LICENSE
</pre>

=== File names ===

The naming schema provided in the examples for the "Repository structure" above is followed.

OpenAPI development guidelines

2017-12-11T21:48:48Z

Featherstone: /* Repository structure */

OpenAPI development guidelines for ETSI MEC ISG API specifications.
More general recommendations can be found at [https://forge.etsi.org/wiki/index.php/OpenAPI_Guidelines Forge OpenAPI Gudelines].

= How to review the latest versions =

<big>If you are interested to access and download the raw YAML files built for each interface (currently only MEC-012 is built in this manner, the other interfaces will follow) visit [https://forge.etsi.org/jenkins/view/all/job/MEC%20-%20Multi-access%20Edge%20Computing/ latest succesful builds].</big>

<big>[[ShortGuideToReviewInGerrit|A short guide to review in Gerrit]]</big>

If you are willing to contribute or if you want more information, contact [mailto:cti_support@etsi.org?subject=MEC%20openapis%20development: ETSI CTI].

= API development =

== General guidelines ==

MEC APIs are currently described using the OpenAPI 2.0 specification.
Click [https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md here] to find the official reference.

A migration to the OpenAPI 3.0 specification is being actively pursued within the ISG. However, it is desirable that auto-generation of client and server stubs are supported through swagger-codegen, which is still in development.

=== Root API files ===

Since the specification requires the <code>apiVersion</code> be after <code>apiName</code> in the resource path, each interface will have a separate OpenAPI root file.

In details, paths are required to start with:
<pre>
<apiRoot>/<apiName>/<apiVersion>
</pre>

the only way to model this with OAS is using separate files for each interface. This will also help readability and clarity.

=== Definitions ===
Definitions are currently not shared across API descriptions and there is no cross referencing. This is also the case in the group specifications themselves.

=== Resources ===
It's encouraged to create a separate file for each resource (as is the case for Mp1 and Location), although only the complete description file is provided for several APIs.

== Branching strategy ==

* Within the repository there will be a branch for each ''active'' version of the interfaces. A version is ''active'' if it is still under maintenance in the WG.
* Git tags will be used to label a commit on a branch with a specific revision of the deliberable.

== Folder structure and file names ==

=== Repository structure ===

<pre>
repository_root i.e. MEC
|- Group Specification (GS) x e.g. MEC.GS-011
|- Readme.md General API information
|- APIx.json Auto-generated JSON
|- APIx.yaml Main OAS file (auto-generated using the APIx.split.yaml file: multi-file-swagger Mp1.split.yaml > Mp1.json), e.g. Mp1.yaml
|- APIx.split.yaml Definition file split into its component parts, to bring it together use [https://github.com/mohsen1/multi-file-swagger-example multi-file-swagger]
|- definitions
| - DataType1.yaml e.g. CurrentTime.yaml
| - DataType2.yaml
|- examples Example responses
| - Example1.yaml e.g. ServiceInfo.yaml
| - Example2.yaml
|- externalDocs Links to external docs, i.e. the GS
| - index.yaml
|- info General info regarding API, e.g. Copyright
| - index.yaml
|- parameters API Body/Query/Path Parameters
| - Parameter1.yaml e.g. Body.DnsRule.yaml
| - Parameter2.yaml e.g. Path.DnsRuleId.yaml
|- paths Paths associated with the API
| - PathA.yaml High level path, e.g. Services.yaml
| - PathA.{method}.yaml Lower level path, e.g. Services.GET.yaml
|- Group Specification y
|- ...
|- Group Specification z
|- ...
|- Readme.md
|- LICENSE
</pre>

=== File names ===

The naming schema provided in the examples for the "Repository structure" above is followed.

OpenAPI development guidelines

2017-12-11T21:48:02Z

Featherstone:

OpenAPI development guidelines for ETSI MEC ISG API specifications.
More general recommendations can be found at [https://forge.etsi.org/wiki/index.php/OpenAPI_Guidelines Forge OpenAPI Gudelines].

= How to review the latest versions =

<big>If you are interested to access and download the raw YAML files built for each interface (currently only MEC-012 is built in this manner, the other interfaces will follow) visit [https://forge.etsi.org/jenkins/view/all/job/MEC%20-%20Multi-access%20Edge%20Computing/ latest succesful builds].</big>

<big>[[ShortGuideToReviewInGerrit|A short guide to review in Gerrit]]</big>

If you are willing to contribute or if you want more information, contact [mailto:cti_support@etsi.org?subject=MEC%20openapis%20development: ETSI CTI].

= API development =

== General guidelines ==

MEC APIs are currently described using the OpenAPI 2.0 specification.
Click [https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md here] to find the official reference.

A migration to the OpenAPI 3.0 specification is being actively pursued within the ISG. However, it is desirable that auto-generation of client and server stubs are supported through swagger-codegen, which is still in development.

=== Root API files ===

Since the specification requires the <code>apiVersion</code> be after <code>apiName</code> in the resource path, each interface will have a separate OpenAPI root file.

In details, paths are required to start with:
<pre>
<apiRoot>/<apiName>/<apiVersion>
</pre>

the only way to model this with OAS is using separate files for each interface. This will also help readability and clarity.

=== Definitions ===
Definitions are currently not shared across API descriptions and there is no cross referencing. This is also the case in the group specifications themselves.

=== Resources ===
It's encouraged to create a separate file for each resource (as is the case for Mp1 and Location), although only the complete description file is provided for several APIs.

== Branching strategy ==

* Within the repository there will be a branch for each ''active'' version of the interfaces. A version is ''active'' if it is still under maintenance in the WG.
* Git tags will be used to label a commit on a branch with a specific revision of the deliberable.

== Folder structure and file names ==

=== Repository structure ===

<pre>
repository_root i.e. MEC
|- Group Specification (GS) x e.g. MEC.GS-011
|- Readme.md General API information
|- APIx.json Auto-generated JSON
'''|- APIx.yaml Main OAS file (auto-generated using the APIx.split.yaml file: multi-file-swagger Mp1.split.yaml > Mp1.json), e.g. Mp1.yaml'''
|- APIx.split.yaml Definition file split into its component parts, to bring it together use [https://github.com/mohsen1/multi-file-swagger-example multi-file-swagger]
|- definitions
| - DataType1.yaml e.g. CurrentTime.yaml
| - DataType2.yaml
|- examples Example responses
| - Example1.yaml e.g. ServiceInfo.yaml
| - Example2.yaml
|- externalDocs Links to external docs, i.e. the GS
| - index.yaml
|- info General info regarding API, e.g. Copyright
| - index.yaml
|- parameters API Body/Query/Path Parameters
| - Parameter1.yaml e.g. Body.DnsRule.yaml
| - Parameter2.yaml e.g. Path.DnsRuleId.yaml
|- paths Paths associated with the API
| - PathA.yaml High level path, e.g. Services.yaml
| - PathA.{method}.yaml Lower level path, e.g. Services.GET.yaml
|- Group Specification y
|- ...
|- Group Specification z
|- ...
|- Readme.md
|- LICENSE
</pre>

=== File names ===

The naming schema provided in the examples for the "Repository structure" above is followed.

OpenAPI development guidelines

2017-10-27T15:02:12Z

Featherstone: Created page with "OpenAPI development guidelines for ETSI ISG MEC. More general recommendations can be found at [https://forge.etsi.org/wiki/index.php/OpenAPI_Guidelines Forge OpenAPI Guidelines]."

OpenAPI development guidelines for ETSI ISG MEC.
More general recommendations can be found at [https://forge.etsi.org/wiki/index.php/OpenAPI_Guidelines Forge OpenAPI Guidelines].