Subject: Re: [drinks] Following today's meeting

From: "Cartwright, Ken" <[email-masked]>
Date: Thu, 9 May 2013 08:56:49 -0400

Hi,

Thanks for these thoughts.  Very insightful.  My $.02 is as follows (sorry for any grammar/typos, putting this response together in a rush):

"During the call, we agreed that the cardinality on the DG side of the PubId-DG association should be 0..1 instead of 0...n."

KJC:  I'd state it like this...The cardinality in the body of the framework document and in the XSD are already correct/whatWeIntended, 0..1.  But the diagram in the intro of the framework document incorrectly illustrates 0..n because it was a carry-over from the requirements document diagram, which was more notional (and was referring to the requirement that a given TN/TNRange/etc can be in one or more DGs, or not in a DG).  So we decided on the recent call that it would be best to change the diagram in the framework document to represent the implementation construct in the XSD that uses a PIType, rather than the notional concepts in the requirements document.  The operative point being that we are not really "changing" a cardinality, but are making a clerical correction to a diagram, albeit a good correction.  Good catch.

---

"For example, an obvious URI for a TN resource would represent the key attributes as path parameters such as /rant/{rant}/TN/dgName/{dgName}/tn/{tn}. However, dgName is optional and may not have a value. We can solve this problem by using a special string to represent the absence of a value, or by using other types of URI parameters (e.g. query parameters), but I don't think it's the right way to go."

KJC:  Hierarchical relationships in REST URIs are "optional".  If the hierarchical relationship exists then it is in the URI, if it does not exist, then it is not in the URI.  So a reasonable approach to resolving your Rest URI question is to not implement the TNs/PIs->DG relationship as a mandatory hierarchy where the DG "contains" the TNs/PIs.  This can be accomplished in at least a couple ways as follows...

1)      Consider modeling the URI in a way that is analogous to the SOAP XSD;s approach, with an attribute of the TN/PI containing the DG relationship.    If you do that, then instead of having this: /rant/{rant}/TN/DGNAME/{dgName}/TN/{tn}
You'd have this:
/rant/{rant}/TN/{tn}/DG/{dgName}
Examples:
/rant/SomeCompany/TN/17039876543
/rant/SomeCompany/TN/13013456789/DG/NorthEast
In this approach your quandary goes away.  If there is no DG relationship, then that portion of the URI is just not necessary and is therefore not there.  Note that this is basically how the SOAP XSD design does it.

2)      You could alternatively do it like this:
/rant/{rant}/DG/{dgName}/TN/{tn}
Examples:
/rant/SomeCompany/DG/NorthEast/TN/17039876543
/rant/SomeCompany/TN/13019876543

Some TNs are "in" DGs and some are not.  There should be no issue with that approach either.

Imo, also adding in the concept of the PI to the URL may be a valid addition to the URIs, since they are all just types of PIs
/rant/{rant}/PI/{PIString}/DG/{dgName}
Examples:
/rant/SomeCompany/PI/Prefix/17039
/rant/SomeCompany/PI/TN/13019876543/DG/NorthEast
/rant/SomeCompany/PI/Range/13010000000-13019999999/DG/NorthEast
/rant/SomeCompany/PI/LRN/19059876543/DG/SouthEast

---

I also noticed that the text in section 3.1, bullet two, about Destination groups says "can be

      associated with one or more SED Groups".  That should say "can be associated with zero or more SED Groups"

---

"the corInfo element should be an attribute of the PI-DG association since it is not intrisic to the PI itself"

KJC:  I believe that the COR claim is intrinsic to the PI.  And putting it on an association between the PI and the DG would add further complexity to the XSD and the model.

In general, I think making this change would reduce the flexibility that is in the current model, while not reducing the complexity.

Thanks

From: [email-masked] [mailto:[email-masked]] On Behalf Of Mickael Marrache
Sent: Wednesday, April 24, 2013 2:51 PM
To: [email-masked]
Subject: [drinks] Following today's meeting

