February 12, 2016

CRM 2016 Web API and plural names

The new Web API available for CRM 2016 is based on OData V4 protocol and the endpoint is /api/data/v8.0/

The MSDN contains several examples of the new endpoint, for example if we want to retrieve the top 3 accounts:


Simple, right? if you want to retrieve from account entity you write accounts, if you want to retrieve from contact entity you write contacts, if you want to retrieve from opportunity entity you write opportunities. You write the plural.

What a poor choice to use the plural form instead of the singular one, and let me say something, the root of the problem is an English-centered vision.

I'm not an expert of REST and OData protocols, maybe they suggest to use the plural forms but when you let users dynamically add entries to the endpoint (i.e. creating an entity) the use of plural forms is a mess.

A user on Dynamics Community asked a question: "my custom entity name is xxx_settings and I can't query using the endpoint /api/data/v8.0/xxx_settingss, which is the right syntax?"

Well, in this case the answer is simple, who designed the API decided to apply the exceptions, so if the noun ends with s the plural is es, in the user's case the correct endpoint is /api/data/v8.0/xxx_settingses, but if you want to be sure about the name you can check the metadata at this url: /api/data/v8.0/ or download the XML from the Developer Resources inside CRM UI.

Now let's play a game, how much are robust the exceptions they implemented in order to create the plural form? The answer is weak.
English is not my first language so I googled "plural exceptions english" and I landed in this page: A handout on irregular plural noun forms. I started to create some custom entities, here some results:
new_city become new_cities, English correct.
new_wolf become new_wolfs, English incorrect.
new_knife become new_knifes, English incorrect.
new_man become new_mans, English incorrect.

Now, I don't expect that all the irregular forms are covered, but if you decide to handle the final 's' and the final 'y' why not handle the final 'f'? However not big deal, You check the metadata and you can find the exact plural word to use.

BUT, and there is a BUT

Let's say we created our custom entity new_city and now the REST endpoint responds to /api/data/v8.0/new_cities, what will happen if we create a custom entity called new_citie?
The entity is not listed inside the REST endpoint!!! because the plural of new_citie is new_cities but it's already used by new_city.
The lesson is: pay attention when you name your entities if you need to query them using the new REST endpoint, if the plural form of a new entity is the same of the plural form of a previous entity, you can't query it.


  1. It gets even worse if you read that these LogicalCollectionNames can be changed by request:

    Change the name of an entity set
    By default, the entity set name matches the EntityMetadata EntityType LogicalCollectionName (EntityMetadataLogicalCollectionName) property value. If you have a custom entity that you want to address using a different entity set name, you can update the EntityMetadata EntityType EntitySetName (EntityMetadata.EntitySetName) property value to use a different name.
    Source: https://msdn.microsoft.com/de-de/library/mt607990.aspx#bkmk_entityTypes

    It would be nice to have an endpoint with a small footprint to get a LogicalCollectionName for a normal LogicalName.

    1. In a sense it's worse because after you code to a specific name, someone could change it. But in another sense, it means that if you don't like the name it generates by default, you can change it BEFORE you start writing code.

  2. I've been getting "Resource not found for the segment xyz" and wasn't even sure how to deal with custom entities until you mentioned that it uses the plural form. This is so silly, I couldn't think something like this would be the cause of my error.
    Thanks for the insight.

  3. Thank you, very useful information!

  4. I just ran into this problem as well... what a headache! Thanks for posting this info so I can get on with the REST endpoint of my life :)

  5. As 'Unknown' mentioned above, if you don't like the default-generated plural, you can fix it before you write any code. https://msdn.microsoft.com/de-de/library/mt607990.aspx#bkmk_entityTypes - so although it is somewhat annoying, and I prefer the Set notation, it can be addressed in a supported fashion, and will probably only cause a problem the first time you see it, because after that, you'll know what to do right away.

  6. Excelent post! Just dealing with a custom entity plural name. (Using an old CRM, but still a problem). Thanks Guido!