openapi: 3.0.0 info: title: CAPIF_Publish_Service_API description: | API for publishing service APIs. © 2019, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC). All rights reserved. version: "1.1.0.alpha-1" externalDocs: description: 3GPP TS 29.222 V16.1.0 Common API Framework for 3GPP Northbound APIs url: http://www.3gpp.org/ftp/Specs/archive/29_series/29.222/ servers: - url: '{apiRoot}/published-apis/v1' variables: apiRoot: default: https://example.com description: apiRoot as defined in subclause 7.5 of 3GPP TS 29.222. paths: # APF published API /{apfId}/service-apis: post: description: Publish a new API. parameters: - name: apfId in: path required: true schema: $ref: '#/components/schemas/apfId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ServiceAPIDescription' responses: '201': description: Service API published successfully The URI of the created resource shall be returned in the "Location" HTTP header. content: application/json: schema: $ref: '#/components/schemas/ServiceAPIDescription' headers: Location: description: 'Contains the URI of the newly created resource, according to the structure: {apiRoot}/published-apis/v1/{apfId}/service-apis/{serviceApiId}' required: true schema: type: string '400': $ref: 'TS29122_CommonData.yaml#/components/responses/400' '401': $ref: 'TS29122_CommonData.yaml#/components/responses/401' '403': $ref: 'TS29122_CommonData.yaml#/components/responses/403' '404': $ref: 'TS29122_CommonData.yaml#/components/responses/404' '411': $ref: 'TS29122_CommonData.yaml#/components/responses/411' '413': $ref: 'TS29122_CommonData.yaml#/components/responses/413' '415': $ref: 'TS29122_CommonData.yaml#/components/responses/415' '429': $ref: 'TS29122_CommonData.yaml#/components/responses/429' '500': $ref: 'TS29122_CommonData.yaml#/components/responses/500' '503': $ref: 'TS29122_CommonData.yaml#/components/responses/503' default: $ref: 'TS29122_CommonData.yaml#/components/responses/default' get: description: Retrieve all published APIs. parameters: - name: apfId in: path required: true schema: $ref: '#/components/schemas/apfId' responses: '200': description: Definition of all service API(s) published by the API publishing function. content: application/json: schema: $ref: '#/components/schemas/ServiceAPIDescription' '400': $ref: 'TS29122_CommonData.yaml#/components/responses/400' '401': $ref: 'TS29122_CommonData.yaml#/components/responses/401' '403': $ref: 'TS29122_CommonData.yaml#/components/responses/403' '404': $ref: 'TS29122_CommonData.yaml#/components/responses/404' '406': $ref: 'TS29122_CommonData.yaml#/components/responses/406' '429': $ref: 'TS29122_CommonData.yaml#/components/responses/429' '500': $ref: 'TS29122_CommonData.yaml#/components/responses/500' '503': $ref: 'TS29122_CommonData.yaml#/components/responses/503' default: $ref: 'TS29122_CommonData.yaml#/components/responses/default' # Individual APF published API /{apfId}/service-apis/{serviceApiId}: get: description: Retrieve a published service API. parameters: - name: serviceApiId in: path required: true schema: $ref: '#/components/schemas/serviceApiId' - name: apfId in: path required: true schema: $ref: '#/components/schemas/apfId' responses: '200': description: Definition of all service API published by the API publishing function. content: application/json: schema: $ref: '#/components/schemas/ServiceAPIDescription' '400': $ref: 'TS29122_CommonData.yaml#/components/responses/400' '401': $ref: 'TS29122_CommonData.yaml#/components/responses/401' '403': $ref: 'TS29122_CommonData.yaml#/components/responses/403' '404': $ref: 'TS29122_CommonData.yaml#/components/responses/404' '406': $ref: 'TS29122_CommonData.yaml#/components/responses/406' '429': $ref: 'TS29122_CommonData.yaml#/components/responses/429' '500': $ref: 'TS29122_CommonData.yaml#/components/responses/500' '503': $ref: 'TS29122_CommonData.yaml#/components/responses/503' default: $ref: 'TS29122_CommonData.yaml#/components/responses/default' put: description: Update a published service API. parameters: - name: serviceApiId in: path required: true schema: $ref: '#/components/schemas/serviceApiId' - name: apfId in: path required: true schema: $ref: '#/components/schemas/apfId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ServiceAPIDescription' responses: '200': description: Definition of service API updated successfully. content: application/json: schema: $ref: '#/components/schemas/ServiceAPIDescription' '400': $ref: 'TS29122_CommonData.yaml#/components/responses/400' '401': $ref: 'TS29122_CommonData.yaml#/components/responses/401' '403': $ref: 'TS29122_CommonData.yaml#/components/responses/403' '404': $ref: 'TS29122_CommonData.yaml#/components/responses/404' '411': $ref: 'TS29122_CommonData.yaml#/components/responses/411' '413': $ref: 'TS29122_CommonData.yaml#/components/responses/413' '415': $ref: 'TS29122_CommonData.yaml#/components/responses/415' '429': $ref: 'TS29122_CommonData.yaml#/components/responses/429' '500': $ref: 'TS29122_CommonData.yaml#/components/responses/500' '503': $ref: 'TS29122_CommonData.yaml#/components/responses/503' default: $ref: 'TS29122_CommonData.yaml#/components/responses/default' delete: description: Unpublish a published service API. parameters: - name: serviceApiId in: path required: true schema: $ref: '#/components/schemas/serviceApiId' - name: apfId in: path required: true schema: $ref: '#/components/schemas/apfId' responses: '204': description: The individual published service API matching the serviceAPiId is deleted. '400': $ref: 'TS29122_CommonData.yaml#/components/responses/400' '401': $ref: 'TS29122_CommonData.yaml#/components/responses/401' '403': $ref: 'TS29122_CommonData.yaml#/components/responses/403' '404': $ref: 'TS29122_CommonData.yaml#/components/responses/404' '429': $ref: 'TS29122_CommonData.yaml#/components/responses/429' '500': $ref: 'TS29122_CommonData.yaml#/components/responses/500' '503': $ref: 'TS29122_CommonData.yaml#/components/responses/503' default: $ref: 'TS29122_CommonData.yaml#/components/responses/default' # Components components: schemas: # Data types uses as path variables apfId: type: string description: Identification of the API publishing function. serviceApiId: type: string description: String identifying an individual published service API. # Data Type for representations ServiceAPIDescription: type: object properties: apiName: type: string description: API name, it is set as {apiName} part of the URI structure as defined in subclause 4.4 of 3GPP TS 29.501. apiId: type: string description: API identifier assigned by the CAPIF core function to the published service API. Shall not be present in the HTTP POST request from the API publishing function to the CAPIF core function. Shall be present in the HTTP POST response from the CAPIF core function to the API publishing function and in the HTTP GET response from the CAPIF core function to the API invoker (discovery API). aefProfiles: type: array items: $ref: '#/components/schemas/AefProfile' minItems: 1 description: AEF profile information, which includes the exposed API details (e.g. protocol). description: type: string description: Text description of the API supportedFeatures: $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures' shareableInfo: $ref: '#/components/schemas/ShareableInformation' serviceAPICategory: type: string apiSuppFeats: $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures' required: - apiName InterfaceDescription: type: object properties: ipv4Addr: $ref: 'TS29122_CommonData.yaml#/components/schemas/Ipv4Addr' ipv6Addr: $ref: 'TS29122_CommonData.yaml#/components/schemas/Ipv6Addr' port: $ref: 'TS29122_CommonData.yaml#/components/schemas/Port' securityMethods: type: array items: $ref: '#/components/schemas/SecurityMethod' minItems: 1 description: Security methods supported by the interface, it take precedence over the security methods provided in AefProfile, for this specific interface. oneOf: - required: [ipv4Addr] - required: [ipv6Addr] AefProfile: type: object properties: aefId: type: string description: Identifier of the API exposing function versions: type: array items: $ref: '#/components/schemas/Version' minItems: 1 description: API version protocol: $ref: '#/components/schemas/Protocol' dataFormat: $ref: '#/components/schemas/DataFormat' securityMethods: type: array items: $ref: '#/components/schemas/SecurityMethod' minItems: 1 description: Security methods supported by the AEF domainName: type: string description: Domain to which API belongs to interfaceDescriptions: type: array items: $ref: '#/components/schemas/InterfaceDescription' minItems: 1 description: Interface details required: - aefId - versions oneOf: - required: [domainName] - required: [interfaceDescriptions] Resource: type: object properties: resourceName: type: string description: Resource name commType: $ref: '#/components/schemas/CommunicationType' uri: type: string description: Relative URI of the API resource, it is set as {apiSpecificResourceUriPart} part of the URI structure as defined in subclause 4.4 of 3GPP TS 29.501. custOpName: type: string description: it is set as {custOpName} part of the URI structure for a custom operation associated with a resource as defined in subclause 4.4 of 3GPP TS 29.501. operations: type: array items: $ref: '#/components/schemas/Operation' minItems: 1 description: Supported HTTP methods for the API resource. Only applicable when the protocol in AefProfile indicates HTTP. description: type: string description: Text description of the API resource required: - resourceName - commType - uri CustomOperation: type: object properties: commType: $ref: '#/components/schemas/CommunicationType' custOpName: type: string description: it is set as {custOpName} part of the URI structure for a custom operation without resource association as defined in subclause 4.4 of 3GPP TS 29.501. operations: type: array items: $ref: '#/components/schemas/Operation' minItems: 1 description: Supported HTTP methods for the API resource. Only applicable when the protocol in AefProfile indicates HTTP. description: type: string description: Text description of the custom operation required: - commType - custOpName Version: type: object properties: apiVersion: type: string description: API major version in URI (e.g. v1) expiry: $ref: 'TS29571_CommonData.yaml#/components/schemas/DateTime' resources: type: array items: $ref: '#/components/schemas/Resource' minItems: 1 description: Resources supported by the API. custOperations: type: array items: $ref: '#/components/schemas/CustomOperation' minItems: 1 description: Custom operations without resource association. required: - apiVersion ShareableInformation: type: object properties: isShareable: type: boolean ccfProviderDomains: type: array items: type: string minItems: 1 required: - isShareable Protocol: anyOf: - type: string enum: - HTTP_1_1 - HTTP_2 - type: string description: > This string provides forward-compatibility with future extensions to the enumeration but is not used to encode content defined in the present version of this API. description: > Possible values are - HTTP_1_1: HTTP version 1.1 - HTTP_2: HTTP version 2 CommunicationType: anyOf: - type: string enum: - REQUEST_RESPONSE - SUBSCRIBE_NOTIFY - type: string description: > This string provides forward-compatibility with future extensions to the enumeration but is not used to encode content defined in the present version of this API. description: > Possible values are - REQUEST_RESPONSE: The communication is of the type request-response - SUBSCRIBE_NOTIFY: The communication is of the type subscribe-notify DataFormat: anyOf: - type: string enum: - JSON - type: string description: > This string provides forward-compatibility with future extensions to the enumeration but is not used to encode content defined in the present version of this API. description: > Possible values are - JSON: JavaScript Object Notation SecurityMethod: anyOf: - type: string enum: - PSK - PKI - OAUTH - type: string description: > This string provides forward-compatibility with future extensions to the enumeration but is not used to encode content defined in the present version of this API. description: > Possible values are - PSK: Security method 1 (Using TLS-PSK) as described in 3GPP TS 33.122 - PKI: Security method 2 (Using PKI) as described in 3GPP TS 33.122 - OAUTH: Security method 3 (TLS with OAuth token) as described in 3GPP TS 33.122 Operation: anyOf: - type: string enum: - GET - POST - PUT - PATCH - DELETE - type: string description: > This string provides forward-compatibility with future extensions to the enumeration but is not used to encode content defined in the present version of this API. description: > Possible values are - GET: HTTP GET method - POST: HTTP POST method - PUT: HTTP PUT method - PATCH: HTTP PATCH method - DELETE: HTTP DELETE method