Route Name (URI)
Last updated
Last updated
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.
API Versioning
URI Path
Query String Parameters
HTTP Verb
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.
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.
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".
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.
