Skip to content

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, and debug_mode no longer enables the urllib3 (HTTP) debug logs. To keep getting the SDK logs, call enable_default_logging(), as explained in OpenCAPIF SDK logs.
  • Fewer dependencies. pip install opencapif_sdk now installs only what the SDK uses, and PyJWT is 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 use pip install "opencapif_sdk[samples]" for the Flask-based samples.
  • pyOpenSSL replaced by cryptography. Keys and certificate signing requests (CSRs) are now created with cryptography 50.x, the same version used by the OpenCAPIF services, and pyOpenSSL is 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 imports OpenSSL, install pyOpenSSL yourself.
  • Event subscription methods renamed. update_subcription() and patch_subcription() are now update_subscription() and patch_subscription(), in both capif_invoker_event_feature and capif_provider_event_feature. The old names have been removed.
  • Invoker details file. The key registered_security_contexes of capif_api_security_context_details-<capif_username>.json is now registered_security_contexts. For invoker folders created with earlier versions, run discover() again before get_tokens().
  • New mandatory invoker setting: security_context.pref_security_context. It lists the security methods requested to CAPIF for every discovered API (OAUTH, PKI and/or PSK, in order of preference), and must contain at least one method, with no other values (case-insensitive); otherwise, creating a service_discoverer raises a ValueError. Add it to the invoker section of your configuration, or set the INVOKER_SECURITY_CONTEXT_PREF_SECURITY_CONTEXT environment variable. See Choosing the security methods.
  • Event subscription methods raise exceptions. create_subscription(), delete_subscription(), update_subscription() and patch_subscription(), in both event features, used to return (None, {'error': ...}) when they failed. They now raise the requests exception (e.g. HTTPError) if CAPIF rejects the request, or the new EventSubscriptionError if 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_url used 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_authentication renamed to check_authentication_data. This attribute (the ip and port used by check_authentication()) now has the same name in capif_invoker_connector and service_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 with api_name (and aef_id); check_authentication_data is only used when api_name is 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 accepts aef_id and api_version, and raises ApiInvocationError if the API or resource are not found.
  • get_tokens() and get_access_token() only request a token for the APIs for which CAPIF selected OAUTH, and return None if there are none. The expiration time of the token is stored in access_token_expires_at.

New features

  • Choose the security methods for the invoker's APIs, with the security_context.pref_security_context setting described above. Previously, the SDK always requested the methods announced by each AEF.
  • get_security_context() now returns the security context returned by CAPIF; its securityInfo shows the security method selected for each API (selSecurityMethod). See Security Context.
  • discover() now returns the APIs discovered in CAPIF (in serviceAPIDescriptions), or None if none were found.
  • New enable_default_logging() function, explained in OpenCAPIF SDK logs.
  • create_subscription() returns the CAPIF ID of the new subscription. EventSubscriptionError can be imported from opencapif_sdk.
  • service_discoverer is now a subclass of capif_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_username and ca_root_path are kept as aliases of capif_username and pathca.
  • Invoke the discovered APIs with invoke_api() (or get_api_session() for a configured requests session). 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 raise ApiInvocationError, which can be imported from opencapif_sdk.
  • PSK security method (3GPP TS 33.122). If PSK is in pref_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() and get_api_session() then connect to the AEF with TLS-PSK, sending the apiInvokerId as PSK identity (configurable with api_invocation.psk_identity or the INVOKER_API_INVOCATION_PSK_IDENTITY environment 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() and get_all_services() now return the services retrieved from CAPIF (they are still saved to service_received.json).
  • When a request fails, the original requests exception (e.g. Timeout, ConnectionError, HTTPError) is raised instead of UnboundLocalError, and the logs include the HTTP status and body returned by CAPIF.
  • An empty capif_https_port now means port 443 in every operation.
  • The invoker details file (capif_api_security_context_details-<capif_username>.json) is only readable by the user (permissions 0600), as it contains the access tokens and, with PSK, the pre-shared keys.
  • The PUBLISH_REQ_PUBLISHER_AEFS_IDS environment 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_DESCRIPTION and INVOKER_EVENTS_DESCRIPTION (comma-separated or JSON list), PROVIDER_EVENTS_FILTERS and INVOKER_EVENTS_FILTERS (JSON list), WEB_SOCKET_NOTIF_CONFIG and PROVIDER_LOG (JSON object). An invalid value raises a ValueError that names the variable.
  • api_schema_translator.build() uses port 443 for https:// URLs without a port (it used 80).
  • patch_subscription() no longer fails, and the provider's update_subscription() no longer removes the subscription from the local records, so it can still be updated or deleted afterwards.
  • unpublish_service() and update_service() now remove the stored copy of the affected API (capif_<api_name>_<api_id>_api.json).
  • create_logs() and check_invoker_authentication() no longer build URLs with a double /.
  • capif_logging_feature raises a clear error when the API set in log.apiName has 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_url no longer makes capif_invoker_connector fail with IndexError.
  • The invoker folder can be set with the INVOKER_FOLDER environment variable, like the other settings (the lowercase invoker_folder variable 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_KEY and POSTMAN_ENVIRONMENT_ID environment 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.py saves the uuid of the created user in capif_sdk_register.json, so deregister_and_login.py can delete it afterwards.
  • The sample configuration files include the mandatory security_context.pref_security_context setting, and the environment variables sample includes INVOKER_SECURITY_CONTEXT_PREF_SECURITY_CONTEXT and can be loaded with source without errors.
  • The Provider Network App sample serves its APIs over HTTPS (https://localhost:8088 and https://localhost:8888, the addresses it publishes), with a self-signed certificate for localhost that it creates in its aef_server_certificate folder. The invoker sample trusts that certificate through api_invocation.ca_cert, so it can call the sample APIs with invoke_api(). In addition, the provider sample:

    • Answers check-authentication without 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.
  • The Postman collection of the invoker sample uses HTTPS and the /apply path.

  • The sample configuration files use relative folders (./test_provider_certificate_folder and ./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.py is now invoker_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.py exits 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 with invoke_api(). SDK_TEST_SECURITY_METHODS limits the security methods checked (PSK requires OpenCAPIF 5.1.0 or later). See Testing the SDK.
  • ci_cd_test/test_sdk.sh exits with an error code (1) and shows the failed step when any step of the SDK tests fails; it used to exit with 0 in 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.