OpenCAPIF SDK release notes
Release 1.0.0
Version 1.0.0 includes changes that are not backward compatible with the 0.1.x versions. Check the first list below before upgrading.
Changes that may require action when upgrading
- The SDK no longer configures logging when imported. It does not create a
logs/folder or change your application's logging anymore, anddebug_modeno longer enables theurllib3(HTTP) debug logs. To keep getting the SDK logs, callenable_default_logging(), as explained in OpenCAPIF SDK logs. - Fewer dependencies.
pip install opencapif_sdknow installs only what the SDK uses, andPyJWTis now declared explicitly. Flask, Flask-JWT-Extended, Werkzeug, Jinja2, MarkupSafe, connexion, python-dateutil, six, text-unidecode and typing-extensions are no longer installed with the SDK. If your code uses any of them, install them yourself, or usepip install "opencapif_sdk[samples]"for the Flask-based samples. pyOpenSSLreplaced bycryptography. Keys and certificate signing requests (CSRs) are now created withcryptography50.x, the same version used by the OpenCAPIF services, andpyOpenSSLis no longer installed with the SDK (its latest versions no longer include the CSR functions that the SDK used). The keys and CSRs are equivalent to the previous ones (RSA 2048, SHA-256 and the same subject fields), so provider and invoker folders created with earlier versions keep working. If your code importsOpenSSL, installpyOpenSSLyourself.- Event subscription methods renamed.
update_subcription()andpatch_subcription()are nowupdate_subscription()andpatch_subscription(), in bothcapif_invoker_event_featureandcapif_provider_event_feature. The old names have been removed. - Invoker details file. The key
registered_security_contexesofcapif_api_security_context_details-<capif_username>.jsonis nowregistered_security_contexts. For invoker folders created with earlier versions, rundiscover()again beforeget_tokens(). - New mandatory invoker setting:
security_context.pref_security_context. It lists the security methods requested to CAPIF for every discovered API (OAUTH,PKIand/orPSK, in order of preference), and must contain at least one method, with no other values (case-insensitive); otherwise, creating aservice_discovererraises aValueError. Add it to theinvokersection of your configuration, or set theINVOKER_SECURITY_CONTEXT_PREF_SECURITY_CONTEXTenvironment variable. See Choosing the security methods. - Event subscription methods raise exceptions.
create_subscription(),delete_subscription(),update_subscription()andpatch_subscription(), in both event features, used to return(None, {'error': ...})when they failed. They now raise therequestsexception (e.g.HTTPError) if CAPIF rejects the request, or the newEventSubscriptionErrorif the subscription name is not found, CAPIF does not return the subscription ID, or the invoker has not been onboarded. - The invoker callback URL is sent as configured.
capif_callback_urlused to get a trailing/added in some requests (onboarding and event subscriptions) but not in others (security context). It is now always sent exactly as configured. capif_invoker_connector.check_authenticationrenamed tocheck_authentication_data. This attribute (theipandportused bycheck_authentication()) now has the same name incapif_invoker_connectorandservice_discoverer.check_authentication()uses HTTPS with server authentication only. It no longer sends the access token, and it returns the response of the AEF. It can now target the AEF of a discovered API withapi_name(andaef_id);check_authentication_datais only used whenapi_nameis not set.retrieve_specific_resource_name()returns the full URL of the resource (e.g.https://10.0.0.5:8443/resilience), built from the address published by the AEF, without calling CAPIF again. It acceptsaef_idandapi_version, and raisesApiInvocationErrorif the API or resource are not found.get_tokens()andget_access_token()only request a token for the APIs for which CAPIF selected OAUTH, and returnNoneif there are none. The expiration time of the token is stored inaccess_token_expires_at.
New features
- Choose the security methods for the invoker's APIs, with the
security_context.pref_security_contextsetting described above. Previously, the SDK always requested the methods announced by each AEF. get_security_context()now returns the security context returned by CAPIF; itssecurityInfoshows the security method selected for each API (selSecurityMethod). See Security Context.discover()now returns the APIs discovered in CAPIF (inserviceAPIDescriptions), orNoneif none were found.- New
enable_default_logging()function, explained in OpenCAPIF SDK logs. create_subscription()returns the CAPIF ID of the new subscription.EventSubscriptionErrorcan be imported fromopencapif_sdk.service_discovereris now a subclass ofcapif_invoker_connector, so it reads the invoker configuration in the same way and also offers its methods and attributes (e.g.capif_username).capif_invoker_usernameandca_root_pathare kept as aliases ofcapif_usernameandpathca.- Invoke the discovered APIs with
invoke_api()(orget_api_session()for a configuredrequestssession). The SDK uses the security method selected by CAPIF: for OAUTH it obtains, caches and renews an access token for that API (get_access_token_by_api_name()), for PKI it uses the invoker certificate, and for PSK it connects with TLS-PSK (see below). Requests always use HTTPS, verifying the AEF with the CAPIF CA root by default (api_invocation.ca_cert). Errors raiseApiInvocationError, which can be imported fromopencapif_sdk. - PSK security method (3GPP TS 33.122). If
PSKis inpref_security_context, the security context is created over TLS 1.2, and the SDK derives the pre-shared key (AEF_PSK) of each API at each AEF for which CAPIF selects PSK, in the same way as CAPIF.invoke_api()andget_api_session()then connect to the AEF with TLS-PSK, sending theapiInvokerIdas PSK identity (configurable withapi_invocation.psk_identityor theINVOKER_API_INVOCATION_PSK_IDENTITYenvironment variable). It requires Python 3.13 or later (the rest of the SDK keeps working with Python 3.9 or later) and OpenCAPIF 5.1.0 or later. See PSK security method.
Improvements and fixes
get_service()andget_all_services()now return the services retrieved from CAPIF (they are still saved toservice_received.json).- When a request fails, the original
requestsexception (e.g.Timeout,ConnectionError,HTTPError) is raised instead ofUnboundLocalError, and the logs include the HTTP status and body returned by CAPIF. - An empty
capif_https_portnow means port 443 in every operation. - The invoker details file (
capif_api_security_context_details-<capif_username>.json) is only readable by the user (permissions0600), as it contains the access tokens and, with PSK, the pre-shared keys. - The
PUBLISH_REQ_PUBLISHER_AEFS_IDSenvironment variable accepts a comma-separated list (aef1,aef2) or a JSON list (["aef1", "aef2"]). - Environment variables for configuration fields that hold lists or objects are now parsed instead of being used as plain text:
PROVIDER_EVENTS_DESCRIPTIONandINVOKER_EVENTS_DESCRIPTION(comma-separated or JSON list),PROVIDER_EVENTS_FILTERSandINVOKER_EVENTS_FILTERS(JSON list),WEB_SOCKET_NOTIF_CONFIGandPROVIDER_LOG(JSON object). An invalid value raises aValueErrorthat names the variable. api_schema_translator.build()uses port 443 forhttps://URLs without a port (it used 80).patch_subscription()no longer fails, and the provider'supdate_subscription()no longer removes the subscription from the local records, so it can still be updated or deleted afterwards.unpublish_service()andupdate_service()now remove the stored copy of the affected API (capif_<api_name>_<api_id>_api.json).create_logs()andcheck_invoker_authentication()no longer build URLs with a double/.capif_logging_featureraises a clear error when the API set inlog.apiNamehas not been published yet.- The warning about unverified HTTPS requests is only silenced for the initial request to the CAPIF register service, instead of for the whole application.
- An empty
capif_callback_urlno longer makescapif_invoker_connectorfail withIndexError. - The invoker folder can be set with the
INVOKER_FOLDERenvironment variable, like the other settings (the lowercaseinvoker_foldervariable is still accepted).
SDK repository: samples, scripts and configuration files
These changes affect the SDK repository, not the installed package:
- The Invoker Network App sample reads the Postman API key and environment ID from the
POSTMAN_API_KEYandPOSTMAN_ENVIRONMENT_IDenvironment variables, instead of having them written in the code. If they are not set, it skips the Postman update. - The Network App samples, the scripts and the testing clients call
enable_default_logging(), so they keep writing the SDK logs. - The scripts can be run from any directory, and write their logs to
scripts/logs/.register_and_login.pysaves theuuidof the created user incapif_sdk_register.json, soderegister_and_login.pycan delete it afterwards. - The sample configuration files include the mandatory
security_context.pref_security_contextsetting, and the environment variables sample includesINVOKER_SECURITY_CONTEXT_PREF_SECURITY_CONTEXTand can be loaded withsourcewithout errors. -
The Provider Network App sample serves its APIs over HTTPS (
https://localhost:8088andhttps://localhost:8888, the addresses it publishes), with a self-signed certificate forlocalhostthat it creates in itsaef_server_certificatefolder. The invoker sample trusts that certificate throughapi_invocation.ca_cert, so it can call the sample APIs withinvoke_api(). In addition, the provider sample:- Answers
check-authenticationwithout requiring an access token, as this operation uses HTTPS with server authentication only. - Serves the TSN configuration at
/apply, the path published in its API description, and a single TSN profile at/profile?name=<profileName>. - Exits with an error code, showing the error, if onboarding or publishing fails.
- Answers
-
The Postman collection of the invoker sample uses HTTPS and the
/applypath. - The sample configuration files use relative folders (
./test_provider_certificate_folderand./test_invoker_certificate_folder) instead of absolute paths, and git ignores the keys and certificates created by the samples. - The script
invoker_capif_event_subcription.pyis nowinvoker_capif_event_subscription.py, and the descriptions and comments of the scripts explain what each one does. - The unit tests cover the provider, invoker, event, logging and translator features, and run in the staging CI pipeline.
test/main.pyexits with an error code when it fails. See Unit tests. - The end-to-end test (
ci_cd_test/test_sdk.sh) publishes an API exposed by three AEFs, one per security method (OAUTH, PKI and PSK), runs those AEFs, and checks that the invoker can call the API at each one withinvoke_api().SDK_TEST_SECURITY_METHODSlimits the security methods checked (PSK requires OpenCAPIF 5.1.0 or later). See Testing the SDK. ci_cd_test/test_sdk.shexits with an error code (1) and shows the failed step when any step of the SDK tests fails; it used to exit with0in any case. The provider is always offboarded at the end, even after a failure. The staging CI pipeline runs it after deploying OpenCAPIF. See Testing the SDK.