Resolve TODOs

Azure · Dec 12, 2023 · 1a151f4 · 1a151f4
1 parent 1f3887a
commit 1a151f4
Show file tree

Hide file tree

Showing 25 changed files with 657 additions and 607 deletions.
diff --git a/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/common.tsp b/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/common.tsp
@@ -16,28 +16,48 @@ alias ServiceTraits = NoRepeatableRequests &
   SupportsClientRequestId &
   RequestHeadersTrait<ApcGatewayIdHeader>;
 
-alias Operations = Azure.Core.ResourceOperations<ServiceTraits>;
-
-// TODO - This Enum only exists to stop linting yelling at us. Can we do this better?
-@doc("Enum to provide static action endpoint")
-enum CommonActionEnum {
-  @doc("Static endpoint")
-  action: "action",
-}
-
-@doc("Resource representing an Operator Network")
-@resource("network")
-model Network {
-  @key
-  @pattern("[a-z0-9-]+$")
-  @doc("The ID of the network")
-  @visibility("read")
-  networkId: string;
-}
+alias Operations = Azure.Core.ResourceOperations<ServiceTraits, ApcErrorResponse>;
 
 @doc("Header to identify APC Gateway resource.")
 model ApcGatewayIdHeader {
   @doc("The identifier of the APC Gateway resource which should handle this request.")
   @header("apc-gateway-id")
   apcGatewayId: string;
 }
