Closed tomkerkhove closed 6 years ago
The sentence is not really clear there are two points here:
1) The api name is singular Don't : https://your-api-name-plural.domain.com/v1/controller Do : https://your-api-name-singular.domain.com/v1/controller
2) The API prefix is useless Don't : https://your-api-name-singular.domain.com/api/v1/controller or https://api.domain.com/api/your-api-name-singular/v1/controller (duplication) or https://data.domain.com/api/your-api-name-singular/v1/controller (what does the "api" word bring to the URL?)
Do :
https://your-api-name-singular.domain.com/v1/controller (the api name is in the base, in case u have a common domain per API)
or
https://api.domain.com/your-api-name-singular/v1/controller (the api name is explicit)
e.g. https://api.domain.com/master-data/v1/controller https://api.domain.com/hr/v1/controller
This is the full guidance we have now:
- The API name is a singular concept and the 'api' prefix does not provide an added value
- Don't - api/v1/users/{id}/profile
- Do - https://master-data.contoso.com or https://api.contoso.com/master-data
I'll make sure that this is seperated to reflect this.
However, can you provide an example where using api in the uri path is ok, for example this?
https://codit.eu/api/v1/users
?
I am ok to use API word if really necessary. For example if you have a solution called CDS, that exposes a web interface, a rest api and a soap service, i am ok with the config:
Regarding your example, what is the API name? the API name comes always before the version (v1)
so in your example, the api name is API, users is the controller. This is fine if you are exposing a single api.
But how do you compose your URL when you have more APIs?
https://codit.eu/api/v1/users
That's a good point, let me send a PR in one of the next days and see what you think.
Current guidelines mention the following:
Why is that exactly?