Skip to content
GitLab
Commits (25)
Hide whitespace changes
Inline Side-by-side
.jenkins.sh 0 → 100755
View file @ 68625d1f
#!/bin/bash
# Copyright ETSI 2017
# See: https://forge.etsi.org/etsi-forge-copyright-statement.txt
cd "$(dirname "$0")"
run_dir="$(pwd)"
rm build/*-API.yaml
rm build/*-API.json
cd docker
./build-container.sh
./run-container.sh "${run_dir}"
OUTCOME=$?
exit $OUTCOME
docker/Dockerfile 0 → 100644
View file @ 68625d1f
# Copyright ETSI 2017
# See: https://forge.etsi.org/etsi-forge-copyright-statement.txt
FROM alpine:3.10.0
RUN env
RUN apk update
RUN apk add bash
RUN apk add nodejs
RUN apk add nodejs-npm
RUN apk add asciidoctor
RUN apk add openjdk8
RUN apk add ca-certificates wget && update-ca-certificates
RUN apk add openssl
RUN gem install rdoc --pre || gem install rdoc --pre
RUN gem install asciidoctor-pdf-cjk
RUN wget https://forge.etsi.org/swagger2markup-cli-1.3.2.jar
RUN npm config set proxy $http_proxy
RUN npm install -g swagger-cli
RUN npm install -g json-refs
RUN npm install -g yamljs
ADD validate-in-docker.sh /validate-in-docker.sh
RUN chmod +x /validate-in-docker.sh
ADD swg2mrkup /bin/swg2mrkup
RUN chmod +x /bin/swg2mrkup
ADD oas2pdf /bin/oas2pdf
RUN chmod +x /bin/oas2pdf
ENTRYPOINT ["/validate-in-docker.sh"]
docker/build-container.sh 0 → 100755
View file @ 68625d1f
#!/bin/bash
# Copyright ETSI 2017
# See: https://forge.etsi.org/etsi-forge-copyright-statement.txt
#set -x
proxy = ""
if [[ ! -v http_proxy ]]; then
echo "http_proxy is not set"
elif [[ -z "$http_proxy" ]]; then
echo "http_proxy is empty"
else
echo "http_proxy is set to $http_proxy"
if [[ $http_proxy =~ ^http:\/\/[0-9] ]]; then
echo "starts with http"
proxy=$http_proxy
elif [[ $http_proxy =~ ^[0-9] ]]; then
echo "starts with number"
proxy=http://$http_proxy
fi
fi
echo "Proxy set to $proxy"
docker build --build-arg http_proxy=$proxy --build-arg https_proxy=$proxy -t openapivalidator .
\ No newline at end of file
docker/oas2pdf 0 → 100644
View file @ 68625d1f
#!/bin/bash
#Copyright (c) ETSI 2017.
# This software is subject to copyrights owned by ETSI. Non-exclusive permission
# is hereby granted, free of charge, to copy, reproduce and amend this file
# under the following conditions: It is provided "as is", without warranty of any
# kind, expressed or implied.
# ETSI shall never be liable for any claim, damages, or other liability arising
# from its use or inability of use.This permission does not apply to any documentation
# associated with this file for which ETSI keeps all rights reserved. The present
# copyright notice shall be included in all copies of whole or part of this
# software and shall not imply any sub-license right.
#
# Author: michele.carignani@etsi.org
#
# This script takes an OpenAPI file in input and creates
# a PDF file with the content.
#
# Prerequisites:
# - https://github.com/Swagger2Markup/swagger2markup-cli
# - Asciidoctor (sudo apt-get install asciidoctor)
# - Asciidoctor-pdf (sudo gem install asciidoctor-pdf)
#
# Usage:
# oas2pdf <oasfile> (e.g. myapi.json)
#
# Result:
# A new pdf file is created in the working directory (e.g. myapi.pdf)
#
#
#
#
# Configuration
# Change this if needed
SWG2MRKUP=swg2mrkup
ASCIIDOCPDF=asciidoctor-pdf
# Setup
WD=$(pwd)
TWD=$(mktemp -d)
INFILE=$(basename ${1?"Error: missing input file name"} )
OUTFILE="${INFILE%.*}"
echo "$INFILE, $OUTFILE"
echo "Converting to asciidoc.."
${SWG2MRKUP} convert -i "$1" -f "$TWD/$OUTFILE"
echo
echo "Converting to PDF.."
"${ASCIIDOCPDF}" "$TWD/${OUTFILE}.adoc" -o "$WD/${OUTFILE}.pdf"
echo
echo "Done."
# Clean up
rm -r $TWD
docker/run-container.sh 0 → 100755
View file @ 68625d1f
#!/bin/bash
# Copyright ETSI 2017
# See: https://forge.etsi.org/etsi-forge-copyright-statement.txt
# Change this variable to true if you want
# to copy the created yaml files to a web served directory
#
#
WEB_PUBLISH=true
f="${1:-`pwd`}"
filter="$2"
echo "Mounting dir $f as /work"
if [ -n "$JOB_BASE_NAME" -a "$WEB_PUBLISH" = true ] ; then
s="/var/www/html/api/nfv/$JOB_BASE_NAME/$BUILD_NUMBER"
mkdir -v -p "$s"
echo "Mounting dir $s as /storage"
docker run -v "$f":/work -v "$s":/storage openapivalidator "/work" "/storage" "$filter"
else
docker run -v "$f":/work openapivalidator "/work" "/storage" "$filter"
fi
docker/swg2mrkup 0 → 100644
View file @ 68625d1f
#!/bin/bash
#Copyright (c) ETSI 2017.
# This software is subject to copyrights owned by ETSI. Non-exclusive permission
# is hereby granted, free of charge, to copy, reproduce and amend this file
# under the following conditions: It is provided "as is", without warranty of any
# kind, expressed or implied.
# ETSI shall never be liable for any claim, damages, or other liability arising
# from its use or inability of use.This permission does not apply to any documentation
# associated with this file for which ETSI keeps all rights reserved. The present
# copyright notice shall be included in all copies of whole or part of this
# software and shall not imply any sub-license right.
#
# Author: michele.carignani@etsi.org
java -jar /swagger2markup-cli-1.3.2.jar $@
docker/validate-in-docker.sh 0 → 100644
View file @ 68625d1f
#!/bin/bash
# Copyright ETSI 2017
# See: https://forge.etsi.org/etsi-forge-copyright-statement.txt
# Merges OpenAPIs interfaces in the working directory
# and validates them individually.
# Exit status is 0 if all validation passed, 1 otherwise
# Usage:
# $0 <working-directory> <storage-dir>
#set -x
function store_api () {
f="$1"
cp -v "$1" "${storage_dir}/"
}
function validate_api () {
file="$1"
api="$2"
deliverable="$3"
echo "--- Merging file."
merged_file="../build/${deliverable}-${api}-API.yaml"
json_file="../build/${deliverable}-${api}-API.json"
json-refs resolve "${file}" > "${merged_file}"
yaml2json "${merged_file}" > "${json_file}"
# Create the PDF version
echo "--- Create PDF..."
oas2pdf "${json_file}" 2>/dev/null 1>/dev/null
mv "${deliverable}-${api}-API.pdf" "../build/"
echo "--- Validating ${merged_file}"
swagger-cli validate "${merged_file}"
vres=$?
echo "--- Validation done ($vres)."
# If validation succedes, store the generated file
[ $vres -a -d "/storage" ] && store_api "${merged_file}"
[ $vres -a -d "/storage" ] && store_api "${json_file}"
[ $vres -a -d "/storage" ] && store_api "../build/${deliverable}-${api}-API.pdf"
return $vres
}
# usage get_api_from_fn <file_name>
# e.g. get_api_from_fn /path/to/SOL003/Api1/Api1.yaml returns Api1
function get_api_from_fn () {
echo "$(basename $(dirname $1))"
}
# usage get_api_from_fn <file_name>
# e.g. get_api_from_fn /path/to/SOL003/Api1/Api1.yaml returns Api1
function get_deliverable_from_fn () {
echo "$(basename $(dirname $(dirname $1 )))"
}
## Main ##
wd="${1?"Usage: $0 <working-directory> <storage-directory> [<filter_regex>]"}"
storage_dir="${2?"Usage: $0 <working-directory> <storage-directory> [<filter_regex>]"}"
filter="$3"
echo "Using filter '$filter'"
echo
mkdir -p "$wd/build"
echo "Entering dir $wd/src"
cd "$wd/src"
# Stores the overall validation result
# (single results in OR)
fres=0
for f in $(find -name "*.yaml") ; do
# echo "Found yaml file: $f"
file=$(basename "$f")
api=$(get_api_from_fn $f)
deliverable=$(get_deliverable_from_fn $f)
if [ "$file" = "$api.yaml" ]; then
if [[ -n "$filter" && ! "$f" =~ ^[a-zA-Z0-9\.\/\-]*$filter[a-zA-Z\.\/0-9\-]*$ ]] ; then
echo "Filtered out: $f (api: $api) (deliverable:$deliverable)."
else
echo "-- Will validate: $f (api: $api) (deliverable:$deliverable)"
validate_api "$f" "$api" "$deliverable"
res=$?
fres=$(($fres||$res))
fi
fi
done
chmod -R o+w "$wd/build"
# Exit code needed for jenkins to know the verdict of the build
echo "-- Final validator returns $fres."
exit $fres
src/SOL012/APIVersion/APIVersion.yaml 0 → 100644
View file @ 68625d1f
openapi: 3.0.2
info:
version: 1.0.0-impl:etsi.org:ETSI_NFV_OpenAPI:1
title: SOL012 - API version interface
description: >
SOL012 - API version Interface
IMPORTANT: Please note that this file might
be not aligned to the current version of the ETSI Group Specification it
refers to and has not been approved by the ETSI NFV ISG. In case of
discrepancies the published ETSI Group Specification takes precedence.
Please report bugs to https://forge.etsi.org/rep/nfv/SOL012/issues
license:
name: ETSI Forge copyright notice
url: https://forge.etsi.org/etsi-forge-copyright-notice.txt
contact:
name: NFV-SOL WG
externalDocs:
description: ETSI GS NFV-SOL 012 v3.4.1
url: https://www.etsi.org/deliver/etsi_gs/NFV-SOL/001_099/012/03.04.01_60/gs_nfv-sol012v030401p.pdf
paths:
/nfvpolicy/api_versions:
$ref: '../endpoints/SOL012_endpoints.yaml#/endpoints/api_versions'
\ No newline at end of file
src/SOL012/PolicyManagement/PolicyManagement.yaml 0 → 100644
View file @ 68625d1f
openapi: 3.0.2
info:
version: 1.0.0-impl:etsi.org:ETSI_NFV_OpenAPI:1
title: SOL012 - Policy Management Interface
description: >
SOL012 - Policy Management Interface
IMPORTANT: Please note that this file might be not aligned to the current version of the ETSI Group Specification
it refers to. In case of discrepancies the published ETSI Group Specification takes precedence.
Please report bugs to https://forge.etsi.org/rep/nfv/SOL012/issues
license:
name: ETSI Forge copyright notice
url: https://forge.etsi.org/etsi-forge-copyright-notice.txt
externalDocs:
description: ETSI GS NFV-SOL 012 v3.4.1
url: https://www.etsi.org/deliver/etsi_gs/NFV-SOL/001_099/012/03.04.01_60/gs_nfv-sol012v030401p.pdf
security:
- OauthSecurity:
- all
servers:
- url: http://127.0.0.1/nfvpolicy/v1
- url: https://127.0.0.1/nfvpolicy/v1
paths:
"/api_versions":
$ref: '../endpoints/SOL012_endpoints.yaml#/endpoints/api_versions'
"/policies":
description: >-
This resource represents policies. The API consumer can use this resource to create a policy, and to query multiple policies.
post:
description: >-
The POST method creates a new individual policy resource.
This method shall follow the provisions specified in the tables 5.5.3.3.1-1 and 5.5.3.3.1-2 for URI query parameters,
request and response data structures, and response codes.
As the result of successfully executing this method, a new "individual policy" resource as defined in clause
5.5.4 shall have been created, and the value of the "activationStatus" attribute in the representation of that
resource shall be "DEACTIVATED". A notification of type PolicyChangeNotification shall be triggered as part of
successfully executing this method as defined in clause 5.6.2.7.
parameters:
- $ref: "../components/SOL012_params.yaml#/components/parameters/Version"
- $ref: "../components/SOL012_params.yaml#/components/parameters/Accept"
- $ref: "../components/SOL012_params.yaml#/components/parameters/ContentType"
- $ref: "../components/SOL012_params.yaml#/components/parameters/Authorization"
requestBody:
$ref: "#/components/requestBodies/CreatePolicyRequest"
responses:
"201":
$ref: '#/components/responses/Policy.Post.201'
"400":
$ref: ../components/SOL012_resp.yaml#/components/responses/400
"401":
$ref: ../components/SOL012_resp.yaml#/components/responses/401
"403":
$ref: ../components/SOL012_resp.yaml#/components/responses/403
"404":
$ref: ../components/SOL012_resp.yaml#/components/responses/404
"405":
$ref: ../components/SOL012_resp.yaml#/components/responses/405
"406":
$ref: ../components/SOL012_resp.yaml#/components/responses/406
"422":
$ref: ../components/SOL012_resp.yaml#/components/responses/422
"500":
$ref: ../components/SOL012_resp.yaml#/components/responses/500
"503":
$ref: ../components/SOL012_resp.yaml#/components/responses/503
"504":
$ref: ../components/SOL012_resp.yaml#/components/responses/504
get:
description: >-
The GET method queries information about multiple policies.
This method shall follow the provisions specified in the tables 5.5.3.3.2-1 and 5.5.3.3.2-2
for URI query parameters, request and response data structures, and response codes.
parameters:
- $ref: "../components/SOL012_params.yaml#/components/parameters/filter"
- $ref: "../components/SOL012_params.yaml#/components/parameters/nextpage_opaque_marker"
- $ref: "../components/SOL012_params.yaml#/components/parameters/Version"
- $ref: "../components/SOL012_params.yaml#/components/parameters/Accept"
- $ref: "../components/SOL012_params.yaml#/components/parameters/Authorization"
responses:
"200":
$ref: '#/components/responses/Policy.Get.200'
"400":
$ref: '#/components/responses/Policy.Get.400'
"401":
$ref: ../components/SOL012_resp.yaml#/components/responses/401
"403":
$ref: ../components/SOL012_resp.yaml#/components/responses/403
"404":
$ref: ../components/SOL012_resp.yaml#/components/responses/404
"405":
$ref: ../components/SOL012_resp.yaml#/components/responses/405
"406":
$ref: ../components/SOL012_resp.yaml#/components/responses/406
"422":
$ref: ../components/SOL012_resp.yaml#/components/responses/422
"500":
$ref: ../components/SOL012_resp.yaml#/components/responses/500
"503":
$ref: ../components/SOL012_resp.yaml#/components/responses/503
"504":
$ref: ../components/SOL012_resp.yaml#/components/responses/504
"/policies/{policyId}":
description: >
This resource represents an individual policy. The API consumer can use this resource to modify an individual
policy, to read information about the policy and delete the policy.
parameters:
- $ref: '#/components/parameters/policyId'
get:
description: >
The GET method retrieves information about a policy by reading an individual policy resource.
This method shall follow the provisions specified in the tables 5.5.4.3.2-1 and 5.5.4.3.2-2 for URI
query parameters, request and response data structures, and response codes.
parameters:
- $ref: "../components/SOL012_params.yaml#/components/parameters/Accept"
- $ref: "../components/SOL012_params.yaml#/components/parameters/Authorization"
responses:
"200":
$ref: '#/components/responses/IndividualPolicy.Get.200'
"400":
$ref: ../components/SOL012_resp.yaml#/components/responses/400
"401":
$ref: ../components/SOL012_resp.yaml#/components/responses/401
"403":
$ref: ../components/SOL012_resp.yaml#/components/responses/403
"404":
$ref: ../components/SOL012_resp.yaml#/components/responses/404
"405":
$ref: ../components/SOL012_resp.yaml#/components/responses/405
"406":
$ref: ../components/SOL012_resp.yaml#/components/responses/406
"422":
$ref: ../components/SOL012_resp.yaml#/components/responses/422
"500":
$ref: ../components/SOL012_resp.yaml#/components/responses/500
"503":
$ref: ../components/SOL012_resp.yaml#/components/responses/503
"504":
$ref: ../components/SOL012_resp.yaml#/components/responses/504
patch:
description: >
The PATCH method modifies a policy.
This method shall follow the provisions specified in the tables 5.5.4.3.4-1 and 5.5.4.3.4-2 for URI
query parameters, request and response data structures, and response codes.
Modification of a policy includes three functionalities: activating/deactivating the policy,
changing the associations of the policy, and changing the selected version of the policy.
The three functionalities may be combined flexibly in one request unless there's conflict with
the state of the policy.
parameters:
- $ref: "../components/SOL012_params.yaml#/components/parameters/Accept"
- $ref: "../components/SOL012_params.yaml#/components/parameters/ContentType"
- $ref: "../components/SOL012_params.yaml#/components/parameters/Authorization"
requestBody:
$ref: "#/components/requestBodies/PolicyModifications"
responses:
"200":
$ref: '#/components/responses/PolicyModifications.Patch.200'
"400":
$ref: ../components/SOL012_resp.yaml#/components/responses/400
"401":
$ref: ../components/SOL012_resp.yaml#/components/responses/401
"403":
$ref: ../components/SOL012_resp.yaml#/components/responses/403
"404":
$ref: ../components/SOL012_resp.yaml#/components/responses/404
"405":
$ref: ../components/SOL012_resp.yaml#/components/responses/405
"406":
$ref: ../components/SOL012_resp.yaml#/components/responses/406
"409":
$ref: '#/components/responses/PolicyModifications.Patch.409'
"422":
$ref: ../components/SOL012_resp.yaml#/components/responses/422
"500":
$ref: ../components/SOL012_resp.yaml#/components/responses/500
"503":
$ref: ../components/SOL012_resp.yaml#/components/responses/503
"504":
$ref: ../components/SOL012_resp.yaml#/components/responses/504
delete:
description: >
The DELETE method deletes an individual policy.
This method shall follow the provisions specified in the tables 5.5.4.3.5-1 and 5.5.4.3.5-2 for URI
query parameters, request and response data structures, and response codes.
As the result of successfully executing this method, the "individual policy" resource shall not exist
any longer. A notification of type "PolicyChangeNotification" shall be triggered as part of successfully
executing this method as defined in clause 5.6.2.7.
parameters:
- $ref: "../components/SOL012_params.yaml#/components/parameters/Authorization"
responses:
"204":
$ref: '#/components/responses/Policy.Delete.204'
"400":
$ref: ../components/SOL012_resp.yaml#/components/responses/400
"401":
$ref: ../components/SOL012_resp.yaml#/components/responses/401
"403":
$ref: ../components/SOL012_resp.yaml#/components/responses/403
"404":
$ref: ../components/SOL012_resp.yaml#/components/responses/404
"405":
$ref: ../components/SOL012_resp.yaml#/components/responses/405
"406":
$ref: ../components/SOL012_resp.yaml#/components/responses/406
"409":
$ref: '#/components/responses/Policy.Delete.409'
"422":
$ref: ../components/SOL012_resp.yaml#/components/responses/422
"500":
$ref: ../components/SOL012_resp.yaml#/components/responses/500
"503":
$ref: ../components/SOL012_resp.yaml#/components/responses/503
"504":
$ref: ../components/SOL012_resp.yaml#/components/responses/504
"/policies/{policyId}/selected_versions":
description: >
This resource represents the selected version of an individual policy. The API consumer can use this resource
to read the content of the selected version of the policy.
The selected version is the version to be used when activating the policy and is then enforced as long as the
policy is in ACTIVATED state.
parameters:
- $ref: '#/components/parameters/policyId'
get:
description: >
The GET method fetches the content of the selected version of an individual policy.
This method shall follow the provisions specified in the tables 5.5.5.3.2-1 and 5.5.5.3.2-2 for URI query
parameters, request and response data structures, and response codes.
parameters:
- $ref: "../components/SOL012_params.yaml#/components/parameters/Accept"
- $ref: "../components/SOL012_params.yaml#/components/parameters/Authorization"
responses:
"200":
$ref: '#/components/responses/PolicySelectedVersion.Get.200'
"400":
$ref: ../components/SOL012_resp.yaml#/components/responses/400
"401":
$ref: ../components/SOL012_resp.yaml#/components/responses/401
"403":
$ref: ../components/SOL012_resp.yaml#/components/responses/403
"404":
$ref: '#/components/responses/PolicySelectedVersion.Get.404'
"405":
$ref: ../components/SOL012_resp.yaml#/components/responses/405
"406":
$ref: ../components/SOL012_resp.yaml#/components/responses/406
"422":
$ref: ../components/SOL012_resp.yaml#/components/responses/422
"500":
$ref: ../components/SOL012_resp.yaml#/components/responses/500
"503":
$ref: ../components/SOL012_resp.yaml#/components/responses/503
"504":
$ref: ../components/SOL012_resp.yaml#/components/responses/504
"/policies/{policyId}/versions/{version}":
description: >
This resource represents a particular version of an individual policy. The API consumer can use this resource
to transfer the content, read the content and delete a particular version of a policy.
parameters:
- $ref: '#/components/parameters/policyId'
- $ref: '#/components/parameters/version'
get:
description: >
The GET method fetches the content of a particular version of an individual policy.
This method shall follow the provisions specified in the tables 5.5.6.3.2-1 and 5.5.6.3.2-2 for URI
query parameters, request and response data structures, and response codes.
parameters:
- $ref: "../components/SOL012_params.yaml#/components/parameters/Accept"
- $ref: "../components/SOL012_params.yaml#/components/parameters/Authorization"
responses:
"200":
$ref: '#/components/responses/IndividualPolicyVersion.Get.200'
"400":
$ref: ../components/SOL012_resp.yaml#/components/responses/400
"401":
$ref: ../components/SOL012_resp.yaml#/components/responses/401
"403":
$ref: ../components/SOL012_resp.yaml#/components/responses/403
"404":
$ref: ../components/SOL012_resp.yaml#/components/responses/404
"405":
$ref: ../components/SOL012_resp.yaml#/components/responses/405
"406":
$ref: ../components/SOL012_resp.yaml#/components/responses/406
"422":
$ref: ../components/SOL012_resp.yaml#/components/responses/422
"500":
$ref: ../components/SOL012_resp.yaml#/components/responses/500
"503":
$ref: ../components/SOL012_resp.yaml#/components/responses/503
"504":
$ref: ../components/SOL012_resp.yaml#/components/responses/504
put:
description: >
The PUT method transfers the content of a particular version of an individual policy.
This method shall follow the provisions specified in the tables 5.5.6.3.3-1 and 5.5.6.3.3-2 for
URI query parameters, request and response data structures, and response codes.
parameters:
- $ref: "../components/SOL012_params.yaml#/components/parameters/Accept"
- $ref: "../components/SOL012_params.yaml#/components/parameters/ContentType"
- $ref: "../components/SOL012_params.yaml#/components/parameters/Authorization"
responses:
"201":
$ref: '#/components/responses/PolicyVersionTransfer.Put.201'
"400":
$ref: ../components/SOL012_resp.yaml#/components/responses/400
"401":
$ref: ../components/SOL012_resp.yaml#/components/responses/401
"403":
$ref: ../components/SOL012_resp.yaml#/components/responses/403
"404":
$ref: ../components/SOL012_resp.yaml#/components/responses/404
"405":
$ref: ../components/SOL012_resp.yaml#/components/responses/405
"406":
$ref: ../components/SOL012_resp.yaml#/components/responses/406
"409":
$ref: '#/components/responses/PolicyVersionTransfer.Put.409'
"422":
$ref: ../components/SOL012_resp.yaml#/components/responses/422
"500":
$ref: ../components/SOL012_resp.yaml#/components/responses/500
"503":
$ref: ../components/SOL012_resp.yaml#/components/responses/503
"504":
$ref: ../components/SOL012_resp.yaml#/components/responses/504
delete:
description: >
The DELETE method deletes a particular version of an individual policy.
This method shall follow the provisions specified in the tables 5.5.6.3.5-1 and 5.5.6.3.5-2 for URI query
parameters, request and response data structures, and response codes.
As the result of successfully executing this method, the "particular version of an individual policy" resource
shall be deleted. It's not allowed to delete the selected version of the individual policy.
A notification of type "PolicyChangeNotification" shall be triggered as part of successfully executing this
method as defined in clause 5.6.2.8.
responses:
"204":
$ref: '#/components/responses/PolicyVersion.Delete.204'
"400":
$ref: ../components/SOL012_resp.yaml#/components/responses/400
"401":
$ref: ../components/SOL012_resp.yaml#/components/responses/401
"403":
$ref: ../components/SOL012_resp.yaml#/components/responses/403
"404":
$ref: ../components/SOL012_resp.yaml#/components/responses/404
"405":
$ref: ../components/SOL012_resp.yaml#/components/responses/405
"406":
$ref: ../components/SOL012_resp.yaml#/components/responses/406
"409":
$ref: '#/components/responses/PolicyVersion.Delete.409'
"422":
$ref: ../components/SOL012_resp.yaml#/components/responses/422
"500":
$ref: ../components/SOL012_resp.yaml#/components/responses/500
"503":
$ref: ../components/SOL012_resp.yaml#/components/responses/503
"504":
$ref: ../components/SOL012_resp.yaml#/components/responses/504
"/subscriptions":
description: >-
This resource represents subscriptions. The API consumer can use this resource to subscribe to notifications
related to policy changes and any detected policy conflicts, and to query its subscriptions.
post:
description: >-
The POST method creates a new subscription.
This method shall follow the provisions specified in the tables 5.5.7.3.1-1 and 5.5.7.3.1-2 for URI query parameters,
request and response data structures, and response codes.
As the result of successfully executing this method, a new "Individual subscription" resource as defined in clause 5.5.6
shall have been created. This method shall not trigger any notification.
parameters:
- $ref: "../components/SOL012_params.yaml#/components/parameters/Version"
- $ref: "../components/SOL012_params.yaml#/components/parameters/Accept"
- $ref: "../components/SOL012_params.yaml#/components/parameters/ContentType"
- $ref: "../components/SOL012_params.yaml#/components/parameters/Authorization"
requestBody:
$ref: '#/components/requestBodies/PolicySubscriptionRequest'
responses:
"201":
$ref: '#/components/responses/Subscriptions.Post.201'
"303":
$ref: '#/components/responses/Subscriptions.Post.303'
"400":
$ref: ../components/SOL012_resp.yaml#/components/responses/400
"401":
$ref: ../components/SOL012_resp.yaml#/components/responses/401
"403":
$ref: ../components/SOL012_resp.yaml#/components/responses/403
"404":
$ref: ../components/SOL012_resp.yaml#/components/responses/404
"405":
$ref: ../components/SOL012_resp.yaml#/components/responses/405
"406":
$ref: ../components/SOL012_resp.yaml#/components/responses/406
"422":
$ref: ../components/SOL012_resp.yaml#/components/responses/422
"500":
$ref: ../components/SOL012_resp.yaml#/components/responses/500
"503":
$ref: ../components/SOL012_resp.yaml#/components/responses/503
"504":
$ref: ../components/SOL012_resp.yaml#/components/responses/504
get:
description: >-
The GET method queries the list of active subscriptions of the functional block that invokes the method.
It can be used e.g. for resynchronization after error situations.
This method shall follow the provisions specified in the tables 5.5.7.3.2-1 and 5.5.7.3.2-2 for
URI query parameters, request and response data structures, and response codes.
parameters:
- $ref: "../components/SOL012_params.yaml#/components/parameters/Version"
- $ref: "../components/SOL012_params.yaml#/components/parameters/Accept"
- $ref: "../components/SOL012_params.yaml#/components/parameters/Authorization"
- $ref: "../components/SOL012_params.yaml#/components/parameters/filter"
- $ref: "../components/SOL012_params.yaml#/components/parameters/nextpage_opaque_marker"
responses:
"200":
$ref: '#/components/responses/Subscriptions.Get.200'
"400":
$ref: '#/components/responses/Subscriptions.Get.400'
"401":
$ref: ../components/SOL012_resp.yaml#/components/responses/401
"403":
$ref: ../components/SOL012_resp.yaml#/components/responses/403
"404":
$ref: ../components/SOL012_resp.yaml#/components/responses/404
"405":
$ref: ../components/SOL012_resp.yaml#/components/responses/405
"406":
$ref: ../components/SOL012_resp.yaml#/components/responses/406
"422":
$ref: ../components/SOL012_resp.yaml#/components/responses/422
"500":
$ref: ../components/SOL012_resp.yaml#/components/responses/500
"503":
$ref: ../components/SOL012_resp.yaml#/components/responses/503
"504":
$ref: ../components/SOL012_resp.yaml#/components/responses/504
"/subscriptions/{subscriptionId}":
description: >-
This resource represents an individual subscription. The API consumer can use this resource to read and to
terminate a subscription to notifications related to policy management.
parameters:
- $ref: '#/components/parameters/subscriptionId'
get:
description: >-
The GET method retrieves information about a subscription by reading an "Individual subscription" resource.
This method shall follow the provisions specified in the tables 5.5.8.3.2-1 and 5.5.8.3.2-2 for URI query
parameters, request and response data structures, and response codes.
parameters:
- $ref: "../components/SOL012_params.yaml#/components/parameters/Version"
- $ref: "../components/SOL012_params.yaml#/components/parameters/Accept"
- $ref: "../components/SOL012_params.yaml#/components/parameters/Authorization"
responses:
"200":
$ref: '#/components/responses/IndividualSubscription.Get.200'
"400":
$ref: ../components/SOL012_resp.yaml#/components/responses/400
"401":
$ref: ../components/SOL012_resp.yaml#/components/responses/401
"403":
$ref: ../components/SOL012_resp.yaml#/components/responses/403
"404":
$ref: ../components/SOL012_resp.yaml#/components/responses/404
"405":
$ref: ../components/SOL012_resp.yaml#/components/responses/405
"406":
$ref: ../components/SOL012_resp.yaml#/components/responses/406
"422":
$ref: ../components/SOL012_resp.yaml#/components/responses/422
"500":
$ref: ../components/SOL012_resp.yaml#/components/responses/500
"503":
$ref: ../components/SOL012_resp.yaml#/components/responses/503
"504":
$ref: ../components/SOL012_resp.yaml#/components/responses/504
delete:
description: >-
The DELETE method terminates an individual subscription. This method shall follow the provisions specified
in the tables 5.5.8.3.5-1 and 5.5.8.3.5-2 for URI query parameters, request and response data structures,
and response codes.
As the result of successfully executing this method, the "Individual subscription" resource shall not exist
any longer. This means that no notifications for that subscription shall be sent to the formerly-subscribed
API consumer.
parameters:
- $ref: "../components/SOL012_params.yaml#/components/parameters/Version"
- $ref: "../components/SOL012_params.yaml#/components/parameters/Authorization"
responses:
"204":
$ref: '#/components/responses/IndividualSubscription.Delete.204'
"400":
$ref: ../components/SOL012_resp.yaml#/components/responses/400
"401":
$ref: ../components/SOL012_resp.yaml#/components/responses/401
"403":
$ref: ../components/SOL012_resp.yaml#/components/responses/403
"404":
$ref: ../components/SOL012_resp.yaml#/components/responses/404
"405":
$ref: ../components/SOL012_resp.yaml#/components/responses/405
"406":
$ref: ../components/SOL012_resp.yaml#/components/responses/406
"409":
$ref: ../components/SOL012_resp.yaml#/components/responses/409
"422":
$ref: ../components/SOL012_resp.yaml#/components/responses/422
"500":
$ref: ../components/SOL012_resp.yaml#/components/responses/500
"503":
$ref: ../components/SOL012_resp.yaml#/components/responses/503
"504":
$ref: ../components/SOL012_resp.yaml#/components/responses/504
components:
parameters:
policyId:
name: policyId
description: >
Identifier of the policy. This identifier can be retrieved from the resource referenced by the "Location" HTTP
header in the response to a POST request creating a new "individual policy" resource. It can also be retrieved
from the "id" attribute in the payload body of that response.
in: path
required: true
schema:
$ref: '../components/SOL012_schemas.yaml#/components/schemas/Identifier'
version:
name: version
description: >
Version of the policy. This URI variable is provided by the API consumer in a PUT request creating the new
particular version of an individual policy resource. It can be retrieved from the "versions" attribute in the
payload body of the response to a GET request to the “individual policy” resource.
in: path
required: true
schema:
type: string
subscriptionId:
name: subscriptionId
description: >
Identifier of the subscription. This identifier can be retrieved from the resource referenced by the
"Location" HTTP header in the response to a POST request creating a new "Individual subscription" resource.
It can also be retrieved from the "id" attribute in the payload body of that response.
in: path
required: true
schema:
$ref: '../components/SOL012_schemas.yaml#/components/schemas/Identifier'
schemas:
CreatePolicyRequest:
description: >
This type represents request parameters for creating a policy. It shall comply with the provisions defined
in table 5.6.2.2-1.
type: object
properties:
designer:
description: >
Human readable name of the designer of the policy.
type: string
name:
description: >
Human readable name of the policy.
type: string
pfId:
description: >
Identifier of the Policy Function (PF) which enforces the policy. Shall be present when the
PF is not the API producer and shall be absent otherwise.
Shall be absent when the API producer is NFVO-N.
More information concerning the PF can be found in ETSI GR NFV-IFA 023 [i.2].
For example, the PF can be a VNFM or VIM when the API producer is an NFVO.
$ref: "../components/SOL012_schemas.yaml#/components/schemas/Identifier"
associations:
description: >
Initial value of the “associations” attribute in the “Policy” data structure which represents the policy.
Shall be absent when the association feature is not applicable for the PF.
The associations refer to identifiers of entities that the PF manages. E.g., if the PF is a VNFM,
the policy can associate to VNF instances; if the PF is NFVO, the policy can associate to an NS instances.
How the PF determines the scope of applicability of the policy when this attribute is absent is
outside the scope of the present document.
type: array
items:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/Identifier"
required:
- designer
- name
Policy:
description: >-
This type represents an individual policy. It shall comply with the provisions defined in table 5.6.2.3-1.
type: object
properties:
id:
description: >
Identifier of the policy.
$ref: "../components/SOL012_schemas.yaml#/components/schemas/Identifier"
designer:
description: >
Human readable name of the designer of the policy.
type: string
name:
description: >
Human readable name of the policy.
type: string
pfId:
description: >
Identifier of the Policy Function (PF) which enforces the policy. Shall be present when the PF is not
the API producer and shall be absent otherwise.
Shall be absent when the API producer is NFVO-N.
More information concerning the PF can be found in ETSI GR NFV-IFA 023 [i.2].
For example, the PF can be a VNFM or VIM when the API producer is an NFVO.
$ref: "../components/SOL012_schemas.yaml#/components/schemas/Identifier"
versions:
description: >
Versions of the policy. Shall be present if at least one version of the policy has been transferred.
type: array
items:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/Version"
selectedVersion:
description: >
Selected version of the policy. Shall be present if one or more versions of the policy have been transferred.
$ref: "../components/SOL012_schemas.yaml#/components/schemas/Version"
activationStatus:
description: >
Status of the policy on whether it is activated or deactivated.
$ref: "../components/SOL012_schemas.yaml#/components/schemas/ActivationStatus"
transferStatus:
description: >
Status of the policy on whether the content of the policy has been transferred.
$ref: "../components/SOL012_schemas.yaml#/components/schemas/TransferStatus"
associations:
description: >
Identifiers of the entities that the PF manages and to which the policy associates to.
Shall be absent when the association feature is not applicable for the PF.
The associations refer to identifiers of entities that the PF manages.
E.g., if the PF is a VNFM, the policy can associate to VNF instances; if the PF is NFVO, the policy can
associate to an NS instances.
How the PF determines the scope of applicability of the policy when this attribute is absent is
outside the scope of the present document.
type: array
items:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/Identifier"
_links:
description: >
Links for this resource
type: object
properties:
self:
description: >
URI of this resource
$ref: "../components/SOL012_schemas.yaml#/components/schemas/Link"
selected:
description: >
URI of the selected version of this policy, if exists.
$ref: "../components/SOL012_schemas.yaml#/components/schemas/Link"
versions:
description: >
URIs of all the transferred versions of this policy, if exists.
type: array
items:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/Link"
required:
- self
required:
- id
- designer
- name
- activationStatus
- transferStatus
- _links
PolicySubscriptionRequest:
description: >
This type represents a subscription request related to notifications about policy changes
and policy conflicts. It shall comply with the provisions defined in table 5.6.2.5-1.
type: object
properties:
filter:
description: >
Filter settings for this subscription, to define the subset of all notifications this subscription relates to.
A particular notification is sent to the subscriber if the filter matches, or if there is no filter.
$ref: "#/components/schemas/PolicyNotificationsFilter"
callbackUri:
description: >
The URI of the endpoint to send the notification to.
$ref: "../components/SOL012_schemas.yaml#/components/schemas/Uri"
authentication:
description: >
Authentication parameters to configure the use of Authorization when sending notifications
corresponding to this subscription, as defined in clause 8.3.4 of ETSI GS NFV-SOL 013.
This attribute shall only be present if the subscriber requires authorization of notifications.
$ref: "../components/SOL012_schemas.yaml#/components/schemas/SubscriptionAuthentication"
required:
- callbackUri
PolicySubscription:
description: >
This type represents a subscription related to notifications about policy changes and policy conflicts.
It shall comply with the provisions defined in table 5.6.2.6-1.
type: object
properties:
id:
description: >
Identifier of this subscription resource.
$ref: "../components/SOL012_schemas.yaml#/components/schemas/Identifier"
filter:
description: >
Filter settings for this subscription, to define the subset of all notifications this subscription
relates to. A particular notification is sent to the subscriber if the filter matches, or if there
is no filter.
$ref: "#/components/schemas/PolicyNotificationsFilter"
callbackUri:
description: >
The URI of the endpoint to send the notification to.
$ref: "../components/SOL012_schemas.yaml#/components/schemas/Uri"
_links:
description: >
Links for this resource.
type: object
properties:
self:
description: >
URI of this resource.
$ref: "../components/SOL012_schemas.yaml#/components/schemas/Link"
required:
- self
required:
- id
- callbackUri
- _links
PolicyNotificationsFilter:
description: >
This type represents a subscription filter related to notifications about policy changes and policy conflicts.
It shall comply with the provisions defined in table 5.6.3.2-1.
At a particular nesting level in the filter structure, the following applies: All attributes shall match in
order for the filter to match (logical "and" between different filter attributes). If an attribute is an array,
the attribute shall match if at least one of the values in the array matches (logical "or" between the values
of one filter attribute).
type: object
properties:
notificationTypes:
description: >
Match particular notification types.
Permitted values:
- PolicyChangeNotification
- PolicyConflictNotification
The permitted values of the "notificationTypes" attribute are spelled exactly as the names of the notification
types to facilitate automated code generation systems.
type: array
items:
type: string
enum:
- PolicyChangeNotification
- PolicyConflictNotification
policyIds:
description: >
Match particular policy identifiers.
For "PolicyConflictNotification", the notification is sent if any of the policies specified in the subscription
is impacted by the conflict, as defined in clause 5.6.2.8.
type: array
items:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/Identifier"
changeTypes:
description: >
Match particular policy management operation types that cause the change of the policy.
type: array
items:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/PolicyOperationType"
responses:
Policy.Post.201:
description: >
201 Created
Shall be returned when a policy has been created successfully.
The response body shall contain a representation of the individual policy, as defined in clause 5.6.2.3.
The HTTP response shall include a "Location" HTTP header that contains the resource URI of the created policy.
headers:
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
Version:
description: >
Version of the API used in the response.
schema:
type: string
Location:
description: >
The resource URI of the created resource.
schema:
type: string
format: url
content:
application/json:
schema:
$ref: "#/components/schemas/Policy"
Policy.Get.200:
description: >
Shall be returned when information about zero or more policies has been queried successfully.
The response body shall contain in an array the representations of zero or more policies, as defined
in clause 5.6.2.3.
If the "filter" URI parameter was supplied in the request and is supported, the data in the response body
shall have been transformed according to the rules specified in clauses 5.2.2 and 5.3.2 of
ETSI GS NFV-SOL 013 [6], respectively.
If the API producer supports alternative 2 (paging) according to clause 5.4.2.1 of ETSI GS NFV-SOL 013 [6]
for this resource, inclusion of the Link HTTP header in this response shall follow the provisions in clause
5.4.2.3 of ETSI GS NFV-SOL 013 [6].
headers:
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
Version:
description: >
Version of the API used in the response.
schema:
type: string
Link:
description: >
Reference to other resources. Link HTTP header in this response
shall follow the provisions in clause 5.4.2.3 of ETSI GS NFV-SOL 013.
schema:
type: string
minimum: 0
maximum: 1
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Policy"
Policy.Get.400:
description: >
Shall be returned upon the following error: Invalid attribute-based filtering expression.
The response body shall contain a ProblemDetails structure, in which the "detail" attribute
should convey more information about the error.
Shall be returned upon the following error: Response too big.
If the API producer supports alternative 1 (error) according to clause 5.4.2.1 of ETSI GS NFV-SOL 013 [6]
for this resource, this error response shall follow the provisions in clause 5.4.2.2 of ETSI GS NFV-SOL 013 [6].
headers:
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
Version:
description: >
Version of the API used in the response.
schema:
type: string
content:
application/json:
schema:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/ProblemDetails"
IndividualPolicy.Get.200:
description: >
Shall be returned when information about an individual policy has been read successfully.
The response body shall contain a representation of the policy, as defined in clause 5.6.2.3.
headers:
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
Version:
description: >
Version of the API used in the response.
schema:
type: string
content:
application/json:
schema:
$ref: "#/components/schemas/Policy"
PolicyModifications.Patch.200:
description: >
200 OK
Shall be returned when the modifications have been processed successfully.
The response body shall contain a representation of modifications of the policy, as defined in clause 5.6.2.4.
headers:
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
Version:
description: >
Version of the API used in the response.
schema:
type: string
content:
application/json:
schema:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/PolicyModifications"
PolicyModifications.Patch.409:
description: >
409 Conflict
Shall be returned upon the following error: The operation cannot be executed currently, due to a conflict
with the state of the resource.
Typical reasons are attempts to:
• modify a policy in CREATED state;
• activate a policy in ACTIVATED state;
• deactivate a policy in DEACTIVATED state.
The response body shall contain a ProblemDetails structure, in which the "detail" attribute shall
convey more information about the error.
headers:
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
Version:
description: >
Version of the API used in the response.
schema:
type: string
content:
application/json:
schema:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/ProblemDetails"
Policy.Delete.204:
description: >
204 No Content
Shall be returned when the individual policy has been deleted successfully.
The response body shall be empty
headers:
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
Version:
description: >
Version of the API used in the response.
schema:
type: string
Policy.Delete.409:
description: >
409 Conflict
Shall be returned upon the following error: The operation cannot be executed currently, due to a
conflict with the state of the resource.
Typically, this is due to the fact that the policy is in ACTIVATED state.
The response body shall contain a ProblemDetails structure, in which the "detail" attribute shall
convey more information about the error.
headers:
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
Version:
description: >
Version of the API used in the response.
schema:
type: string
content:
application/json:
schema:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/ProblemDetails"
PolicySelectedVersion.Get.200:
description: >
200 OK
Shall be returned when the content of the selected version of an individual policy has been read successfully.
The response body shall include a copy of the policy content.
The "Content-Type" HTTP header shall be set according to the type of the policy content.
headers:
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
Version:
description: >
Version of the API used in the response.
schema:
type: string
Content-Type:
description: >
The "Content-Type" HTTP header shall be set according to the type of the policy content
schema:
type: string
content:
application/*:
schema:
type: object
additionalProperties: true
PolicySelectedVersion.Get.404:
description: >
404 Not Found
Shall be returned upon the following error: The API producer did not find a current representation for the
target resource or is not willing to disclose that one exists.
The general cause for this error and its handling is specified in clause 6.4 of ETSI GS NFV-SOL 013 [6],
including rules for the presence of the response body.
Specifically in case of this resource, the response code 404 shall also be returned if the policy is in
CREATED state.
In this case, the response body shall be present, and shall contain a ProblemDetails structure, in which
the "detail" attribute shall convey more information about the error.
headers:
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
Version:
description: >
Version of the API used in the response.
schema:
type: string
content:
application/json:
schema:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/ProblemDetails"
IndividualPolicyVersion.Get.200:
description: >
200 OK
Shall be returned when the content of a particular version of an individual policy has been read successfully.
The response body shall include a copy of the policy content.
The "Content-Type" HTTP header shall be set according to the type of the policy content.
headers:
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
Version:
description: >
Version of the API used in the response.
schema:
type: string
Content-Type:
description: >
The "Content-Type" HTTP header shall be set according to the type of the policy content
schema:
type: string
content:
application/*:
schema:
type: object
additionalProperties: true
PolicyVersionTransfer.Put.201:
description: >
201 Created
Shall be returned when the policy content has been transferred successfully.
The response body shall be empty.
headers:
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
Version:
description: >
Version of the API used in the response.
schema:
type: string
PolicyVersionTransfer.Put.409:
description: >
409 Conflict
Shall be returned upon the following error: The operation cannot be executed currently,
due to a conflict with an existing resource.
Typically, this is due to the fact that the particular version has already been transferred to the API producer.
The response body shall contain a ProblemDetails structure, in which the "detail" attribute shall convey more
information about the error.
headers:
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
Version:
description: >
Version of the API used in the response.
schema:
type: string
content:
application/json:
schema:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/ProblemDetails"
PolicyVersion.Delete.204:
description: >
204 No Content
Shall be returned when a particular version of an individual policy has been deleted successfully.
The response body shall be empty
headers:
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
Version:
description: >
Version of the API used in the response.
schema:
type: string
PolicyVersion.Delete.409:
description: >
409 Conflict
Shall be returned upon the following error: The operation cannot be executed currently, due to a
conflict with the state of the resource.
Typically, this is due to the fact that the requested version is the selected version.
The response body shall contain a ProblemDetails structure, in which the "detail" attribute shall
convey more information about the error.
headers:
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
Version:
description: >
Version of the API used in the response.
schema:
type: string
content:
application/json:
schema:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/ProblemDetails"
Subscriptions.Post.201:
description: >
201 Created
Shall be returned when the subscription has been created successfully.
A representation of the created subscription resource shall be returned in the response body,
as defined in clause 5.6.2.6.
The HTTP response shall include a "Location" HTTP header that points to the created
"Individual subscription" resource.
headers:
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided authorization, or error details
if the corresponding HTTP request has provided an invalid authorization token.
schema:
type: string
Version:
description: >
Version of the API used in the response.
schema:
type: string
Location:
description: >
The resource URI of the created resource.
schema:
type: string
format: url
content:
application/json:
schema:
$ref: "#/components/schemas/PolicySubscription"
Subscriptions.Post.303:
description: >
303 See Other
Shall be returned if a subscription with the same callbackUri and the same filter already exists
and the policy of the API producer is to not create redundant subscriptions.
The HTTP response shall include a "Location" HTTP header that contains the resource URI of
the existing "individual subscription" resource.
The response body shall be empty.
headers:
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided authorization, or error details
if the corresponding HTTP request has provided an invalid authorization token.
schema:
type: string
Version:
description: >
Version of the API used in the response.
schema:
type: string
Location:
description: >
The resource URI of the created resource.
schema:
type: string
format: url
Subscriptions.Get.200:
description: >
200 OK
Shall be returned when the list of subscriptions has been queried successfully.
The response body shall contain in an array the representations of all active subscriptions
of the functional block that invokes the method, i.e. zero or more representations of policy
subscriptions as defined in clause 5.6.2.6.
If the "filter" URI parameter was supplied in the request, the data in the response body shall
have been transformed according to the rules specified in clause 5.2.2 of ETSI GS NFV-SOL 013.
If the API producer supports alternative 2 (paging) according to clause 5.4.2.1 of
ETSI GS NFV-SOL 013 for this resource, inclusion of the Link HTTP header in this response
shall follow the provisions in clause 5.4.2.3 of ETSI GS NFV-SOL 013.
headers:
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided authorization, or error details
if the corresponding HTTP request has provided an invalid authorization token.
schema:
type: string
Version:
description: >
Version of the API used in the response.
schema:
type: string
Link:
description: >
Reference to other resources. Link HTTP header in this response shall follow the provisions
in clause 5.4.2.3 of ETSI GS NFV-SOL 013.
schema:
type: string
minimum: 0
maximum: 1
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/PolicySubscription"
Subscriptions.Get.400:
description: >
400 Bad Request
Shall be returned upon the following error: Invalid attribute-based filtering expression.
The response body shall contain a ProblemDetails structure, in which the "detail" attribute
should convey more information about the error.
Shall be returned upon the following error: Response too big.
If the API producer supports alternative 1 (error) according to clause 5.4.2.1 of ETSI GS NFV-SOL 013
for this resource, this error response shall follow the provisions in clause 5.4.2.2 of
ETSI GS NFV-SOL 013.
headers:
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided authorization, or error details
if the corresponding HTTP request has provided an invalid authorization token.
schema:
type: string
Version:
description: >
Version of the API used in the response.
schema:
type: string
content:
application/json:
schema:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/ProblemDetails"
IndividualSubscription.Get.200:
description: >
200 OK
Shall be returned when information about an individual subscription has been read successfully.
The response body shall contain a representation of the subscription resource, as defined in
clause 5.6.2.6.
headers:
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided authorization, or error details
if the corresponding HTTP request has provided an invalid authorization token.
schema:
type: string
Version:
description: >
Version of the API used in the response.
schema:
type: string
content:
application/json:
schema:
$ref: "#/components/schemas/PolicySubscription"
IndividualSubscription.Delete.204:
description: >
204 No Content
Shall be returned when the "individual subscription" resource has been deleted successfully.
The response body shall be empty.
headers:
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided authorization, or error details
if the corresponding HTTP request has provided an invalid authorization token.
schema:
type: string
Version:
description: >
Version of the API used in the response.
schema:
type: string
requestBodies:
CreatePolicyRequest:
description: >
This type represents request parameters for creating a policy. It shall comply with the provisions defined
in table 5.6.2.2-1.
content:
application/json:
schema:
$ref: "#/components/schemas/CreatePolicyRequest"
required: true
PolicyModifications:
description: >
The parameter for the policy modifications, as defined in clause 5.6.2.4.
content:
application/json:
schema:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/PolicyModifications"
PolicySubscriptionRequest:
description: >
Details of the subscription to be created.
content:
application/json:
schema:
$ref: "#/components/schemas/PolicySubscriptionRequest"
\ No newline at end of file
src/SOL012/PolicyManagementNotification/PolicyManagementNotification.yaml 0 → 100644
View file @ 68625d1f
openapi: 3.0.2
info:
version: 1.0.0-impl:etsi.org:ETSI_NFV_OpenAPI:1
title: SOL012 - Policy Management Notification Interface
description: >
SOL012 - Policy Management Notification Interface
IMPORTANT: Please note that this file might be not aligned to the current version of the ETSI Group Specification
it refers to. In case of discrepancies the published ETSI Group Specification takes precedence.
Please report bugs to https://forge.etsi.org/rep/nfv/SOL012/issues
license:
name: ETSI Forge copyright notice
url: https://forge.etsi.org/etsi-forge-copyright-notice.txt
externalDocs:
description: ETSI GS NFV-SOL 012 v3.4.1
url: https://www.etsi.org/deliver/etsi_gs/NFV-SOL/001_099/012/03.04.01_60/gs_nfv-sol012v030401p.pdf
security:
- OauthSecurity:
- all
servers:
- url: http://127.0.0.1/callback/v1
- url: https://127.0.0.1/callback/v1
paths:
/URI_is_provided_by_the_API_consumer_when_creating_the_subscription_PolicyChangeNotification:
description: >-
This resource represents a notification endpoint for policy management.
The API producer can use this resource to send notifications related to policy management events to
a subscribed API consumer, which has provided the URI of this resource during the subscription process.
parameters:
- $ref: "../components/SOL012_params.yaml#/components/parameters/Version"
- $ref: "../components/SOL012_params.yaml#/components/parameters/Accept"
- $ref: "../components/SOL012_params.yaml#/components/parameters/Authorization"
post:
description: >-
The POST method delivers a notification regarding a policy management event from the API producer
to an API consumer. The API consumer shall have previously created an "Individual subscription"
resource with a matching filter.
This method shall follow the provisions specified in the tables 5.5.9.3.1-1 and 5.5.9.3.1-2 for
URI query parameters, request and response data structures, and response codes.
Each notification request body shall include exactly one of the alternatives defined
in table 5.5.9.3.1-2.
parameters:
- $ref: "../components/SOL012_params.yaml#/components/parameters/ContentType"
requestBody:
$ref: "#/components/requestBodies/PolicyChangeNotification"
responses:
"204":
$ref: '#/components/responses/PolicyChangeNotification.Post.204'
"400":
$ref: ../components/SOL012_resp.yaml#/components/responses/400
"401":
$ref: ../components/SOL012_resp.yaml#/components/responses/401
"403":
$ref: ../components/SOL012_resp.yaml#/components/responses/403
"405":
$ref: ../components/SOL012_resp.yaml#/components/responses/405
"406":
$ref: ../components/SOL012_resp.yaml#/components/responses/406
"500":
$ref: ../components/SOL012_resp.yaml#/components/responses/500
"503":
$ref: ../components/SOL012_resp.yaml#/components/responses/503
get:
description: >-
The GET method allows the API producer to test the notification endpoint that is provided by the
API consumer, e.g. during subscription.
This method shall follow the provisions specified in the tables 5.5.9.3.2-1 and 5.5.9.3.2-2 for
URI query parameters, request and response data structures, and response codes.
responses:
"204":
$ref: '#/components/responses/PolicyChangeNotification.Get.204'
"400":
$ref: ../components/SOL012_resp.yaml#/components/responses/400
"401":
$ref: ../components/SOL012_resp.yaml#/components/responses/401
"403":
$ref: ../components/SOL012_resp.yaml#/components/responses/403
"405":
$ref: ../components/SOL012_resp.yaml#/components/responses/405
"406":
$ref: ../components/SOL012_resp.yaml#/components/responses/406
"500":
$ref: ../components/SOL012_resp.yaml#/components/responses/500
"503":
$ref: ../components/SOL012_resp.yaml#/components/responses/503
/URI_is_provided_by_the_API_consumer_when_creating_the_subscription_PolicyConflictNotification:
description: >-
This resource represents a notification endpoint for policy management.
The API producer can use this resource to send notifications related to policy management events to
a subscribed API consumer, which has provided the URI of this resource during the subscription process.
parameters:
- $ref: "../components/SOL012_params.yaml#/components/parameters/Version"
- $ref: "../components/SOL012_params.yaml#/components/parameters/Accept"
- $ref: "../components/SOL012_params.yaml#/components/parameters/Authorization"
post:
description: >-
The POST method delivers a notification regarding a policy management event from the API producer
to an API consumer. The API consumer shall have previously created an "Individual subscription"
resource with a matching filter.
This method shall follow the provisions specified in the tables 5.5.9.3.1-1 and 5.5.9.3.1-2 for
URI query parameters, request and response data structures, and response codes.
Each notification request body shall include exactly one of the alternatives defined
in table 5.5.9.3.1-2.
parameters:
- $ref: "../components/SOL012_params.yaml#/components/parameters/ContentType"
requestBody:
$ref: "#/components/requestBodies/PolicyConflictNotification"
responses:
"204":
$ref: '#/components/responses/PolicyConflictNotification.Post.204'
"400":
$ref: ../components/SOL012_resp.yaml#/components/responses/400
"401":
$ref: ../components/SOL012_resp.yaml#/components/responses/401
"403":
$ref: ../components/SOL012_resp.yaml#/components/responses/403
"405":
$ref: ../components/SOL012_resp.yaml#/components/responses/405
"406":
$ref: ../components/SOL012_resp.yaml#/components/responses/406
"500":
$ref: ../components/SOL012_resp.yaml#/components/responses/500
"503":
$ref: ../components/SOL012_resp.yaml#/components/responses/503
get:
description: >-
The GET method allows the API producer to test the notification endpoint that is provided by the
API consumer, e.g. during subscription.
This method shall follow the provisions specified in the tables 5.5.9.3.2-1 and 5.5.9.3.2-2 for
URI query parameters, request and response data structures, and response codes.
responses:
"204":
$ref: '#/components/responses/PolicyConflictNotification.Get.204'
"400":
$ref: ../components/SOL012_resp.yaml#/components/responses/400
"401":
$ref: ../components/SOL012_resp.yaml#/components/responses/401
"403":
$ref: ../components/SOL012_resp.yaml#/components/responses/403
"405":
$ref: ../components/SOL012_resp.yaml#/components/responses/405
"406":
$ref: ../components/SOL012_resp.yaml#/components/responses/406
"500":
$ref: ../components/SOL012_resp.yaml#/components/responses/500
"503":
$ref: ../components/SOL012_resp.yaml#/components/responses/503
components:
schemas:
PolicyChangeNotification:
description: >
This type represents a notification about policy change. It shall comply with the provisions
defined in table 5.6.2.7-1.
This notification shall be triggered by the API producer when a policy has been changed as
the result of an operation of creating, transferring, deleting or modifying a policy.
type: object
properties:
id:
description: >
Identifier of this notification. If a notification is sent multiple times due to multiple
subscriptions, the "id" attribute of all these notifications shall have the same value.
$ref: "../components/SOL012_schemas.yaml#/components/schemas/Identifier"
notificationType:
description: >
Discriminator for the different notification types. Shall be set to "PolicyChangeNotification"
for this notification type.
$ref: "../components/SOL012_schemas.yaml#/components/schemas/String"
subscriptionId:
description: >
Identifier of the subscription that this notification relates to.
$ref: "../components/SOL012_schemas.yaml#/components/schemas/Identifier"
timeStamp:
description: >
Date and time of the generation of the notification.
$ref: "../components/SOL012_schemas.yaml#/components/schemas/DateTime"
policyId:
description: >
Identifier of the policy.
$ref: "../components/SOL012_schemas.yaml#/components/schemas/Identifier"
affectedVersion:
description: >
Affected version of the policy.
The value is the version identifier in the URI when a particular version of the policy
is transferred or deleted, or the selected version of the policy when the policy is
activated/deactivated/modified.
Shall be present when a particular version of the policy is impacted by the policy
management operation.
Shall be absent otherwise.
$ref: "../components/SOL012_schemas.yaml#/components/schemas/Version"
previousSelectedVersion:
description: >
The previous selected version of the policy.
Shall be present when another version of the policy has been selected.
Shall be absent otherwise.
$ref: "../components/SOL012_schemas.yaml#/components/schemas/Version"
policyModifications:
description: >
Information about the modifications of the policy. Shall be present when the changeType
equals to "MODIFY_POLICY". Shall be absent otherwise.
$ref: "../components/SOL012_schemas.yaml#/components/schemas/PolicyModifications"
changeType:
description: >
Policy management operation that cause the change of the policy.
$ref: "../components/SOL012_schemas.yaml#/components/schemas/PolicyOperationType"
_links:
description: >
Links to resources related to this notification.
type: object
properties:
subscription:
description: >
Link to the related subscription.
$ref: "../components/SOL012_schemas.yaml#/components/schemas/NotificationLink"
objectInstance:
description: >
Link to the resource representing the policies to which the notified change applies.
Shall be present if the policy is accessible as a resource.
$ref: "../components/SOL012_schemas.yaml#/components/schemas/NotificationLink"
required:
- subscription
required:
- id
- notificationType
- subscriptionId
- timeStamp
- policyId
- changeType
- _links
PolicyConflictNotification:
description: >
This type represents a notification about policy conflict. It shall comply with the provisions
defined in table 5.6.2.8-1.
This notification shall be triggered by the API producer when a policy conflict is detected,
and any of the policies specified in an associated notification subscription is impacted
by the conflict.
type: object
properties:
id:
description: >
Identifier of this notification. If a notification is sent multiple times due to multiple
subscriptions, the "id" attribute of all these notifications shall have the same value.
$ref: "../components/SOL012_schemas.yaml#/components/schemas/Identifier"
notificationType:
description: >
Discriminator for the different notification types. Shall be set to "PolicyConflictNotification"
for this notification type.
$ref: "../components/SOL012_schemas.yaml#/components/schemas/String"
subscriptionId:
description: >
Identifier of the subscription that this notification relates to.
$ref: "../components/SOL012_schemas.yaml#/components/schemas/Identifier"
timeStamp:
description: >
Date and time of the generation of the notification.
$ref: "../components/SOL012_schemas.yaml#/components/schemas/DateTime"
policyIds:
description: >
Identifiers of the conflicting policies.
The policy identifier and the corresponding selected version are mapped by the order
in the array.
type: array
items:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/Identifier"
minItems: 2
selectedVersions:
description: >
Selected versions of the conflicting policies.
The policy identifier and the corresponding selected version are mapped by the order
in the array.
type: array
items:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/Version"
minItems: 2
conflictDescription:
description: >
Description of the detected policy conflicts, e.g. conflicting events, conditions
or actions among the policies
$ref: "../components/SOL012_schemas.yaml#/components/schemas/String"
_links:
description: >
Links to resources related to this notification.
type: object
properties:
subscription:
description: >
Link to the related subscription.
$ref: "../components/SOL012_schemas.yaml#/components/schemas/NotificationLink"
objectInstances:
description: >
Link to the resources representing the policies to which the notified conflict applies.
type: array
items:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/NotificationLink"
minItems: 2
required:
- subscription
- objectInstances
required:
- id
- notificationType
- subscriptionId
- timeStamp
- policyIds
- selectedVersions
- conflictDescription
- _links
responses:
PolicyChangeNotification.Post.204:
description: >
204 No Content
Shall be returned when the notification has been delivered successfully.
headers:
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided authorization, or error details
if the corresponding HTTP request has provided an invalid authorization token.
schema:
type: string
Version:
description: >
Version of the API used in the response.
schema:
type: string
PolicyChangeNotification.Get.204:
description: >
204 No Content
Shall be returned to indicate that the notification endpoint has been tested successfully.
The response body shall be empty.
headers:
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided authorization, or error details
if the corresponding HTTP request has provided an invalid authorization token.
schema:
type: string
Version:
description: >
Version of the API used in the response.
schema:
type: string
PolicyConflictNotification.Post.204:
description: >
204 No Content
Shall be returned when the notification has been delivered successfully.
headers:
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided authorization, or error details
if the corresponding HTTP request has provided an invalid authorization token.
schema:
type: string
Version:
description: >
Version of the API used in the response.
schema:
type: string
PolicyConflictNotification.Get.204:
description: >
204 No Content
Shall be returned to indicate that the notification endpoint has been tested successfully.
The response body shall be empty.
headers:
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided authorization, or error details
if the corresponding HTTP request has provided an invalid authorization token.
schema:
type: string
Version:
description: >
Version of the API used in the response.
schema:
type: string
requestBodies:
PolicyChangeNotification:
description: |
A notification about policy changes.
content:
application/json:
schema:
$ref: "#/components/schemas/PolicyChangeNotification"
required: true
PolicyConflictNotification:
description: |
A notification about a detected policy conflict.
content:
application/json:
schema:
$ref: "#/components/schemas/PolicyConflictNotification"
required: true
src/SOL012/components/SOL012_params.yaml 0 → 100644
View file @ 68625d1f
components:
parameters:
Version:
name: Version
description: >
Version of the API requested to use when responding to this request.
in: header
required: true
schema:
type: string
Accept:
name: Accept
description: >
Content-Types that are acceptable for the response. Reference: IETF RFC 7231.
in: header
required: true
schema:
type: string
Authorization:
name: Authorization
description: >
The authorization token for the request. Reference: IETF RFC 7235.
in: header
required: false
schema:
type: string
ContentType:
name: Content-Type
description: |
The MIME type of the body of the request. Reference: IETF RFC 7231
in: header
required: true
schema:
type: string
filter:
name: filter
description: >
Attribute-based filtering expression according to clause 5.2 of ETSI
GS NFV-SOL 013. The NFV-MANO functional entity shall support
receiving this parameter as part of the URI query string. The API
consumer may supply this parameter. All attribute names that appear
in the FmSubscription and in data types referenced from it shall be
supported by the NFV-MANO functional entity in the filter
expression.
in: query
required: false
schema:
type: string
all_fields:
name: all_fields
description: >
Include all complex attributes in the response. See clause
5.3 of ETSI GS NFV-SOL 013. The NFV-MANO functional entity
shall support this parameter.
in: query
required: false
schema:
type: string
fields:
name: fields
description: >
Complex attributes to be included into the response. See clause
5.3 of ETSI GS NFV-SOL 013 for details. The NFV-MANO functional
entity should support this parameter.
in: query
required: false
schema:
type: string
exclude_fields:
name: exclude_fields
description: >
Complex attributes to be excluded from the response. See clause
5.3 of ETSI GS NFV-SOL 013 for details. The NFV-MANO functional
entity should support this parameter.
in: query
required: false
schema:
type: string
exclude_default:
name: exclude_default
in: query
description: >-
Indicates to exclude the following complex attributes from the response. See clause 5.3 of ETSI GS NFV-SOL 013
for details. The NFV-MANO functional entity shall support this parameter.
required: false
schema:
type: string
nextpage_opaque_marker:
name: nextpage_opaque_marker
description: >
Marker to obtain the next page of a paged response. Shall be supported by
the NFV-MANO functional entity if the entity supports alternative 2 (paging)
according to clause 5.4.2.1 of ETSI GS NFV-SOL 013 for this resource.
in: query
required: false
schema:
type: string
src/SOL012/components/SOL012_resp.yaml 0 → 100644
View file @ 68625d1f
components:
responses:
206:
description: >
206 PARTIAL CONTENT
headers:
Content-Type:
description: >
The MIME type of the body of the response.
schema:
type: string
maximum: 1
minimum: 1
Content-Range:
description: >
The Content-Range response HTTP header indicates where in a full body message a partial message belongs.
schema:
type: string
maximum: 1
minimum: 1
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
maximum: 1
minimum: 0
Version:
description: >
Version of the API used in the response.
schema:
type: string
maximum: 1
minimum: 1
content:
application/json:
schema:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/ProblemDetails"
303:
description: >
303 See Other
headers:
Content-Type:
description: The MIME type of the body of the response.
schema:
type: string
maximum: 1
minimum: 1
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
maximum: 1
minimum: 0
Version:
description: >
Version of the API used in the response.
schema:
type: string
maximum: 1
minimum: 1
400:
description: >
400 BAD REQUEST
400 code can be returned in the following specified cases, the specific cause has to be proper specified in the
"ProblemDetails" structure to be returned.
If the request is malformed or syntactically incorrect (e.g. if the request URI contains incorrect
query parameters or the payload body contains a syntactically incorrect data structure),
the API producer shall respond with this response code. The "ProblemDetails" structure shall be provided,
and should include in the "detail" attribute more information about the source of the problem.
If the response to a GET request which queries a container resource would be so big that the performance
of the API producer is adversely affected, and the API producer does not support paging for the affected resource,
it shall respond with this response code. The "ProblemDetails" structure shall be provided, and should include
in the "detail" attribute more information about the source of the problem.
If there is an application error related to the client's input that cannot be easily mapped to any other
HTTP response code ("catch all error"), the API producer shall respond with this response code.
The "ProblemDetails" structure shall be provided, and shall include in the "detail" attribute more information
about the source of the problem.
If the request contains a malformed access token, the API producer should respond with this response.
The details of the error shall be returned in the WWW Authenticate HTTP header, as defined in IETF RFC 6750
and IETF RFC 7235. The ProblemDetails structure may be provided.
The use of this HTTP error response code described above is applicable to the use of the OAuth 2.0
for the authorization of API requests and notifications, as defined in clauses 4.5.3.3 and 4.5.3.4.
headers:
Content-Type:
description: The MIME type of the body of the response.
schema:
type: string
maximum: 1
minimum: 1
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
maximum: 1
minimum: 0
Version:
description: >
Version of the API used in the response.
schema:
type: string
maximum: 1
minimum: 1
content:
application/json:
schema:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/ProblemDetails"
401:
description: >
401 UNAUTHORIZED
If the request contains no access token even though one is required, or if the request contains an authorization
token that is invalid (e.g. expired or revoked), the API producer should respond with this response.
The details of the error shall be returned in the WWW-Authenticate HTTP header, as defined in IETF RFC 6750
and IETF RFC 7235. The ProblemDetails structure may be provided.
headers:
Content-Type:
description: The MIME type of the body of the response.
schema:
type: string
maximum: 1
minimum: 1
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
maximum: 1
minimum: 0
Version:
description: >
Version of the API used in the response.
schema:
type: string
maximum: 1
minimum: 1
content:
application/json:
schema:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/ProblemDetails"
403:
description: >
403 FORBIDDEN
If the API consumer is not allowed to perform a particular request to a particular resource,
the API producer shall respond with this response code. The "ProblemDetails" structure shall be provided.
It should include in the "detail" attribute information about the source of the problem,
and may indicate how to solve it.
headers:
Content-Type:
description: The MIME type of the body of the response.
schema:
type: string
maximum: 1
minimum: 1
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
maximum: 1
minimum: 0
Version:
description: >
Version of the API used in the response.
schema:
type: string
maximum: 1
minimum: 1
content:
application/json:
schema:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/ProblemDetails"
404:
description: >
404 NOT FOUND
If the API producer did not find a current representation for the resource addressed by the URI passed
in the request or is not willing to disclose that one exists, it shall respond with this response code.
The "ProblemDetails" structure may be provided, including in the "detail" attribute information about
the source of the problem, e.g. a wrong resource URI variable.
This response code is not appropriate in case the resource addressed by the URI is a container resource
which is designed to contain child resources, but does not contain any child resource at the time
the request is received. For a GET request to an existing empty container resource, a typical response
contains a 200 OK response code and a payload body with an empty array.
headers:
Content-Type:
description: The MIME type of the body of the response.
schema:
type: string
maximum: 1
minimum: 1
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
maximum: 1
minimum: 0
Version:
description: >
Version of the API used in the response.
schema:
type: string
maximum: 1
minimum: 1
content:
application/json:
schema:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/ProblemDetails"
405:
description: >
405 METHOD NOT ALLOWED
If a particular HTTP method is not supported for a particular resource, the API producer shall respond
with this response code. The "ProblemDetails" structure may be omitted.
headers:
Content-Type:
description: The MIME type of the body of the response.
schema:
type: string
maximum: 1
minimum: 1
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
maximum: 1
minimum: 0
Version:
description: >
Version of the API used in the response.
schema:
type: string
maximum: 1
minimum: 1
content:
application/json:
schema:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/ProblemDetails"
406:
description: >
406 NOT ACCEPTABLE
If the "Accept" HTTP header does not contain at least one name of a content type
that is acceptable to the API producer, the API producer shall respond with this
response code. The "ProblemDetails" structure may be omitted.
headers:
Content-Type:
description: The MIME type of the body of the response.
schema:
type: string
maximum: 1
minimum: 1
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
maximum: 1
minimum: 0
Version:
description: >
Version of the API used in the response.
schema:
type: string
maximum: 1
minimum: 1
content:
application/json:
schema:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/ProblemDetails"
409:
description: >
409 CONFLICT
headers:
Content-Type:
description: The MIME type of the body of the response.
schema:
type: string
maximum: 1
minimum: 1
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
maximum: 1
minimum: 0
Version:
description: >
Version of the API used in the response.
schema:
type: string
maximum: 1
minimum: 1
content:
application/json:
schema:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/ProblemDetails"
412:
description: >
412 PRECONDITION FAILED
Error: A precondition given in an HTTP request header is not fulfilled.
Typically, this is due to an ETag mismatch, indicating that the resource was modified by another entity.
The response body should contain a ProblemDetails structure, in which the "detail" attribute should convey
more information about the error.
headers:
Content-Type:
description: The MIME type of the body of the response.
schema:
type: string
maximum: 1
minimum: 1
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
maximum: 1
minimum: 0
Version:
description: >
Version of the API used in the response.
schema:
type: string
maximum: 1
minimum: 1
content:
application/json:
schema:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/ProblemDetails"
413:
description: >
413 PAYLOAD TOO LARGE
If the payload body of a request is larger than the amount of data the API producer is willing or able to process,
it shall respond with this response code, following the provisions in IETF RFC 7231 for the use
of the "Retry-After" HTTP header and for closing the connection. The "ProblemDetails" structure may be omitted.
headers:
Content-Type:
description: The MIME type of the body of the response.
schema:
type: string
maximum: 1
minimum: 1
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
maximum: 1
minimum: 0
Version:
description: >
Version of the API used in the response.
schema:
type: string
maximum: 1
minimum: 1
content:
application/json:
schema:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/ProblemDetails"
414:
description: >
414 URI TOO LONG
If the request URI of a request is longer than the API producer is willing or able to process,
it shall respond with this response code. This condition can e.g. be caused by passing long queries
in the request URI of a GET request. The "ProblemDetails" structure may be omitted.
headers:
Content-Type:
description: The MIME type of the body of the response.
schema:
type: string
maximum: 1
minimum: 1
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
maximum: 1
minimum: 0
Version:
description: >
Version of the API used in the response.
schema:
type: string
maximum: 1
minimum: 1
content:
application/json:
schema:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/ProblemDetails"
416:
description: >
416 Range Not Satisfiable
headers:
Content-Type:
description: The MIME type of the body of the response.
schema:
type: string
maximum: 1
minimum: 1
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
maximum: 1
minimum: 0
Version:
description: >
Version of the API used in the response.
schema:
type: string
maximum: 1
minimum: 1
content:
application/json:
schema:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/ProblemDetails"
422:
description: >
422 UNPROCESSABLE ENTITY
If the payload body of a request contains syntactically correct data (e.g. well-formed JSON) but the data
cannot be processed (e.g. because it fails validation against a schema), the API producer shall respond
with this response code. The "ProblemDetails" structure shall be provided, and should include in the "detail"
attribute more information about the source of the problem.
This error response code is only applicable for methods that have a request body.
headers:
Content-Type:
description: The MIME type of the body of the response.
schema:
type: string
maximum: 1
minimum: 1
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
maximum: 1
minimum: 0
Version:
description: >
Version of the API used in the response.
schema:
type: string
maximum: 1
minimum: 1
content:
application/json:
schema:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/ProblemDetails"
429:
description: >
429 TOO MANY REQUESTS
If the API consumer has sent too many requests in a defined period of time and the API producer is able
to detect that condition ("rate limiting"), the API producer shall respond with this response code,
following the provisions in IETF RFC 6585 [17] for the use of the "Retry-After" HTTP header.
The "ProblemDetails" structure shall be provided and shall include in the "detail" attribute more information
about the source of the problem.
The period of time and allowed number of requests are configured within the API producer by means
outside the scope of the present document.
headers:
Content-Type:
description: The MIME type of the body of the response.
schema:
type: string
maximum: 1
minimum: 1
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
maximum: 1
minimum: 0
Version:
description: >
Version of the API used in the response.
schema:
type: string
maximum: 1
minimum: 1
content:
application/json:
schema:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/ProblemDetails"
500:
description: >
500 INTERNAL SERVER ERROR
If there is an application error not related to the client's input that cannot be easily mapped to any other
HTTP response code ("catch all error"), the API producer shall respond with this response code.
The "ProblemDetails" structure shall be provided, and shall include in the "detail" attribute more information
about the source of the problem.
headers:
Content-Type:
description: The MIME type of the body of the response.
schema:
type: string
maximum: 1
minimum: 1
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
maximum: 1
minimum: 0
Version:
description: >
Version of the API used in the response.
schema:
type: string
maximum: 1
minimum: 1
content:
application/json:
schema:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/ProblemDetails"
503:
description: >
503 SERVICE UNAVAILABLE
If the API producer encounters an internal overload situation of itself or of a system it relies on,
it should respond with this response code, following the provisions in IETF RFC 7231 for the use of
the "Retry-After" HTTP header and for the alternative to refuse the connection. The "ProblemDetails"
structure may be omitted.
headers:
Content-Type:
description: The MIME type of the body of the response.
schema:
type: string
maximum: 1
minimum: 1
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
maximum: 1
minimum: 0
Version:
description: >
Version of the API used in the response.
schema:
type: string
maximum: 1
minimum: 1
content:
application/json:
schema:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/ProblemDetails"
504:
description: >
504 GATEWAY TIMEOUT
If the API producer encounters a timeout while waiting for a response from an upstream server
(i.e. a server that the API producer communicates with when fulfilling a request), it should respond
with this response code.
headers:
Content-Type:
description: The MIME type of the body of the response.
schema:
type: string
maximum: 1
minimum: 1
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
maximum: 1
minimum: 0
Version:
description: >
Version of the API used in the response.
schema:
type: string
maximum: 1
minimum: 1
content:
application/json:
schema:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/ProblemDetails"
\ No newline at end of file
src/SOL012/components/SOL012_schemas.yaml 0 → 100644
View file @ 68625d1f
components:
schemas:
Link:
description: >
This type represents a link to a resource using an absolute URI.
type: object
required:
- href
properties:
href:
description: >
URI of another resource referenced from a resource.
Shall be an absolute URI (i.e. a UTI that contains {apiRoot}).
$ref: "#/components/schemas/Uri"
NotificationLink:
description: >
This type represents a link to a resource in a notification, using an absolute or relative URI.
type: object
required:
- href
properties:
href:
description: >
URI of a resource referenced from a notification.
Should be an absolute URI (i.e. a URI that contains
{apiRoot}), however, may be a relative URI (i.e. a URI
where the {apiRoot} part is omitted) if the {apiRoot}
information is not available.
$ref: "#/components/schemas/Uri"
IpAddress:
description: >
An IPV4 or IPV6 address. Representation: In case of an IPV4 address, string that consists of four decimal
integers separated by dots, each integer ranging from 0 to 255. In case of an IPV6 address, string that
consists of groups of zero to four hexadecimal digits, separated by colons.
type: string
format: IP
KeyValuePairs:
description: >
This type represents a list of key-value pairs. The order of the pairs in the list is not significant. In JSON,
a set of keyvalue pairs is represented as an object. It shall comply with the provisions defined in clause 4
of IETF RFC 8259. In the following example, a list of key-value pairs with four keys ("aString", "aNumber",
"anArray" and "anObject") is provided to illustrate that the values associated with different keys can be of
different type.
type: object
ApiVersionInformation:
description: >
This type represents API version information.
type: object
required:
- uriPrefix
- apiVersions
properties:
uriPrefix:
description: >
Specifies the URI prefix for the API, in the following
form {apiRoot}/{apiName}/{apiMajorVersion}/.
type: string
apiVersions:
description: >
Version(s) supported for the API signaled by the
uriPrefix attribute.
type: array
items:
type: object
required:
- version
properties:
version:
description: >
Identifies a supported version. The value of the
version attribute shall be a version identifier as
specified in clause 9.1 (SOL013).
type: string
isDeprecated:
description: >
If such information is available, this attribute indicates
whether use of the version signaled by the version
attribute is deprecated (true) or not (false).
A deprecated version is still supported by the API producer but is recommended
not to be used any longer.
When a version is no longer supported, it does not appear in the response body.
type: boolean
retirementDate:
description: >
The date and time after which the API version will no
longer be supported.
This attribute may be included if the value of the
isDeprecated attribute is set to true and shall be
absent otherwise.
$ref: "#/components/schemas/DateTime"
Identifier:
description: >
An identifier with the intention of being globally unique.
type: string
IdentifierLocal:
description: >
An identifier that is unique within a limited local scope other than above listed identifiers,
such as within a complex data structure or within a request-response pair.
Representation: string of variable length.
type: string
DateTime:
description: >
Date-time stamp.
Representation: String formatted according to IETF RFC 3339.
type: string
format: date-time
Uri:
description: >
String formatted according to IETF RFC 3986.
type: string
Boolean:
description: >
The Boolean is a data type having two values (true and false).
type: boolean
Version:
description: >
A version.
type: string
String:
description: >
A string defined in IETF RFC 8259.
type: string
Number:
description: >
A number defined in IETF RFC 8259.
type: number
UnsignedInt:
description: >
Unsigned integer
type: number
SubscriptionAuthentication:
type: object
required:
- authType
properties:
authType:
description: >
Defines the types of Authentication / Authorization which the API
consumer is willing to accept when receiving a notification.
Permitted values:
* BASIC: In every HTTP request to the notification endpoint, use
HTTP Basic authentication with the client credentials.
* OAUTH2_CLIENT_CREDENTIALS: In every HTTP request to the
notification endpoint, use an OAuth 2.0 Bearer token, obtained
using the client credentials grant type.
* TLS_CERT: Every HTTP request to the notification endpoint is sent
over a mutually authenticated TLS session, i.e. not only the
server is authenticated, but also the client is authenticated
during the TLS tunnel setup.
type: array
items:
type: string
enum:
- BASIC
- OAUTH2_CLIENT_CREDENTIALS
- TLS_CERT
paramsBasic:
description: >
Parameters for authentication/authorization using BASIC.
Shall be present if authType is "BASIC" and the contained
information has not been provisioned out of band.
Shall be absent otherwise.
type: object
properties:
userName:
description: >
Username to be used in HTTP Basic authentication. Shall be
present if it has not been provisioned out of band.
type: string
password:
description: >
Password to be used in HTTP Basic authentication. Shall be
present if it has not been provisioned out of band.
type: string
paramsOauth2ClientCredentials:
description: >
Parameters for authentication/authorization using
OAUTH2_CLIENT_CREDENTIALS.
Shall be present if authType is "OAUTH2_CLIENT_CREDENTIALS" and the
contained information has not been provisioned out of band.
Shall be absent otherwise.
type: object
properties:
clientId:
description: >
Client identifier to be used in the access token request of the
OAuth 2.0 client credentials grant type.
Shall be present if it has not been provisioned out of band.
The clientId and clientPassword passed in a subscription shall
not be the same as the clientId and clientPassword that are used
to obtain authorization for API requests. Client credentials may
differ between subscriptions. The value of clientPassword should
be generated by a random process.
type: string
clientPassword:
description: >
Client password to be used in the access token request of the
OAuth 2.0 client credentials grant type.
Shall be present if it has not been provisioned out of band.
The clientId and clientPassword passed in a subscription shall
not be the same as the clientId and clientPassword that are used
to obtain authorization for API requests. Client credentials may
differ between subscriptions. The value of clientPassword should
be generated by a random process.
type: string
tokenEndpoint:
description: >
The token endpoint from which the access token can be obtained.
Shall be present if it has not been provisioned out of band.
$ref: "#/components/schemas/Uri"
ProblemDetails:
description: >
The definition of the general "ProblemDetails" data structure from
IETF RFC 7807 [19] is reproduced inthis structure. Compared to the
general framework defined in IETF RFC 7807 [19], the "status" and
"detail" attributes are mandated to be included by the present document,
to ensure that the response contains additional textual information about
an error. IETF RFC 7807 [19] foresees extensibility of the
"ProblemDetails" type. It is possible that particular APIs in the present
document, or particular implementations, define extensions to define
additional attributes that provide more information about the error.
The description column only provides some explanation of the meaning to
Facilitate understanding of the design. For a full description, see
IETF RFC 7807 [19].
type: object
required:
- status
- detail
properties:
type:
description: >
A URI reference according to IETF RFC 3986 [5] that identifies the
problem type. It is encouraged that the URI provides human-readable
documentation for the problem (e.g. using HTML) when dereferenced.
When this member is not present, its value is assumed to be
"about:blank".
type: string
format: URI
title:
description: >
A short, human-readable summary of the problem type. It should not
change from occurrence to occurrence of the problem, except for
purposes of localization. If type is given and other than
"about:blank", this attribute shall also be provided.
A short, human-readable summary of the problem
type. It SHOULD NOT change from occurrence to occurrence of the
problem, except for purposes of localization (e.g., using
proactive content negotiation; see [RFC7231], Section 3.4).
type: string
status:
description: >
The HTTP status code for this occurrence of the problem.
The HTTP status code ([RFC7231], Section 6) generated by the origin
server for this occurrence of the problem.
type: integer
detail:
description: >
A human-readable explanation specific to this occurrence of the
problem.
type: string
instance:
description: >
A URI reference that identifies the specific occurrence of the
problem. It may yield further information if dereferenced.
type: string
format: URI
#TODO: How to express "any additional attributes"?
ActivationStatus:
description: >
The enumeration ActivationStatus shall comply with the provisions defined in table 5.6.4.3-1.
It indicates the activation status of a policy.
type: string
enum:
- ACTIVATED
- DEACTIVATED
TransferStatus:
description: >
The enumeration TransferStatus shall comply with the provisions defined in table 5.6.4.4-1.
It indicates the transfer status of a policy
type: string
enum:
- CREATED
- TRANSFERRED
PolicyModifications:
description: >
This type represents the parameters for modifying a policy. It shall comply with the provisions
defined in table 5.6.2.4-1
type: object
properties:
activationStatus:
description: >
New activation status of the policy.
$ref: "#/components/schemas/ActivationStatus"
selectedVersion:
description: >
New version of the policy to be selected.
$ref: "../components/SOL012_schemas.yaml#/components/schemas/Version"
addAssociations:
description: >
Identifiers of entities to be added to the “associations” attribute in the “Policy”
data structure which represents the policy.
The API producer shall ignore the identifiers that already exist in the "associations"
attribute in the “Policy” data structure.
Shall be absent when the association feature is not applicable for the PF.
type: array
items:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/Identifier"
removeAssociations:
description: >
Identifiers of entities to be removed from the “associations” attribute in the “Policy” data structure
which represents the policy.
The API producer shall ignore the identifiers that do not exist in the "associations"
attribute in the “Policy” data structure.
Shall be absent when the association feature is not applicable for the PF.
type: array
items:
$ref: "../components/SOL012_schemas.yaml#/components/schemas/Identifier"
removeAllAssociations:
description: >
Shall be set to TRUE if the policy is no longer associated to any specific entities managed by the PF.
Shall be absent when the association feature is not applicable for the PF.
If "removeAllAssociations" is set to TRUE, neither "addAssociations" nor “removeAssociations” attributes
shall be present.
Once all associations have been removed, how the PF determines the scope of applicability of
the policy is outside the scope of the present document.
type: boolean
PolicyOperationType:
description: >
The enumeration PolicyOperationType shall comply with the provisions defined in table 5.6.4.4-1.
It indicates the type of the policy change.
Permitted values:
* CREATE_POLICY: The policy is created.
* TRANSFER_POLICY: The policy is transferred.
* DELETE_POLICY: The policy is deleted.
* MODIFY_POLICY: The policy is modified.
type: string
enum:
- CREATE_POLICY
- TRANSFER_POLICY
- DELETE_POLICY
- MODIFY_POLICY
\ No newline at end of file
src/SOL012/endpoints/SOL012_endpoints.yaml 0 → 100644
View file @ 68625d1f
# Copyright (c) ETSI 2019.
# https://forge.etsi.org/etsi-forge-copyright-notice.txt
endpoints:
api_versions:
parameters:
- name: Version
description: >
Version of the API requested to use when responding to this request.
in: header
required: false
schema:
type: string
- name: Authorization
description: >-
The authorization token for the request. Reference: IETF RFC 7235
in: header
required: false
schema:
type: string
get:
summary: Retrieve API version information
description: >
The GET method reads API version information. This method shall follow the provisions specified in
table 4.6.3.3.3.2-1 for request and response data structures, and response codes. URI query parameters are not
supported.
responses:
200:
description: >
200 OK
API version information was read successfully.
The response body shall contain 4.4 API version
information, as defined in clause 4.4.1.13.
content:
application/json:
schema:
$ref: '../components/SOL012_schemas.yaml#/components/schemas/ApiVersionInformation'
headers:
Content-Type:
description: The MIME type of the body of the response.
schema:
type: string
maximum: 1
minimum: 1
WWW-Authenticate:
description: >
Challenge if the corresponding HTTP request has not provided
authorization, or error details if the corresponding HTTP
request has provided an invalid authorization token.
schema:
type: string
maximum: 1
minimum: 0
Version:
description: The used API version.
schema:
type: string
maximum: 1
minimum: 1
400:
$ref: '../components/SOL012_resp.yaml#/components/responses/400'
401:
$ref: '../components/SOL012_resp.yaml#/components/responses/401'
403:
$ref: '../components/SOL012_resp.yaml#/components/responses/403'
404:
$ref: '../components/SOL012_resp.yaml#/components/responses/404'
405:
$ref: '../components/SOL012_resp.yaml#/components/responses/405'
406:
$ref: '../components/SOL012_resp.yaml#/components/responses/406'
413:
$ref: '../components/SOL012_resp.yaml#/components/responses/413'
414:
$ref: '../components/SOL012_resp.yaml#/components/responses/414'
416:
$ref: '../components/SOL012_resp.yaml#/components/responses/416'
422:
$ref: '../components/SOL012_resp.yaml#/components/responses/422'
429:
$ref: '../components/SOL012_resp.yaml#/components/responses/429'
500:
$ref: '../components/SOL012_resp.yaml#/components/responses/500'
503:
$ref: '../components/SOL012_resp.yaml#/components/responses/503'
504:
$ref: '../components/SOL012_resp.yaml#/components/responses/504'
\ No newline at end of file