+
+@doc("Identifier for the network to be queried")
+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."
+  */
+  identifier: string;
+}
+
+  @doc("The phone number of the device to be identified.")
+  model PhoneNumberModel
+  {
+    @doc("Phone number in E.164 format (starting with country code), and optionally prefixed with '+'")
+    @pattern("^\\+?[0-9]{5,15}$")
+    phoneNumber?: string;
+  }
+
+@error
+@doc("A custom error type for APC.")
+model ApcErrorResponse {
+  @doc("The numeric error code.")
+  status: int32;
+
+  @doc("The error code")
+  code: string;
+
+  @doc("The detailed error message.")
+  errorMessage: string;
+
+  @doc("The consent URL in case of a consent failure")
+  consentUrl?: url;
+}
diff --git a/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/location.tsp b/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/location.tsp
@@ -10,6 +10,7 @@ namespace Azure.ProgrammableConnectivity;
 /// Interfaces
 
 interface LocationInterface {
+  @doc("Verifies whether a device is within a specified location area, defined as an accuracy (radius) around a point, specified by longitude and latitude.")
   verify is Operations.ResourceAction<
     LocationEndpoint,
     LocationVerifyRequest,
@@ -25,15 +26,15 @@ model LocationEndpoint {
   @key("action")
   @doc("Static endpoint")
   @visibility("read")
-  action: CommonActionEnum;
+  action: "";
 }
 
 /// Request models
 
 @doc("Request to verify Location")
 model LocationVerifyRequest {
-  @doc("Network to query for this device")
-  network: Network;
+    @doc("Network to query for this device, or device information to enable network routing.")
+  networkIdentifier: NetworkIdentifier;
 
   @doc("Latitude of location to be verified")
   @minValue(-90)
@@ -50,7 +51,8 @@ model LocationVerifyRequest {
   @maxValue(100)
   accuracy: int32;
 
-  ...LocationDevice;
+  @doc("The device to find the location for.")
+  locationDevice: LocationDevice
 }
 
 /// Response models
@@ -62,23 +64,43 @@ model LocationVerifyResponse {
 }
 
 /// Common models
-
-// TODO - implement maxProperties = 1 and minProperties = 1
-@doc("Device information needed by CAMARA Location API")
+@doc("Device information needed by operator to provide location information. Include exactly one of these properties to identify your device.")
 model LocationDevice {
   @doc("External identifier or network access identifier of the device")
   networkAccessIdentifier?: string;
+
+  ...PhoneNumberModel;
+
+  @doc ("IPv4 address and port of the device")
+  ipv4Address?: Ipv4Address;
 
-  // TODO - is there a good way to commonise the phone number definition and still capture that it's sometimes required and sometimes optional?
-  @doc("Phone number in E.164 format (starting with country code), and optionally prefixed with '+'")
-  @pattern("^\\+?[0-9]{5,15}$")
-  phoneNumber?: string;
+  @doc ("IPv6 address and port of the device")
+  ipv6Address?: Ipv6Address;
+}
 
-  @doc("IPv4 address and port of the device, in the form address:port")
-  @pattern("^([01]?\\d\\d?|2[0-4]\\d|25[0-5])(?:\\.(?:[01]?\\d\\d?|2[0-4]\\d|25[0-5])){3}(:\\d{1,4})?$")
-  ipv4Address?: string;
+@doc ("IPv4 device indicator")
+model Ipv4Address {
+  /** IPv4 address may be specified in form <address/mask> 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. */
+  ipv4: string;
+
+  @doc ("User equipment port.")
+  port: int32;
+}
 
-  @doc("IPv6 address of the device")
-  @pattern("^((([^:]+:){7}([^:]+))|((([^:]+:)*[^:]+)?::(([^:]+:)*[^:]+)?))(\\/.+)?$")
-  ipv6Address?: string;
+@doc ("IPv6 device indicator")
+model Ipv6Address {
+  /** IPv6 address, following IETF 5952 format, may be specified in form <address/mask> 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 */
+  ipv6: string;
+
+  @doc ("User equipment port.")
+  port: int32;
 }
diff --git a/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/network.tsp b/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/network.tsp
@@ -11,12 +11,10 @@ namespace Azure.ProgrammableConnectivity;
 /// Interfaces
 
 interface Networks {
-  // TODO - do we need this?
-  list is Operations.ResourceList<Network>;
-
+  @doc("Retrieves the network a given device is on. Returns network in a networkCode format that can be used for other APIs.")
   retrieve is Operations.ResourceAction<
     NetworkRetrieveEndpoint,
-    NetworkDevice,
+    DeviceNetworkIdentifier,
     Network
   >;
 }
@@ -29,15 +27,23 @@ model NetworkRetrieveEndpoint {
   @key("action")
   @doc("Static endpoint")
   @visibility("read")
-  action: CommonActionEnum;
+  action: "";
 }
 
 /// Common models
-
-@doc("Represents a Device whose Network is searched for")
-model NetworkDevice {
-  // TODO - is there a good way to commonise the phone number definition and still capture that it's sometimes required and sometimes optional?
-  @doc("Phone number in E.164 format (starting with country code), and optionally prefixed with '+'")
-  @pattern("^\\+?[0-9]{5,15}$")
-  phoneNumber: string;
+@doc("The device for which to find the network.")
+model DeviceNetworkIdentifier {
+  @doc("The type of device identifier given: 'IPv4' or 'IPv6'.")
+  identifierType: string;
+  /** The device identifier in a format matching the type above:
+  - IPv4 in dotted-quad format.
+  - IPV6 in IETF 5952 format.*/
+  deviceIdentifier: string;
 }
+
+@doc("The network that the device is on.")
+model Network {
+  @pattern("[a-z0-9-]+$")
+  @doc("The identifier for the network. This can be used as the networkIdentifier for the service APIs.")
+  networkCode: string;
+}
diff --git a/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/number.tsp b/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/number.tsp
@@ -23,16 +23,18 @@ namespace Azure.ProgrammableConnectivity;
   of the entire flow (the 200 response) is included in this document.
 """)
 interface NumberInterface {
+
+  @doc("Verifies the phone number (MSISDN) associated with a device.")
   verify is Operations.ResourceAction<
     NumberEndpoint,
     NumberVerifyRequest,
     NumberVerifyResponse
   >;
 
-  // TODO - GET or POST?
+  @doc("Retrieves the phone number (MSISDN) associated with a device.")
   retrieve is Operations.ResourceAction<
     NumberEndpoint,
-    {},
+    NetworkIdentifier,
     NumberRetrieveResponse
   >;
 }
@@ -45,15 +47,15 @@ model NumberEndpoint {
   @key("action")
   @doc("Static endpoint")
   @visibility("read")
-  action: CommonActionEnum;
+  action: "";
 }
 
 /// Request models
 
 @doc("Request to verify number of device")
 model NumberVerifyRequest {
-  @doc("Network to query for this device")
-  network: Network;
+  @doc("Identifier for the network to query for this device.")
+  networkIdentifier: NetworkIdentifier;
 
   ...NumberDevice;
 }
@@ -68,21 +70,15 @@ model NumberVerifyResponse {
 
 @doc("Response with number of device")
 model NumberRetrieveResponse {
-  // TODO - is there a good way to commonise the phone number definition and still capture that it's sometimes required and sometimes optional?
   @doc("Phone number in E.164 format (starting with country code), and optionally prefixed with '+'")
   @pattern("^\\+?[0-9]{5,15}$")
   phoneNumber: string;
 }
 
 /// Common models
-
-// TODO - implement maxProperties = 1 and minProperties = 1
-@doc("Device information needed by CAMARA Number API")
+@doc("Device information to verify phone number. Include exactly one form of phone number.")
 model NumberDevice {
-  // TODO - is there a good way to commonise the phone number definition and still capture that it's sometimes required and sometimes optional?
-  @doc("Phone number in E.164 format (starting with country code), and optionally prefixed with '+'")
-  @pattern("^\\+?[0-9]{5,15}$")
-  phoneNumber?: string;
+  ...PhoneNumberModel;
 
   @doc("Hashed phone number. SHA-256 (in hexadecimal representation) of the mobile phone number in **E.164 format (starting with country code)**. Optionally prefixed with '+'.")
   hashedPhoneNumber?: string;

diff --git a/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/simswap.tsp b/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/simswap.tsp
@@ -9,14 +9,16 @@ using Azure.Core.Traits;
 namespace Azure.ProgrammableConnectivity;
 
 /// Interfaces
-
+@doc("SIM Swap API provides the customer the ability to obtain information on any recent SIM pairing change related to the User's mobile account.")
 interface SimSwapInterface {
+  @doc("Provides timestamp of latest SIM swap")
   retrieve is Operations.ResourceAction<
     SimSwapEndpoint,
     SimSwapRetrieveRequest,
     SimSwapRetrieveResponse
   >;
 
+  @doc("Verifies if a SIM swap has been performed during a past period (defined in the request with 'maxAgeHours' attribute). Returns 'True' if a SIM swap has occured.")
   verify is Operations.ResourceAction<
     SimSwapEndpoint,
     SimSwapVerifyRequest,
@@ -32,28 +34,28 @@ model SimSwapEndpoint {
   @key("action")
   @doc("Static endpoint")
   @visibility("read")
-  action: CommonActionEnum;
+  action: "";
 }
 
 /// Request models
 
 @doc("Request to retrieve SimSwap date")
 model SimSwapRetrieveRequest {
-  @doc("Network to query for this device")
-  network: Network;
-
   ...SimSwapDevice;
+
+  @doc("Network to query for this device")
+  networkIdentifier: NetworkIdentifier;
 }
 
 @doc("Request to verify SimSwap in period")
 model SimSwapVerifyRequest {
   @doc("Maximum lookback for SimSwap verification")
-  maxAge?: int32;
+  @minValue(1)
+  @maxValue(2400)
+  maxAgeHours?: int32 = 240;
 
-  @doc("Network to query for this device")
-  network: Network;
-
-  ...SimSwapDevice;
+  @doc("Identifier for the network to query for this device.")
+  networkIdentifier: NetworkIdentifier;
 }
 
 /// Response Models
@@ -72,10 +74,10 @@ model SimSwapVerifyResponse {
 
 /// Common models
 
-@doc("Device information needed by CAMARA SimSwap API")
+@doc("Device information needed by operator to find sim swap information.")
 model SimSwapDevice {
-  // TODO - is there a good way to commonise the phone number definition and still capture that it's sometimes required and sometimes optional?
   @doc("Phone number in E.164 format (starting with country code), and optionally prefixed with '+'")
   @pattern("^\\+?[0-9]{5,15}$")
   phoneNumber: string;
 }
+