Apply the best pratices on naming fields on API objects

[Arthurvdv]

When creating API endpoints I tent to expose the "No." fields as number, with the idea that whoever consumes the API does not know the inner workings of Business Central and that there no possible ambiguity between No (boolean) and Number.

For Example:

query 54342 "Calendar Entry Api VRA"
{
    QueryType = API;
    APIPublisher = 'myPublisher';
    APIGroup = 'myGroup';
    APIVersion = 'v1.0';
    EntityName = 'calendarEntry';
    EntitySetName = 'calendarEntries';

    elements
    {
        dataitem(Calendar_Entry; "Calendar Entry")
        {
            column(no; "No.") { }                          // column(number; "No.") { }
            column(workCenterNo; "Work Center No.") { }    // column(workCenterNumber; "Work Center No.") { }
        }
    }
}

This is inspired by the way Microsoft has created the default API's: https://github.com/StefanMaron/MSDyn365BC.Code.History/blob/b7f963bfbf1ca844150d40bd13062c8a3d8e5cd9/APIV2/Source/_Exclude_APIV2_/src/pages/APIV2Accounts.Page.al#L34

I'm thinking of having a rule to apply the best pratices on naming.
The difficulty here is to have this a generic as possible, I think these rules below could always be applied?

Field Name	Exposed Name
Rec.SystemId	id
Rec.SystemModifiedAt	lastModifiedDateTime
Rec.Name	displayName
Rec."No."	number
Rec."My Field No."	myFieldNumber

[jwikman]

I love it!

You might also want to check out other recommendations for API pages, as documented on https://alguidelines.dev/docs/bestpractices/api-page/ ?
Don't know if they should be implemented as different rules, though?

Some examples:

• Use camelCasing for names (and not DisplayName as in your example above 😉)
  • Also on page properties EntitySetName and EntityName
• Always add ODataKeyFields with SystemId as value.
• Mandatory fields: SystemId and SystemModifiedAt (but with your proposed naming)

[Arthurvdv]

You might also want to check out other recommendations for API pages, as documented on https://alguidelines.dev/docs/bestpractices/api-page/

Briljant suggestion and great content to build some rules on this!

Don't know if they should be implemented as different rules, though?

With the current way of Code Analyzers work with Business Central, we need to have a certainly level of granularity, so everybody can set the severity (None, Info, Warning, Error) as they see best fit.

Use camelCasing for names (and not DisplayName as in your example above 😉)

That's a typo! 😳 (fixed now)

[jwikman]

Yes, several rules for those sounds as a good approach. 👍

[Arthurvdv]

I believe I count nine possible rules:

• LC00xx: Set property DelayedInsert to True on editable API page
• LC00xx: Set property ODataKeyFields with SystemId field
• LC00xx: Mandatory field 'SystemId' is missing
• LC00xx: Mandatory field 'SystemModifiedAt' is missing
• LC00xx: Give fields a more describing name: id for field SystemId
• LC00xx: Give fields a more describing name: lastModifiedDateTime for field SystemModifiedAt
• LC00xx: Give fields a more describing name: number for field No.
• LC00xx: Give fields a more describing name: displayName for field Name
• LC00xx: The property ApplicationArea does not play a role in API pages, so it can be skipped

[jwikman]

I thought you forgot the camelCase rule, but just realized that AA010x handles those already.
I believe that you covered all I can think of! 👍

I guess you already thought that the rule "number for field No." to cover names where "No." a part of the name.
"No." -> number
"Customer No." -> customerNumber
"Maximum No. of Attempts" -> maximumNumberOfAttempts
etc.

[jwikman]

Btw, AZ AL Dev Tools has a nice feature when you create API pages, as mentioned in anzwdev/al-code-outline#528 (comment), so you do get the naming above by auto-magic 🙂
Maybe worth to mention in the WIKI for the new rule?