The Use of Plural Nouns in restful Transactions

Topics: Resources, REST
Coordinator
Mar 5, 2016 at 6:10 PM
I wanted to get a thread started about plurals. How should we use them within ACORD Resource Standard.

Use plural nouns

Do not mix up singular and plural nouns. Keep it simple and use only plural nouns for all resources.
/vehicles instead of /vehicle
/parties instead of /party
/coverages instead of /coverage
/locations instead of /location
Developer
May 15, 2016 at 10:27 PM
It makes sense to use vehicles, parties, locations etc. Here is a sample request for an address cleanse service that we are thinking about. We also have a need to track each request so including a UUID is needed for us while sending a full payload to a SOAP or REST end point.

<ACORD>
<LocationRq>
    <RqUID>f81d4fae-7dec-11d0-a765-00a0c91e6bf6</RqUID>
    <BusinessPurposeTypeCd>AddressCleanse</BusinessPurposeTypeCd>
    <Locations>
        <Location>
            <Addr id="A001">
                <Addr1>4500 Main Street</Addr1>
                <Addr2>Suite 100-A</Addr2>
                <City>Houston</City>
                <StateProvCd>TX</StateProvCd>
                <PostalCode>78900</PostalCode>
            </Addr>
        </Location>
        <Location>
            <Addr id="A002">
                <Addr1>4502 Main Street</Addr1>
                <Addr2>Suite 100-A</Addr2>
                <City>Houston</City>
                <StateProvCd>TX</StateProvCd>
                <PostalCode>78900</PostalCode>
            </Addr>
        </Location>
        <Location>
            <Addr id="A003">
                <Addr1>4506 Main Street</Addr1>
                <Addr2>Suite 100-A</Addr2>
                <City>Houston</City>
                <StateProvCd>TX</StateProvCd>
                <PostalCode>78900</PostalCode>
            </Addr>
        </Location>
    </Locations>
</LocationRq>
</ACORD>
Developer
May 16, 2016 at 1:31 PM
Nathan - I agree that plural nouns are the proper way to go for resource urls. You can also find some other best practices here: http://blog.mwaysolutions.com/2014/06/05/10-best-practices-for-better-restful-api/ (#3 is specifically what you state.)

niluhitu - What exactly is the purpose of the <Locations> aggregate in your example? It seems like an unnecessary wrapper.

Thinking specifically of the JAXB representation and accessing the first location from the Rq would look like this:

locationRq.getLocations().getLocation.get(0);

Making the single location aggregate name <Locations> seems odd when looking at the XML but JAXB provides it like this:

locationRq.getLocations.get(0);

The best way to correct this would be to use <Location> in the XML and use the JAXB annotations to link a Locations list to that XML aggregate.

There is a lot of conflicting information about wrapping data sets, but Google's style guide recommends to not wrap repeating elements simply for the sake of wrapping them: https://google.github.io/styleguide/xmlstyle.html

5.2: XML elements that merely wrap repeating child elements SHOULD NOT be used.
Developer
May 26, 2016 at 12:42 PM
Matt, niluhitu is Nila:)

I see what you are saying from JAXB perspective. If we use some sort of parent tag such as ACORD that wraps multiple instances of Location aggregates then it makes to remove Locations plural. If resource message is not supposed to have a wrapper then we would want a plural and response could be. We will talk this internally as well.

<Locations>
    <Location>
        <Addr id="A001">
            <Addr1>4500 Main Street</Addr1>
            <Addr2>Suite 100-A</Addr2>
            <City>Houston</City>
            <StateProvCd>TX</StateProvCd>
            <PostalCode>78900</PostalCode>
        </Addr>
    </Location>
    <Location>
        <Addr id="A002">
            <Addr1>4502 Main Street</Addr1>
            <Addr2>Suite 100-A</Addr2>
            <City>Houston</City>
            <StateProvCd>TX</StateProvCd>
            <PostalCode>78900</PostalCode>
        </Addr>
    </Location>
</Locations>
Developer
May 26, 2016 at 12:51 PM
Edited May 26, 2016 at 12:51 PM
Hey Nila,

I think I got confused in the way the XML was setup in the original post - there appears to be <ACORD> wrappers around the code block.

Regardless, I think the wrapper concept is required and needed for a RESTful interface when returning a list of aggregates (as is done in your latest example.) I would not want wrappers inside the ACORD schema to wrap anywhere a list of elements exists.
Coordinator
Aug 2, 2016 at 1:40 PM
Edited Sep 15, 2016 at 6:31 PM
Hi Folks,

I'm going to suggest that we use a simple <Resources> aggregate for returning repeating data sets in XML.

The current schema does not contain any plural aggregates and it would take a enormous amount of work to refactor them into the schema.

So far the only use case for them has been when "All Vehicles" or "All Policies", etc... are returned. This can easily be satisfied with the below XML:
<?xml version="1.0" encoding="UTF-8"?>
<Resources>
    <Vehicle>
        <Manufacturer>BMW</Manufacturer>
        <Model>325</Model>
        <ModelYear>2005</ModelYear>
        <VehBodyTypeCd>SEDAN</VehBodyTypeCd>
        <Registration>
            <RegistrationId>213123</RegistrationId>
            <StateProvCd>MA</StateProvCd>
        </Registration>
        <CostNewAmt>
            <Amt>32000</Amt>
        </CostNewAmt>
    </Vehicle>
    <Vehicle>
        <Manufacturer>FORD</Manufacturer>
        <Model>F150</Model>
        <ModelYear>2006</ModelYear>
        <VehBodyTypeCd>TRUCK</VehBodyTypeCd>
        <Registration>
            <RegistrationId>941263</RegistrationId>
            <StateProvCd>MA</StateProvCd>
        </Registration>
        <CostNewAmt>
            <Amt>62000</Amt>
        </CostNewAmt>
    </Vehicle>
</Resources>

Coordinator
Aug 2, 2016 at 1:41 PM
That being said - I would definitely like to continue the conversation around plurals in URLs...