Hi,

During the call, we agreed that the cardinality on the DG side of the PubId-DG association should be 0..1 instead of 0...n. We also agreed that this cardinality should not be interpreted as limiting a PI to be associated to at most one DG. However, this cardinality should be interpreted as limiting a PI instance to be associated to at most one DG. Thus, for example, the "same" telephone number may be associated to multiple DGs by the use of multiple TN instances. This way is made possible by including the dgName element as part of the key, so that for a given registrant and a given value (e.g. tn, tnp, start/end...), different values for the dgName element are allowed.

I think that the dgName element should not be part of the key because it is optional. While it may be acceptable for a key attribute to be optional in some cases, I think it's relatively rare. Also, it becomes more difficult to define a URI for each public identifier concrete type. For example, an obvious URI for a TN resource would represent the key attributes as path parameters such as /rant/{rant}/TN/dgName/{dgName}/tn/{tn}. However, dgName is optional and may not have a value. We can solve this problem by using a special string to represent the absence of a value, or by using other types of URI parameters (e.g. query parameters), but I don't think it's the right way to go.

What I proposed during the call was to exclude the dgName element from the key. So, there would be only one PI instance for a particular value, that is identified by the registrant that owns the PI, and the value of the PI (e.g. tn, tnp...). In order to allow a PI to be associated to multiple DGs, the maxOccurs attribute of the dgName element should be set to unbounded. The registrant organization would only deal with one instance for a given PI value. The URI for the TN resource would then be /rant/{rant}/TN/{tn}.

Concerning the carrier-of-record concern, the question is: Is there a meaning to let a registrant organization provision the same PI (in terms of value) with different COR information? The current model allows such a feature by the use of multiple PI instances (thus, allowing multiple corInfos). If this is a real use case, the corInfo element should be an attribute of the PI-DG association since it is not intrisic to the PI itself but depends on an external factor (in this case, the association with a particular DG). Creating a new complex type DestGrpRefType that includes the DG key and the corInfo element would solve this issue. The list of dgName (ObjNameType) would become a list of dgRefs (DestGrpRefType).

Not related to this question, there are two other points I raised in the mailing list:

 1.  The framework document states: "If the response to the Get operation includes object(s) that extend the BasicObjType, the Registry MUST include the 'cDate' and 'mDate', if applicable.". In the examples section in the SOAP document (section 10), for the Get examples, the elements cDate and mDate are not part of the returned responses.
 2.  According to the framework document, an egress route is added by the originating SSP to the registry. The originating SSP must be a peering organization of the SED group to which the egress route is associated. Thus, an egress route is an element owned by the originating SSP. The rant field of the egress route would then identify the originating SSP and not the owner of the SED group. Also, in the SOAP document in section 10.17, the rant field has the value iana-en:111 as expected. There is an error in the SOAP document in section 10.11. The rant field has the value iana-en:222 where it should have the value iana-en:111 that identifies SSP1.

Also, a new version of the REST draft is available at http://tools.ietf.org/html/draft-marrache-drinks-spp-protocol-rest-02. It would be great if you can take a look at it and comment.

Thanks,
Mickael

________________________________
This e-mail message is for the sole use of the intended recipient(s)and may
contain confidential and privileged information of Transaction Network Services.
Any unauthorised review, use, disclosure or distribution is prohibited. If you
are not the intended recipient, please contact the sender by reply e-mail and destroy all copies of the original message.

---

From: Mickael Marrache <[email-masked]>
Date: Thu, 9 May 2013 17:14:28 +0300

Hi,

Concerning the first point, this is what I meant. I just explained the
current approach as a prerequisite for the next part.

Concerning the second point, I think you don't answer the real question.

