Route Name (URI)

The route URI is the entry point in which the client will use to initiate the request for a desired resource. There are 4 considerations when it comes to planning for the URI path.

1. API Versioning

2. URI Path

3. Query String Parameters

4. HTTP Verb

The anatomy of an HTTP request.

API Versioning

We talked about API versioning strategies under chapter 3, Versioning Strategies. Whichever strategy(ies) you decide to implore, make to specify it clearly in the design doc.

For me personally, I have always used the URI prefixing approach like this: https://example.com/api/v1.

URI Path

Next is the URI path itself. Make sure to design the URIs by following the best practices and guidelines mentioned in chapter 3, URI Design. Also, make sure to make them as RESTful as possible whilst being as pragmatic as possible.

Query String Parameters

Similar to the above, try following the best practices mentioned in the URI Query Design section of chapter 3. Make sure to remember that query strings are used mainly as optional parameters.

The final result of your decision should be something like this:

GET /api/v1/users?page=1&limit=10

Which should be very intuitive as it translates to "retrieve a list of the first 10 users in the application".

HTTP Verb

Similar to the above, try following the best practices mentioned in chapter 3, Method Verbs. Make sure to always utilize the verbs as much as possible without naming the URIs as actions or functional APIs.