1、 ETSI TS 129 501 V15.0.1 (2018-07) 5G; 5G System; Principles and Guidelines for Services Definition; Stage 3 (3GPP TS 29.501 version 15.0.1 Release 15) TECHNICAL SPECIFICATION ETSI ETSI TS 129 501 V15.0.1 (2018-07)13GPP TS 29.501 version 15.0.1 Release 15Reference DTS/TSGC-0429501vf01 Keywords 5G ET
2、SI 650 Route des Lucioles F-06921 Sophia Antipolis Cedex - FRANCE Tel.: +33 4 92 94 42 00 Fax: +33 4 93 65 47 16 Siret N 348 623 562 00017 - NAF 742 C Association but non lucratif enregistre la Sous-Prfecture de Grasse (06) N 7803/88 Important notice The present document can be downloaded from: http
3、:/www.etsi.org/standards-search The present document may be made available in electronic versions and/or in print. The content of any electronic and/or print versions of the present document shall not be modified without the prior written authorization of ETSI. In case of any existing or perceived d
4、ifference in contents between such versions and/or in print, the only prevailing document is the print of the Portable Document Format (PDF) version kept on a specific network drive within ETSI Secretariat. Users of the present document should be aware that the document may be subject to revision or
5、 change of status. Information on the current status of this and other ETSI documents is available at https:/portal.etsi.org/TB/ETSIDeliverableStatus.aspx If you find errors in the present document, please send your comment to one of the following services: https:/portal.etsi.org/People/CommiteeSupp
6、ortStaff.aspx Copyright Notification No part may be reproduced or utilized in any form or by any means, electronic or mechanical, including photocopying and microfilm except as authorized by written permission of ETSI. The content of the PDF version shall not be modified without the written authoriz
7、ation of ETSI. The copyright and the foregoing restriction extend to reproduction in all media. ETSI 2018. All rights reserved. DECTTM, PLUGTESTSTM, UMTSTMand the ETSI logo are trademarks of ETSI registered for the benefit of its Members. 3GPPTM and LTETMare trademarks of ETSI registered for the ben
8、efit of its Members and of the 3GPP Organizational Partners. oneM2M logo is protected for the benefit of its Members. GSMand the GSM logo are trademarks registered and owned by the GSM Association. ETSI ETSI TS 129 501 V15.0.1 (2018-07)23GPP TS 29.501 version 15.0.1 Release 15Intellectual Property R
9、ights Essential patents IPRs essential or potentially essential to normative deliverables may have been declared to ETSI. The information pertaining to these essential IPRs, if any, is publicly available for ETSI members and non-members, and can be found in ETSI SR 000 314: “Intellectual Property Ri
10、ghts (IPRs); Essential, or potentially Essential, IPRs notified to ETSI in respect of ETSI standards“, which is available from the ETSI Secretariat. Latest updates are available on the ETSI Web server (https:/ipr.etsi.org/). Pursuant to the ETSI IPR Policy, no investigation, including IPR searches,
11、has been carried out by ETSI. No guarantee can be given as to the existence of other IPRs not referenced in ETSI SR 000 314 (or the updates on the ETSI Web server) which are, or may be, or may become, essential to the present document. Trademarks The present document may include trademarks and/or tr
12、adenames which are asserted and/or registered by their owners. ETSI claims no ownership of these except for any which are indicated as being the property of ETSI, and conveys no right to use or reproduce any trademark and/or tradename. Mention of those trademarks in the present document does not con
13、stitute an endorsement by ETSI of products, services or organizations associated with those trademarks. Foreword This Technical Specification (TS) has been produced by ETSI 3rd Generation Partnership Project (3GPP). The present document may refer to technical specifications or reports using their 3G
14、PP identities, UMTS identities or GSM identities. These should be interpreted as being references to the corresponding ETSI deliverables. The cross reference between GSM, UMTS, 3GPP and ETSI identities can be found under http:/webapp.etsi.org/key/queryform.asp. Modal verbs terminology In the present
15、 document “shall“, “shall not“, “should“, “should not“, “may“, “need not“, “will“, “will not“, “can“ and “cannot“ are to be interpreted as described in clause 3.2 of the ETSI Drafting Rules (Verbal forms for the expression of provisions). “must“ and “must not“ are NOT allowed in ETSI deliverables ex
16、cept when used in direct citation. ETSI ETSI TS 129 501 V15.0.1 (2018-07)33GPP TS 29.501 version 15.0.1 Release 15Contents Intellectual Property Rights 2g3Foreword . 2g3Modal verbs terminology 2g3Foreword . 6g31 Scope 7g32 References 7g33 Definitions and abbreviations . 8g33.1 Definitions 8g33.2 Abb
17、reviations . 8g34 Design Principles for 5GC SBI APIs . 8g34.1 General Principles 8g34.2 API Design Style and REST Implementation Levels . 9g34.2.1 General 9g34.2.2 API Design Principles for Query Operation . 9g34.2.3 API Design Principles for Delete Operation . 9g34.3 Version Control 10g34.3.1 Struc
18、ture of API version numbers . 10g34.3.1.1 API version number format . 10g34.3.1.2 Rules for incrementing field values. 10g34.3.1.3 Visibility of the API version number fields 10g34.3.1.4 Relation to the Technical Specification version number . 11g34.3.1.5 Discovery of the supported versions . 11g34.
19、4 URI Structure . 11g34.4.1 Resource URI structure . 11g34.4.2 Custom operations URI structure 12g34.4.3 Callback URI structure . 12g34.5 Resource Representation and Content Format Negotiation 12g34.5.1 Resource Representation . 12g34.5.2 Content Format Negotiation . 12g34.6 Use of HTTP Methods . 13
20、g34.6.1 Use of Request/Response Communication . 13g34.6.1.1 CRUD . 13g34.6.1.1.1 Creating a Resource . 13g34.6.1.1.1.1 General . 13g34.6.1.1.1.2 Creating a Resource using POST . 13g34.6.1.1.1.3 Creating a Resource using PUT . 14g34.6.1.1.2 Reading a Resource . 14g34.6.1.1.2.1 Reading a Single Resour
21、ce 14g34.6.1.1.2.2 Querying a Set of Resources 15g34.6.1.1.3 Updating a Resource 16g34.6.1.1.3.1 Usage of HTTP PUT 16g34.6.1.1.3.2 Usage of HTTP PATCH 16g34.6.1.1.4 Deleting a Resource . 17g34.6.1.1.5 Query Parameters 18g34.6.1.2 Custom Operations 18g34.6.1.3 Use of Asynchronous Operations 18g34.6.1
22、.4 Special provisions to support the seamless change of AMF as NF service producer 18g34.6.2 Use of Subscribe/Notify Communication . 18g34.6.2.1 General 18g34.6.2.2 Management of Subscriptions . 19g34.6.2.2.1 General 19g34.6.2.2.2 Creation of a Subscription . 19g34.6.2.2.3 Modify a subscription 20g3
23、4.6.2.2.3.1 Modification of a Subscription Using HTTP PUT. 20g3ETSI ETSI TS 129 501 V15.0.1 (2018-07)43GPP TS 29.501 version 15.0.1 Release 154.6.2.2.3.2 Modification of a Subscription Using HTTP PATCH . 20g34.6.2.2.4 Delete a subscription . 21g34.6.2.3 Notifications 21g34.6.2.4 Special provisions t
24、o support the seamless change of AMF as NF service consumer 22g34.7 HATEOAS . 22g34.7.1 General 22g34.7.2 3GPP hypermedia format 22g34.7.3 Advertising legitimate application state transitions 23g34.7.4 Inferring link relation semantic . 23g34.7.5 Common Relation Types 23g34.7.5.1 Introduction . 23g3
25、4.7.5.2 Registered relation types . 24g34.7.5.3 Extension relation types 24g34.7.6 Negotiating the support of optional HATEOAS features . 24g34.8 Error Responses 24g34.9 Transferring multiple resources to a NF Service Consumer . 26g34.9.1 General 26g34.9.2 Direct Delivery . 26g34.9.3 Direct Delivery
26、 with Iterations . 26g34.9.4 Indirect Delivery . 27g34.9.5 Indirect Delivery with HTTP/2 Server Push . 27g34.9.6 Criteria for choosing the transfer method . 29g35 Documenting 5GC SBI APIs . 29g35.1 Naming Conventions 29g35.1.1 Case Conventions . 29g35.1.2 API Naming Conventions . 30g35.1.3 Conventio
27、ns for URI Parts 30g35.1.3.1 Introduction . 30g35.1.3.2 URI Path Segment Naming Conventions 31g35.1.3.3 URI Query Naming Conventions 31g35.1.4 Conventions for Names in Data Structures . 32g35.2 API Definition 32g35.2.1 Resource Structure 32g35.2.2 Resources and HTTP Methods . 33g35.2.3 Representing
28、RPC as Custom Operations on Resources 35g35.2.4 Data Models 36g35.2.4.1 General 36g35.2.4.2 Structured data types . 37g35.2.4.3 Simple data types and enumerations . 38g35.2.4.4 Binary Data . 38g35.2.4.5 Data types describing alternative data types or combinations of data types . 38g35.2.5 Relation t
29、ypes . 39g35.3 Open API specification files . 40g35.3.1 General 40g35.3.2 Formatting of OpenAPI files 40g35.3.3 Info 40g35.3.4 externalDocs . 40g35.3.5 Servers 40g35.3.6 References to other 3GPP-defined Open API specification files 41g35.3.7 Server-initiated communication 41g35.3.8 Describing the bo
30、dy of HTTP PATCH requests . 42g35.3.8.1 General 42g35.3.8.2 JSON Merge Patch 42g35.3.8.3 JSON PATCH . 42g35.3.9 Structured data types . 43g35.3.10 Data types describing alternative data types or combinations of data types . 44g35.3.11 Error Responses 46g35.3.12 Enumerations 47g3Annex A (informative)
31、: TS Skeleton Template 48g3ETSI ETSI TS 129 501 V15.0.1 (2018-07)53GPP TS 29.501 version 15.0.1 Release 15Annex B (informative): Backward Incompatible Changes . 49g3Annex C (Informative): Resource modelling 50g3C.1 Document . 50g3C.2 Collection . 50g3C.3 Store . 50g3C.4 Custom operation . 51g3Annex
32、D (informative): Open API example file for Patch 52g3Annex E (informative): Change history . 55g3History 56g3ETSI ETSI TS 129 501 V15.0.1 (2018-07)63GPP TS 29.501 version 15.0.1 Release 15Foreword This Technical Specification has been produced by the 3rd Generation Partnership Project (3GPP). The co
33、ntents of the present document are subject to continuing work within the TSG and may change following formal TSG approval. Should the TSG modify the contents of the present document, it will be re-released by the TSG with an identifying change of release date and an increase in version number as fol
34、lows: Version x.y.z where: x the first digit: 1 presented to TSG for information; 2 presented to TSG for approval; 3 or greater indicates TSG approved document under change control. y the second digit is incremented for all changes of substance, i.e. technical enhancements, corrections, updates, etc
35、. z the third digit is incremented when editorial only changes have been incorporated in the document. ETSI ETSI TS 129 501 V15.0.1 (2018-07)73GPP TS 29.501 version 15.0.1 Release 151 Scope The present document defines design principles and documentation guidelines for 5GC SBI APIs. These principles
36、 and guidelines should be followed when drafting the 5G System SBI Stage 3 specifications. 2 References The following documents contain provisions which, through reference in this text, constitute provisions of the present document. - References are either specific (identified by date of publication
37、, edition number, version number, etc.) or non-specific. - For a specific reference, subsequent revisions do not apply. - For a non-specific reference, the latest version applies. In the case of a reference to a 3GPP document (including a GSM document), a non-specific reference implicitly refers to
38、the latest version of that document in the same Release as the present document. 1 3GPP TR 21.905: “Vocabulary for 3GPP Specifications“. 2 3GPP TS 29.500: “5G System; Technical Realization of Service Based Architecture; Stage 3“. 3 IETF RFC 8259: “The JavaScript Object Notation (JSON) Data Interchan
39、ge Format“. 4 OpenAPI: “OpenAPI 3.0.0 Specification“, https:/ 5 3GPP TS 29.571: “5G System; Common Data Types for Service Based Interfaces Stage 3“. 6 IETF RFC 7231: “Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content“ 7 IETF RFC 7396: “JSON Merge Patch“. 8 IETF RFC 6902: “JavaScript Obje
40、ct Notation (JSON) Patch“. 9 IETF RFC 3986: “Uniform Resource Identifier (URI): Generic Syntax“ 10 IETF RFC 5789: “PATCH Method for HTTP“ 11 IETF RFC 8288: “Web Linking“. 12 IANA: “HTTP Status Code Registry at IANA“, http:/www.iana.org/assignments/http-status-codes 13 IETF RFC 7540: “Hypertext Trans
41、fer Protocol Version 2 (HTTP/2)“ 14 Fielding, Roy Thomas. Architectural Styles and the Design of Network-based Software Architectures. Doctoral dissertation, University of California, Irvine, 2000. 15 Erik Wilde, Cesare Pautasso, REST: From Research to Practice, Springer 16 YAML 1.2: “YAML Aint Mark
42、up Language“, http:/yaml.org. 17 Semantic Versioning Specification: https:/semver.org 18 3GPP TS 29.510: “5G System; Network Function Repository Services; Stage 3“. 19 IETF RFC 7807: “Problem Details for HTTP APIs“. 20 3GPP TS 29.502: “5G System; Session Management Services; Stage 3“. 21 3GPP TS 29.
43、509: “Authentication Server Services; Stage 3“. ETSI ETSI TS 129 501 V15.0.1 (2018-07)83GPP TS 29.501 version 15.0.1 Release 153 Definitions and abbreviations 3.1 Definitions For the purposes of the present document, the terms and definitions given in 3GPP TR 21.905 1 and the following apply. A term
44、 defined in the present document takes precedence over the definition of the same term, if any, in 3GPP TR 21.905 1. 3.2 Abbreviations For the purposes of the present document, the abbreviations given in 3GPP TR 21.905 1 and the following apply. An abbreviation defined in the present document takes
45、precedence over the definition of the same abbreviation, if any, in 3GPP TR 21.905 1. 5GC 5G Core Network HAL Hypertext Application Language HATEOAS Hypermedia as the Engine of Application State SBI Service Based Interface YAML YAML Aint Markup Language 4 Design Principles for 5GC SBI APIs 4.1 Gener
46、al Principles Each 5GC SBI API specification should include the following information for each specified service: - Purpose of the API; - URIs of resources; - Supported HTTP methods for a given resource; - Supported representations (e.g. JSON, see IETF RFC 8259 3); - Request body schema(s) (where ap
47、plicable); - Response body schema(s) (where applicable); - Supported response status codes; - Relation types supported if HATEOAS is implemented by the API; - A reference in the resource description subclause to one of the archetypes defined in Annex C if the resource design matches one of them; and
48、 - A list defining identifiers of optional features (see subclause 6.6 of 3GPP TS 29.500 2 for related procedures). For each specified service a subclause to a normative Annex should be provided containing the OpenAPI definitions according to OpenAPI Specification 4 for the service. The specificatio
49、ns should state that content of this normative annex takes precedence when being discrepant to other parts of the specification. The TS Skeleton Template as provided in Annex A should be used as a starting point when drafting 5GC SBI API specifications. Common procedures, HTTP extensions and error handling applicable to several 5GC SBI API specifications should be defined in 3GPP TS 29.500 2 and should be referenced from individual 5GC SBI API spe