Firstly, using optional path parameters introduces an implementation issue.
Also, JAX-RS, which will probably be the most used solution for
implementing SPPP over REST in Java, does not support easily optional
parameters (see
http://www.nakov.com/blog/2009/07/15/jax-rs-path-pathparam-and-optional-parameters/).
There are workarounds to this "issue" but this lack of support shows this
is a rare way of defining URIs in REST. Optional path parameters are
generally discouraged in REST.

I think the real question is why to include the name of the destination
group as part of the PI key, not how to represent optional path parameters
in REST. Also, I don't see how excluding the dgName from the PI key would
reduce flexibility of the model. On the other hand, I think that including
the dgName as part of the PI key increases complexity of RESTful
implementations for the reasons I mentioned in the previous paragraph.
Also, I think that defining two URI templates for PIs (one for PIs that are
part of DGs and another for PIs that are not part of DGs) makes the REST
API less intuitive for the clients, and adds complexity for implementors. I
don't really see enough advantages with the current model, that would
convince me to accept this implementation complexity.

Concerning the COR aspect, it's only a question we raised during the last
meeting. I agree that the COR is intrinsic to the PI, so we don't need to
move it at the PI-DG association level.

Thanks,
Mickael

On Thu, May 9, 2013 at 3:56 PM, Cartwright, Ken <[email-masked]>wrote:

>  Hi,****
>
>
> Thanks for these thoughts.  Very insightful.  My $.02 is as follows (sorry
> for any grammar/typos, putting this response together in a rush):****
>
> ** **
>
> “During the call, we agreed that the cardinality on the DG side of the
> PubId-DG association should be 0..1 instead of 0...n.”****
>
> ** **
>
> KJC:  I’d state it like this…The cardinality in the body of the framework
> document and in the XSD are already correct/whatWeIntended, 0..1.  But the
> diagram in the intro of the framework document incorrectly illustrates 0..n
> because it was a carry-over from the requirements document diagram, which
> was more notional (and was referring to the requirement that a given
> TN/TNRange/etc can be in one or more DGs, or not in a DG).  So we decided
> on the recent call that it would be best to change the diagram in the
> framework document to represent the implementation construct in the XSD
> that uses a PIType, rather than the notional concepts in the requirements
> document.  The operative point being that we are not really “changing” a
> cardinality, but are making a clerical correction to a diagram, albeit a
> good correction.  Good catch.****
>
> ** **
>
> ---****
>
> ** **
>
> “For example, an obvious URI for a TN resource would represent the key
> attributes as path parameters such as
> /rant/{rant}/TN/dgName/{dgName}/tn/{tn}. However, dgName is optional and
> may not have a value. We can solve this problem by using a special string
> to represent the absence of a value, or by using other types of URI
> parameters (e.g. query parameters), but I don't think it's the right way to
> go.”****
>
> ** **
>
> KJC:  Hierarchical relationships in REST URIs are “optional”.  If the
> hierarchical relationship exists then it is in the URI, if it does not
> exist, then it is not in the URI.  So a reasonable approach to resolving
> your Rest URI question is to not implement the TNs/PIs->DG relationship as
> a mandatory hierarchy where the DG “contains” the TNs/PIs.  This can be
> accomplished in at least a couple ways as follows…****
>
> ** **
>
> **1)      **Consider modeling the URI in a way that is analogous to the
> SOAP XSD;s approach, with an attribute of the TN/PI containing the DG
> relationship.    If you do that, then instead of having this:
> /rant/{rant}/TN/DGNAME/{dgName}/TN/{tn}****
>
> You’d have this:****
>
> /rant/{rant}/TN/{tn}/DG/{dgName}****
>
> Examples:  ****
>
> /rant/SomeCompany/TN/17039876543****
>
> /rant/SomeCompany/TN/13013456789/DG/NorthEast****
>
> In this approach your quandary goes away.  If there is no DG relationship,
> then that portion of the URI is just not necessary and is therefore not
> there.  Note that this is basically how the SOAP XSD design does it.****
>
> ** **
>
> **2)      **You could alternatively do it like this:****
>
> /rant/{rant}/DG/{dgName}/TN/{tn}****
>
> Examples:****
>
> /rant/SomeCompany/DG/NorthEast/TN/17039876543****
>
> /rant/SomeCompany/TN/13019876543****
>
> ** **
>
> Some TNs are “in” DGs and some are not.  There should be no issue with
> that approach either.****
>
> ** **
>
> Imo, also adding in the concept of the PI to the URL may be a valid
> addition to the URIs, since they are all just types of PIs****
>
> /rant/{rant}/PI/{PIString}/DG/{dgName}****
>
> Examples:****
>
> /rant/SomeCompany/PI/Prefix/17039****
>
> /rant/SomeCompany/PI/TN/13019876543/DG/NorthEast****
>
> /rant/SomeCompany/PI/Range/13010000000-13019999999/DG/NorthEast****
>
> /rant/SomeCompany/PI/LRN/19059876543/DG/SouthEast****
>
> ** **
>
> ---****
>
> ** **
>
> I also noticed that the text in section 3.1, bullet two, about Destination groups says “can be****
>
>       associated with one or more SED Groups”.  That should say “can be associated with zero or more SED Groups”****
>
> ** **
>
> ---****
>
> “the corInfo element should be an attribute of the PI-DG association since it is not intrisic to the PI itself”****
>
> ** **
>
> KJC:  I believe that the COR claim is intrinsic to the PI.  And putting it on an association between the PI and the DG would add further complexity to the XSD and the model.****
>
> ** **
>
> In general, I think making this change would reduce the flexibility that is in the current model, while not reducing the complexity.****
>
> ** **
>
> Thanks****
>
> ** **
>
> ** **
>
> *From:* [email-masked] [mailto:[email-masked]] *On
> Behalf Of *Mickael Marrache
> *Sent:* Wednesday, April 24, 2013 2:51 PM
> *To:* [email-masked]
> *Subject:* [drinks] Following today's meeting****
>
> ** **
>
> Hi,****
>
> ** **
>
> During the call, we agreed that the cardinality on the DG side of the
> PubId-DG association should be 0..1 instead of 0...n. We also agreed that
> this cardinality should not be interpreted as limiting a PI to be
> associated to at most one DG. However, this cardinality should be
> interpreted as limiting a PI instance to be associated to at most one DG.
> Thus, for example, the "same" telephone number may be associated to
> multiple DGs by the use of multiple TN instances. This way is made possible
> by including the dgName element as part of the key, so that for a given
> registrant and a given value (e.g. tn, tnp, start/end...), different values
> for the dgName element are allowed.****
>
> ** **
>
> I think that the dgName element should not be part of the key because it
> is optional. While it may be acceptable for a key attribute to be optional
> in some cases, I think it's relatively rare. Also, it becomes more
> difficult to define a URI for each public identifier concrete type. For
> example, an obvious URI for a TN resource would represent the key
> attributes as path parameters such as
> /rant/{rant}/TN/dgName/{dgName}/tn/{tn}. However, dgName is optional and
> may not have a value. We can solve this problem by using a special string
> to represent the absence of a value, or by using other types of URI
> parameters (e.g. query parameters), but I don't think it's the right way to
> go.****
>
> ** **
>
> What I proposed during the call was to exclude the dgName element from the
> key. So, there would be only one PI instance for a particular value, that
> is identified by the registrant that owns the PI, and the value of the PI
> (e.g. tn, tnp...). In order to allow a PI to be associated to multiple DGs,
> the maxOccurs attribute of the dgName element should be set to unbounded.
> The registrant organization would only deal with one instance for a given
> PI value. The URI for the TN resource would then be /rant/{rant}/TN/{tn}.*
> ***
>
> ** **
>
> Concerning the carrier-of-record concern, the question is: Is there a
> meaning to let a registrant organization provision the same PI (in terms of
> value) with different COR information? The current model allows such a
> feature by the use of multiple PI instances (thus, allowing multiple
> corInfos). If this is a real use case, the corInfo element should be an
> attribute of the PI-DG association since it is not intrisic to the PI
> itself but depends on an external factor (in this case, the association
> with a particular DG). Creating a new complex type DestGrpRefType that
> includes the DG key and the corInfo element would solve this issue. The
> list of dgName (ObjNameType) would become a list of dgRefs (DestGrpRefType).
> ****
>
> ** **
>
> Not related to this question, there are two other points I raised in the
> mailing list:****
>
>    1. The framework document states: "If the response to the Get
>    operation includes object(s) that extend the BasicObjType, the Registry
>    MUST include the 'cDate' and 'mDate', if applicable.". In the examples
>    section in the SOAP document (section 10), for the Get examples, the
>    elements cDate and mDate are not part of the returned responses.****
>    2. According to the framework document, an egress route is added by
>    the originating SSP to the registry. The originating SSP must be a peering
>    organization of the SED group to which the egress route is associated.
>    Thus, an egress route is an element owned by the originating SSP. The rant
>    field of the egress route would then identify the originating SSP and not
>    the owner of the SED group. Also, in the SOAP document in section 10.17,
>    the rant field has the value iana-en:111 as expected. There is an error in
>    the SOAP document in section 10.11. The rant field has the value
>    iana-en:222 where it should have the value iana-en:111 that identifies SSP1.
>    ****
>
>  ** **
>
> Also, a new version of the REST draft is available at
> http://tools.ietf.org/html/draft-marrache-drinks-spp-protocol-rest-02. It
> would be great if you can take a look at it and comment.****
>
> ** **
>
> Thanks,****
>
> Mickael****
>
> ------------------------------
> are not the intended recipient, please contact the sender by reply e-mail
> and destroy all copies of the original message.
>
>

