REST API guidelines from Microsoft

REST API guidelines from Microsoft

This article notes some REST API guidelines from Microsoft (they are applicable to other tech stacks too, such as Python FastAPI). The Microsoft article has further guidelines, this article presents a selection.

Organize the API design around resources

- when designing the URL paths, think in terms of 'objects' rather than verbs

Examples:

https://adventure-works.com/orders // Good

https://adventure-works.com/create-order // Avoid

ref: Web API design best practices - Azure Architecture Center | Microsoft Learn

Define API operations in terms of HTTP methods

- use GET and POST appropriately

- combine with URL 'paths' to model the hierarchy of objects

Examples:

/customers -> GET = Get all customers, POST = Create a new customer

/customers/1 -> GET = Get customer 1

/customers/1/orders -> GET = Get all orders for customer 1, POST = Create a new order for customer 1

Source

- Web API design best practices - Azure Architecture Center | Microsoft Learn