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
}