---

From: "Cartwright, Ken" <[email-masked]>
Date: Thu, 9 May 2013 10:36:00 -0400

Ok.  My apologies if I "didn't answer the key question" in the way you wanted.  I think I responded directly to your points.  And I think that the URL structures that I propose are very clean and intuitive, not complicated or esoteric.  You did not say anything about "optional parameters" until this reply.  So perhaps I can now speak to that question now that you have posed it.  The model in the doc is what it is, if the group decides to change it, then so be it.  But, SOAP has no issue dealing with it and I believe that Rest has no real issue dealing with it either, and as I stated I think the resulting URL structure is very clear and simple.  I also do not really see this as an "optional parameter" type situation.  The example in the link you describe was speaking to someone wanting to put a "format" selection in the main body of the output URL path so that they know if it is XML or JSON or etc.  The situation here is more of including a  hierarchical relationship as part of the URL path, which is done all the time.  And of course not all objects in a model will always have the same hierarchical relationships.

But, that's my $.02.  Take it fwiw.  :)

Ken

From: Mickael Marrache [mailto:[email-masked]]
Sent: Thursday, May 09, 2013 10:14 AM
To: Cartwright, Ken; [email-masked]
Subject: Re: [drinks] Following today's meeting

Hi,

Concerning the first point, this is what I meant. I just explained the current approach as a prerequisite for the next part.

