Link#Title in getDomains() returns same value as Link#HREF

[DemianTinkiel]

I was looking at getDomains, specially in reference to authzforce/java-xacml-sdk#17 and I noticed that getDomains returns something like

GET http://localhost:8082/authzforce-ce/domains/

HTTP/1.1 200 
Date: Mon, 18 May 2020 19:01:52 GMT
Content-Type: application/xml
Content-Length: 540

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:resources xmlns="http://www.w3.org/2005/Atom" xmlns:ns2="http://authzforce.github.io/rest-api-model/xmlns/authz/5" xmlns:ns3="http://authzforce.github.io/core/xmlns/pdp/6.0"
               xmlns:ns4="urn:oasis:names:tc:xacml:3.0:core:schema:wd-17">
  <link rel="item" href="HJW2dLuXEemloQJCrBsAAw" title="HJW2dLuXEemloQJCrBsAAw"/>
  <link rel="item" href="SV4T35k1EeqozAJCrBDuBQ" title="SV4T35k1EeqozAJCrBDuBQ"/>
</ns2:resources>

yet getDomains/{domainID}

returns something like

GET http://localhost:8082/authzforce-ce/domains/SV4T35k1EeqozAJCrBDuBQ

HTTP/1.1 200 
Date: Mon, 18 May 2020 19:16:31 GMT
Content-Type: application/xml
Content-Length: 736

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domain xmlns="http://authzforce.github.io/rest-api-model/xmlns/authz/5" xmlns:ns2="http://www.w3.org/2005/Atom" xmlns:ns3="http://authzforce.github.io/core/xmlns/pdp/6.0"
        xmlns:ns4="urn:oasis:names:tc:xacml:3.0:core:schema:wd-17">
  <properties externalId="myTestDomain1">
    <description>test domain</description>
  </properties>
  <childResources>
    <ns2:link rel="item" href="/properties" title="Domain properties"/>
    <ns2:link rel="item" href="/pap" title="Policy Administration Point"/>
    <ns2:link rel="http://docs.oasis-open.org/ns/xacml/relation/pdp" href="/pdp" title="Policy Decision Point"/>
  </childResources>
</domain>

Is this by design? I guess I expected the response of getDomains to be something like

 <link rel="item" href="SV4T35k1EeqozAJCrBDuBQ" title="myTestDomain1"/>

[cdanger]

Yes, this is by design. The purpose of title is different from externalId. So far, the title is set always to the domain ID like href and therefore mostly useless. Now that you ask - yes, your question is relevant - I will probably remove it to avoid the confusion. The original intent was to keep the API as minimal as possible, and let the API consumer - a User Interface of any kind for instance - handle all the display names, description, etc. in its own database, and make the link with AuthzForce API's domain via the externalId. So if I follow this approach, I should probably remove the description property as well. Not sure anymore why it has been there originally.

[DemianTinkiel]

I guess I should have asked when I was doing authzforce/java-xacml-sdk#17 . As the doDomainIdTranslation becomes nearly useless if you don't already know the domain names. I was hoping to be able to do domain discovery without doing extra steps like

 adminXacmlSdk.getDomains().forEach(link -> {
            try {
                domains.put(adminXacmlSdk.getDomain(link.getHref()).getExternalId(), link.getHref());
            } catch (XacmlSdkException e) {
                LOG.error("Error listing domains ", e);
            }
        });

getDomains(externalID) works with the human-readable name, while getDomain(STRING) only works with the id/href unless you use the doDomainIdTranslation.

I understand wanting to keep the API concise, so description probably doesn't make sense but title can still have a use within HATEOS.

Anyway, thanks for clearing it out. Shall I close this or do you want to use it to track the removal of title & description?

[cdanger]

Keep this open, I will look at how title is used in HATEOAS, and check whether it is worth keeping it (and make it configurable via API like other domain properties).