Naming conventions

URI's

API URI's are based around resources. Actions are indicated with the use of HTTP Methods.

• Use nouns, not verbs
• Resources that are collections should be indicated using plural nouns
  e.g. /pathways
• Specific resource in collection is defined after collection (generally with id)
  e.g. /pathways/{id}
• Resources of which only one instance can exist should be indicated using singular noun
  e.g. /pathways/{id}/favourite
• Related/Linked resources are defined after specific resource (recursive - refer to above)
  e.g. /pathways/{nodeId}/steps, /pathways/{nodeId}/steps/{stepId}, /pathways/{nodeId}/steps/{stepId}/progress

Microsoft Documentation: Organize the API around resources.

Code

Decorate actions and controllers according to resource path and applicable version(s).

Controllers

[ApiRoute("TrainingRequirements")]
public class TrainingRequirementsController : ApiBaseController
{
    //code logic
}

Actions

[ApiRoute("LearningPortal/Pathways/{nodeId:int}")]
public NodeStructure GetPathway(int nodeId)
{
    //code logic
}


[ApiRoute("LearningPortal/Pathways/{nodeId:int}/Favourite")]
public bool GetFavourite(int nodeId)
{
    //code logic
}

[ApiRoute("LearningPortal/Pathways/{nodeId:int}/Steps/{stepId:int}", AcceptedVersions = new[] { 1, 2 })]
public StepStructure GetPathwayStep(int nodeId, int stepId)
{
    //code logic
}

[ApiRoute("LearningPortal/Pathways/{nodeId:int}/Steps/{stepId:int}", StartingVersion = 3)]
public StepStructureV3 GetPathwayStepV3(int nodeId, int stepId)
{
    //code logic
}