Firstly, using optional path parameters introduces an implementation issue. Also, JAX-RS, which will probably be the most used solution for implementing SPPP over REST in Java, does not support easily optional parameters (see http://www.nakov.com/blog/2009/07/15/jax-rs-path-pathparam-and-optional-parameters/). There are workarounds to this "issue" but this lack of support shows this is a rare way of defining URIs in REST. Optional path parameters are generally discouraged in REST.

I think the real question is why to include the name of the destination group as part of the PI key, not how to represent optional path parameters in REST. Also, I don't see how excluding the dgName from the PI key would reduce flexibility of the model. On the other hand, I think that including the dgName as part of the PI key increases complexity of RESTful implementations for the reasons I mentioned in the previous paragraph. Also, I think that defining two URI templates for PIs (one for PIs that are part of DGs and another for PIs that are not part of DGs) makes the REST API less intuitive for the clients, and adds complexity for implementors. I don't really see enough advantages with the current model, that would convince me to accept this implementation complexity.

Concerning the COR aspect, it's only a question we raised during the last meeting. I agree that the COR is intrinsic to the PI, so we don't need to move it at the PI-DG association level.

Thanks,
Mickael
On Thu, May 9, 2013 at 3:56 PM, Cartwright, Ken <[email-masked]<mailto:[email-masked]>> wrote:
Hi,

---

---

---

Thanks

From: [email-masked]<mailto:[email-masked]> [mailto:[email-masked]<mailto:[email-masked]>] On Behalf Of Mickael Marrache
Sent: Wednesday, April 24, 2013<tel:2013> 2:51 PM
To: [email-masked]<mailto:[email-masked]>
Subject: [drinks] Following today's meeting

Hi,

Thanks,
Mickael

---

From: "Bhatia, Vikas" <[email-masked]>
Date: Thu, 9 May 2013 11:00:55 -0400

W.r.t the following two points from the email below

===

For #1 - "cDate" is part of all GET examples (http://tools.ietf.org/html/draft-ietf-drinks-spp-protocol-over-soap-03.txt). "mDate" is an optional parameter that comes only if the record has been modified. The framework document section 7.3 says "the Registry MUST include the 'cDate' and 'mDate',   if applicable.", "if applicable" is key.
For #2 - Its just an example and each example can be seen in isolation. The document does not state that SSP1 has registrant ID "iana-en:11" always.

Thanks,
Vikas

Hi,

Thanks,
Mickael

---

From: "Cartwright, Ken" <[email-masked]>
Date: Fri, 10 May 2013 14:38:54 -0400

And not that I've given the REST mapping any deep thought, but the more I think about it, the more it seems to me that the below is clear/simple/good and would support what the model says should be supported.  I also see no reason why a Rest implementation would have issues with this (in fact it looks like vanilla Rest to me).  There are many examples in the real world of needing to work with objects that reside inside _and_ outside of some hierarchical container/collection.  Rest certainly supports that very easily.  I can also think of a couple other approaches and variations of the approach below that also make sense.  Given this, I can't see a  reason why the Rest question that arose would necessitate a change to the model.

//How to list and get one or more rants - but this may or may not not be a feature that is supported

sppapi.example.com/rants/{rantIdentifier}
sppapi.example.com/rants

//For a given Rant, how to list and get one or more of the Dest Groups

sppapi.example.com/rants/{rantIdentifier}/destGroups/{destGroupIdentifier}
sppapi.example.com/rants/{rantIdentifier}/destGroups

//For a given Rant, how to list and get one or more PIs/TNs associated with (in) a Dest Group

sppapi.example.com/rants/{rantIdentifier}/destGroups/{destGroupIdentifier}/TNs/{tnIdentifier}
sppapi.example.com/rants/{rantIdentifier}/destGroups/{destGroupIdentifier}/TNs

//For a given Rant, how to list and get one or more PIs/TNs not associated with (not in) a Dest Group

sppapi.example.com/rants/{rantIdentifier}/TNs/{tnIdentifier}
sppapi.example.com/rants/{rantIdentifier}/TNs

//For a given Rant, how to list and get one or more SEDGroups

sppapi.example.com/rants/{rantIdentifier}/SEDGroups/{sedGroupIdentifier}
sppapi.example.com/rants/{rantIdentifier}/SEDGroups

//etc, etc for other object types

From: Cartwright, Ken
Sent: Thursday, May 09, 2013 10:36 AM
To: 'Mickael Marrache'; [email-masked]
Subject: RE: [drinks] Following today's meeting

Ken

From: Mickael Marrache [mailto:[email-masked]]
Sent: Thursday, May 09, 2013 10:14 AM
To: Cartwright, Ken; [email-masked]<mailto:[email-masked]>
Subject: Re: [drinks] Following today's meeting

Hi,

Thanks,
Mickael

---

---

---

Thanks

Hi,

Thanks,
Mickael