diff --git a/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/common.tsp b/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/common.tsp index 41d86a629591..daf2d047610f 100644 --- a/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/common.tsp +++ b/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/common.tsp @@ -36,12 +36,10 @@ model NetworkIdentifier { @doc("The type of identifier for the network. one of: 'IPv4', 'IPv6', 'NetworkCode'") identifierType: string; - /** - The network identifier in a format matching the type above: - - IPv4 of a device in dotted-quad form 1.2.3.4. - - IPv6 of a device in IETF 5952 format. - - NetworkCode matching our documentation or an output from /Network:retrieve." - */ + @doc(""" + The network identifier, based on the identifierType: an IPv4 address, and IPv6 address, or a Network Code. + A Network Code may be obtained from APC documentation or from the APC /Network:retrieve endpoint. + """) identifier: string; } @@ -91,10 +89,7 @@ model Ipv6AddressModel { @doc("IPv4 device indicator") model Ipv4Address { - /** IPv4 address may be specified in form
as: - - address - an IPv4 number in dotted-quad form 1.2.3.4. Only this exact IP number will match the flow control rule. - - address/mask - an IP number as above with a mask width of the form 1.2.3.4/24. - In this case, all IP numbers from 1.2.3.0 to 1.2.3.255 will match. The bit width MUST be valid for the IP version. */ + @doc("An IPv4 address. This may be specified as an exact address, or as a subnet in CIDR notation.") ipv4: string; @doc("User equipment port.") @@ -103,13 +98,7 @@ model Ipv4Address { @doc("IPv6 device indicator") model Ipv6Address { - /** IPv6 address, following IETF 5952 format, may be specified in form
as: - - address - The /128 subnet is optional for single addresses: - - 2001:db8:85a3:8d3:1319:8a2e:370:7344 - - 2001:db8:85a3:8d3:1319:8a2e:370:7344/128 - - address/mask - an IP v6 number with a mask: - - 2001:db8:85a3:8d3::0/64 - - 2001:db8:85a3:8d3::/64 */ + @doc("An IPv6 address. This may be specified as an exact address, or as a subnet in CIDR notation.") ipv6: string; @doc("User equipment port.") diff --git a/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/location.tsp b/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/location.tsp index 7f87ab4b056b..2fe865cf1574 100644 --- a/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/location.tsp +++ b/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/location.tsp @@ -51,8 +51,8 @@ model DeviceLocationVerificationContent { @maxValue(100) accuracy: int32; - @doc("The device to find the location for.") - locationDevice: LocationDevice; + @doc("The device to find the location for. Exactly one of Network Access Code, Phone Number, IPv4 address, or IPv6 address") + device: LocationDevice; } /// Response models @@ -64,6 +64,10 @@ model DeviceLocationVerificationResult { } /// Common models + +// LocationDevice represents a Device as required by the Location API. The APC team aims +// to drive commonisation of the underlying CAMARA APIs so that all APIs can share a common Device +// model in future. @doc("Device information needed by operator to provide location information. Include exactly one of these properties to identify your device.") model LocationDevice { ...NetworkAccessIdentifierModel; diff --git a/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/number.tsp b/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/number.tsp index 677b36d910dc..beaae5fe49e7 100644 --- a/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/number.tsp +++ b/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/number.tsp @@ -13,26 +13,24 @@ namespace Azure.ProgrammableConnectivity; @doc(""" Number operations include Frontend Authentication. - Users must first make a call to triggerFrontendAuthentication, which redirects the device - to the device's Network to authenticate directly. The Network responds with a token. + Users first make a call to the endpoint /Number:verify, which returns a redirect to the device's + Network. This is followed by the device to authenticate directly with the Network. The Network + responds with a token and a redirect. This token can be exchanged with APC for a code. - This redirects the device to APC, where the token is used to verify / retrieve - the device number. The second response is a 200 containing the result of the query. + Users make a second call to the endpoint /Number:verify including the code. The code is used + to verify the device number. The second response is a 200 containing the result of the query. - This flow requires some manual interaction from the developer between receiving the 302 redirect, - and making a second call to obtain the number verification result. This has therefore been - split into two operations, one for the redirect, and one for the result. + For more information on the steps required to use Number Verificaiton, see the APC documentation. """) interface NumberVerification { + #suppress "@azure-tools/typespec-azure-core/no-response-body" "302 redirect has no response body" @doc("Verifies the phone number (MSISDN) associated with a device. As part of the frontend authorization flow, the device is redirected to the operator network to authenticate directly.") @sharedRoute @action("verify") verifyWithoutCode is Operations.ResourceAction< NumberVerificationEndpoint, NumberVerificationWithoutCodeContent, - // Typespec requires that non-204 responses have a non-empty body. This requirement cannot be suppressed. - // Return a model containing only one optional field to get around this. - TypeSpec.Http.Response<302> & EmptyResult, + TypeSpec.Http.Response<302> & {}, TraitOverride> @@ -82,12 +80,6 @@ model NumberVerificationWithCodeContent { /// Response models -@doc("Empty model to return as part of 302 redirect") -model EmptyResult { - @doc("Optional content") - content?: string; -} - @doc("Response verifying number of device") model NumberVerificationResult { @doc("True if number if the phone number matches the device, False otherwise") @@ -95,6 +87,10 @@ model NumberVerificationResult { } /// Common models + +// NumberDevice represents a Device as required by the Number Verification API. The APC team aims +// to drive commonisation of the underlying CAMARA APIs so that all APIs can share a common Device +// model in future. @doc("Device information to verify phone number. Include exactly one form of phone number.") model NumberDevice { ...PhoneNumberModel; diff --git a/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/simswap.tsp b/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/simswap.tsp index d412a97b2afc..d004d29d282a 100644 --- a/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/simswap.tsp +++ b/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/simswap.tsp @@ -76,6 +76,9 @@ model SimSwapVerificationResult { /// Common models +// SimSwapDevice represents a Device as required by the Sim Swap API. The APC team aims +// to drive commonisation of the underlying CAMARA APIs so that all APIs can share a common Device +// model in future. @doc("Device information needed by operator to find sim swap information.") model SimSwapDevice { ...PhoneNumberModel; diff --git a/specification/programmableconnectivity/Azure.ProgrammableConnectivity/examples/2024-02-09-preview/DeviceLocation_Verify_MaximumSet_Gen.json b/specification/programmableconnectivity/Azure.ProgrammableConnectivity/examples/2024-02-09-preview/DeviceLocation_Verify_MaximumSet_Gen.json index f1e2075d814c..5ca27769ff7b 100644 --- a/specification/programmableconnectivity/Azure.ProgrammableConnectivity/examples/2024-02-09-preview/DeviceLocation_Verify_MaximumSet_Gen.json +++ b/specification/programmableconnectivity/Azure.ProgrammableConnectivity/examples/2024-02-09-preview/DeviceLocation_Verify_MaximumSet_Gen.json @@ -14,7 +14,7 @@ "latitude": 70, "longitude": -161, "accuracy": 91, - "locationDevice": { + "device": { "networkAccessIdentifier": "122345@domain.com", "phoneNumber": "+447000000000", "ipv4Address": { diff --git a/specification/programmableconnectivity/Azure.ProgrammableConnectivity/examples/2024-02-09-preview/NumberVerification_VerifyWithoutCode_MaximumSet_Gen.json b/specification/programmableconnectivity/Azure.ProgrammableConnectivity/examples/2024-02-09-preview/NumberVerification_VerifyWithoutCode_MaximumSet_Gen.json index e938f4e89d11..9a2f68a4e168 100644 --- a/specification/programmableconnectivity/Azure.ProgrammableConnectivity/examples/2024-02-09-preview/NumberVerification_VerifyWithoutCode_MaximumSet_Gen.json +++ b/specification/programmableconnectivity/Azure.ProgrammableConnectivity/examples/2024-02-09-preview/NumberVerification_VerifyWithoutCode_MaximumSet_Gen.json @@ -15,8 +15,6 @@ } }, "responses": { - "302": { - "body": {} - } + "302": {} } } diff --git a/specification/programmableconnectivity/data-plane/Azure.ProgrammableConnectivity/preview/2024-02-09-preview/examples/DeviceLocation_Verify_MaximumSet_Gen.json b/specification/programmableconnectivity/data-plane/Azure.ProgrammableConnectivity/preview/2024-02-09-preview/examples/DeviceLocation_Verify_MaximumSet_Gen.json index f1e2075d814c..5ca27769ff7b 100644 --- a/specification/programmableconnectivity/data-plane/Azure.ProgrammableConnectivity/preview/2024-02-09-preview/examples/DeviceLocation_Verify_MaximumSet_Gen.json +++ b/specification/programmableconnectivity/data-plane/Azure.ProgrammableConnectivity/preview/2024-02-09-preview/examples/DeviceLocation_Verify_MaximumSet_Gen.json @@ -14,7 +14,7 @@ "latitude": 70, "longitude": -161, "accuracy": 91, - "locationDevice": { + "device": { "networkAccessIdentifier": "122345@domain.com", "phoneNumber": "+447000000000", "ipv4Address": { diff --git a/specification/programmableconnectivity/data-plane/Azure.ProgrammableConnectivity/preview/2024-02-09-preview/examples/NumberVerification_VerifyWithoutCode_MaximumSet_Gen.json b/specification/programmableconnectivity/data-plane/Azure.ProgrammableConnectivity/preview/2024-02-09-preview/examples/NumberVerification_VerifyWithoutCode_MaximumSet_Gen.json index e938f4e89d11..9a2f68a4e168 100644 --- a/specification/programmableconnectivity/data-plane/Azure.ProgrammableConnectivity/preview/2024-02-09-preview/examples/NumberVerification_VerifyWithoutCode_MaximumSet_Gen.json +++ b/specification/programmableconnectivity/data-plane/Azure.ProgrammableConnectivity/preview/2024-02-09-preview/examples/NumberVerification_VerifyWithoutCode_MaximumSet_Gen.json @@ -15,8 +15,6 @@ } }, "responses": { - "302": { - "body": {} - } + "302": {} } } diff --git a/specification/programmableconnectivity/data-plane/Azure.ProgrammableConnectivity/preview/2024-02-09-preview/openapi.json b/specification/programmableconnectivity/data-plane/Azure.ProgrammableConnectivity/preview/2024-02-09-preview/openapi.json index 35daa1b69d3f..ee1a3814550f 100644 --- a/specification/programmableconnectivity/data-plane/Azure.ProgrammableConnectivity/preview/2024-02-09-preview/openapi.json +++ b/specification/programmableconnectivity/data-plane/Azure.ProgrammableConnectivity/preview/2024-02-09-preview/openapi.json @@ -201,9 +201,6 @@ "responses": { "302": { "description": "Redirection", - "schema": { - "$ref": "#/definitions/EmptyResult" - }, "headers": { "location": { "type": "string" @@ -610,9 +607,9 @@ "minimum": 2, "maximum": 100 }, - "locationDevice": { + "device": { "$ref": "#/definitions/LocationDevice", - "description": "The device to find the location for." + "description": "The device to find the location for. Exactly one of Network Access Code, Phone Number, IPv4 address, or IPv6 address" } }, "required": [ @@ -620,7 +617,7 @@ "latitude", "longitude", "accuracy", - "locationDevice" + "device" ] }, "DeviceLocationVerificationResult": { @@ -656,23 +653,13 @@ "network" ] }, - "EmptyResult": { - "type": "object", - "description": "Empty model to return as part of 302 redirect", - "properties": { - "content": { - "type": "string", - "description": "Optional content" - } - } - }, "Ipv4Address": { "type": "object", "description": "IPv4 device indicator", "properties": { "ipv4": { "type": "string", - "description": "IPv4 address may be specified in form
as:\n - address - an IPv4 number in dotted-quad form 1.2.3.4. Only this exact IP number will match the flow control rule.\n - address/mask - an IP number as above with a mask width of the form 1.2.3.4/24.\n In this case, all IP numbers from 1.2.3.0 to 1.2.3.255 will match. The bit width MUST be valid for the IP version." + "description": "An IPv4 address. This may be specified as an exact address, or as a subnet in CIDR notation." }, "port": { "type": "integer", @@ -701,7 +688,7 @@ "properties": { "ipv6": { "type": "string", - "description": "IPv6 address, following IETF 5952 format, may be specified in form
as:\n - address - The /128 subnet is optional for single addresses:\n - 2001:db8:85a3:8d3:1319:8a2e:370:7344\n - 2001:db8:85a3:8d3:1319:8a2e:370:7344/128\n - address/mask - an IP v6 number with a mask:\n - 2001:db8:85a3:8d3::0/64\n - 2001:db8:85a3:8d3::/64" + "description": "An IPv6 address. This may be specified as an exact address, or as a subnet in CIDR notation." }, "port": { "type": "integer", @@ -767,7 +754,7 @@ }, "identifier": { "type": "string", - "description": "The network identifier in a format matching the type above:\n - IPv4 of a device in dotted-quad form 1.2.3.4.\n - IPv6 of a device in IETF 5952 format.\n - NetworkCode matching our documentation or an output from /Network:retrieve.\"" + "description": "The network identifier, based on the identifierType: an IPv4 address, and IPv6 address, or a Network Code.\nA Network Code may be obtained from APC documentation or from the APC /Network:retrieve endpoint." } }, "required": [ diff --git a/specification/programmableconnectivity/data-plane/readme.md b/specification/programmableconnectivity/data-plane/readme.md index f959c88a23b6..9afcd7bc956b 100644 --- a/specification/programmableconnectivity/data-plane/readme.md +++ b/specification/programmableconnectivity/data-plane/readme.md @@ -39,7 +39,8 @@ input-file: - Azure.ProgrammableConnectivity/preview/2024-02-09-preview/openapi.json suppressions: - code: ValidResponseCodeRequired - reason: APC must return a 302 as part of a non-standard + reason: APC must return a 302 as part of a non-standard frontend authentication flow + where: $.paths./number-verification/number:verify.post.responses ``` # Code Generation